Merge pull request #202300 from jeanbisutti/java_runtime_attach

Add Java runtime attachment feature for Spring Boot

Author: v-ccolin

articles/azure-monitor/app/java-in-process-agent.md

@@ -60,6 +60,9 @@ Add `-javaagent:path/to/applicationinsights-agent-3.3.0.jar` to your application
 > [!TIP]
 > For help with configuring your application's JVM args, see [Tips for updating your JVM args](./java-standalone-arguments.md).
 
+> [!TIP]
+> If you develop a Spring Boot application, you can replace the JVM argument by a programmatic configuration. More [here](./java-spring-boot.md).
+
 #### Set the Application Insights connection string
 
 1. There are two ways you can point the jar file to your Application Insights resource:

articles/azure-monitor/app/java-spring-boot.md

@@ -0,0 +1,73 @@
+---
+title: Configure Azure Monitor Application Insights for Spring Boot
+description: How to configure Azure Monitor Application Insights for Spring Boot applications
+ms.topic: conceptual
+ms.date: 06/22/2022
+ms.devlang: java
+ms.custom: devx-track-java
+---
+
+# Configure Azure Monitor Application Insights for Spring Boot
+
+You can enable the Azure Monitor Application Insights agent for Java by adding an argument to the JVM. When you can't do this, you can use a programmatic configuration. We detail these two configurations below. 
+
+## Addition of a JVM argument 
+
+### Usual case
+
+Add the JVM arg `-javaagent:path/to/applicationinsights-agent-3.3.0.jar` somewhere before `-jar`, for example:
+
+```
+java -javaagent:path/to/applicationinsights-agent-3.3.0.jar -jar <myapp.jar>
+```
+
+### Spring Boot via Docker entry point
+
+If you're using the *exec* form, add the parameter `"-javaagent:path/to/applicationinsights-agent-3.3.0.jar"` to the parameter list somewhere before the `"-jar"` parameter, for example:
+
+```
+ENTRYPOINT ["java", "-javaagent:path/to/applicationinsights-agent-3.3.0.jar", "-jar", "<myapp.jar>"]
+```
+
+If you're using the *shell* form, add the JVM arg `-javaagent:path/to/applicationinsights-agent-3.3.0.jar` somewhere before `-jar`, for example:
+
+```
+ENTRYPOINT java -javaagent:path/to/applicationinsights-agent-3.3.0.jar -jar <myapp.jar>
+```
+
+## Programmatic configuration
+
+To use the programmatic configuration and attach the Application Insights agent for Java during the application startup, you must add the following dependency.
+```xml
+<dependency>
+    <groupId>com.microsoft.azure</groupId>
+    <artifactId>applicationinsights-runtime-attach</artifactId>
+    <version>3.3.0</version>
+</dependency>
+```
+
+And invoke the `attach()` method of the `com.microsoft.applicationinsights.attach.ApplicationInsights` class.
+
+> [!TIP]
+> ⚠ The invocation  must be requested at the beginning of the `main` method.
+
+Example:
+
+```java
+@SpringBootApplication
+public class SpringBootApp {
+
+  public static void main(String[] args) {
+    ApplicationInsights.attach();
+    SpringApplication.run(SpringBootApp.class, args);
+  }
+}
+```
+
+If you want to use a JSON configuration: 
+* The `applicationinsights.json` file has to be in the classpath
+* Or you can use an environmental variable or a system property, more in the _Configuration file path_ part on [this page](../app/java-standalone-config.md).
+
+
+> [!TIP]
+> With a programmatic configuration, the `applicationinsights.log` file containing the agent logs is located in the directory from where the JVM is launched (user directory). This default behavior can be changed (see the _Self-diagnostics_ part of [this page](../app/java-standalone-config.md)).

articles/azure-monitor/app/java-standalone-arguments.md

@@ -16,25 +16,7 @@ Configure [App Services](../../app-service/configure-language-java.md#set-java-r
 
 ## Spring Boot
 
-Add the JVM arg `-javaagent:path/to/applicationinsights-agent-3.3.0.jar` somewhere before `-jar`, for example:
-
-```
-java -javaagent:path/to/applicationinsights-agent-3.3.0.jar -jar <myapp.jar>
-```
-
-## Spring Boot via Docker entry point
-
-If you're using the *exec* form, add the parameter `"-javaagent:path/to/applicationinsights-agent-3.3.0.jar"` to the parameter list somewhere before the `"-jar"` parameter, for example:
-
-```
-ENTRYPOINT ["java", "-javaagent:path/to/applicationinsights-agent-3.3.0.jar", "-jar", "<myapp.jar>"]
-```
-
-If you're using the *shell* form, add the JVM arg `-javaagent:path/to/applicationinsights-agent-3.3.0.jar` somewhere before `-jar`, for example:
-
-```
-ENTRYPOINT java -javaagent:path/to/applicationinsights-agent-3.3.0.jar -jar <myapp.jar>
-```
+Read the Spring Boot documentation [here](../app/java-in-process-agent.md).
 
 ## Tomcat 8 (Linux)
 
@@ -112,7 +94,7 @@ Add `-javaagent:path/to/applicationinsights-agent-3.3.0.jar` to the existing `jv
 ...
 ```
 
-If you are running multiple managed servers on a single host, you will need to add `applicationinsights.agent.id` to the `system-properties` for each `server`:
+If you're running multiple managed servers on a single host, you'll need to add `applicationinsights.agent.id` to the `system-properties` for each `server`:
 
 ```xml
 ...
@@ -134,7 +116,7 @@ If you are running multiple managed servers on a single host, you will need to a
 ...
 ```
 
-The specified `applicationinsights.agent.id` value must be unique. It is used to create a subdirectory under the applicationinsights directory, as each JVM process needs its own local applicationinsights config and local applicationinsights log file. Also, if reporting to the central collector, the `applicationinsights.properties` file is shared by the multiple managed servers, and so the specified `applicationinsights.agent.id` is needed to override the `agent.id` setting in that shared file. `applicationinsights.agent.rollup.id` can be similarly specified in the server's `system-properties` if you need to override the `agent.rollup.id` setting per managed server.
+The specified `applicationinsights.agent.id` value must be unique. It's used to create a subdirectory under the application insights directory, as each JVM process needs its own local application insights config and local application insights log file. Also, if reporting to the central collector, the `applicationinsights.properties` file is shared by the multiple managed servers, and so the specified `applicationinsights.agent.id` is needed to override the `agent.id` setting in that shared file. `applicationinsights.agent.rollup.id` can be similarly specified in the server's `system-properties` if you need to override the `agent.rollup.id` setting per managed server.
 
 
 ## Jetty 9
@@ -171,7 +153,7 @@ Go to **servers > WebSphere application servers > Application servers**, choose
 ```
 Java and Process Management > Process definition >  Java Virtual Machine
 ```
-In "Generic JVM arguments" add the following:
+In "Generic JVM arguments" add the following JVM argument:
 ```
 -javaagent:path/to/applicationinsights-agent-3.3.0.jar
 ```
@@ -187,4 +169,4 @@ Create a new file `jvm.options` in the server directory (for example `<openliber
 
 ## Others
 
-Please see your application server documentation on how to add JVM args.
+See your application server documentation on how to add JVM args.

articles/azure-monitor/toc.yml

@@ -908,6 +908,8 @@ items:
         items:
         - name: Overview
           href: app/java-in-process-agent.md
+        - name: Spring Boot
+          href: app/java-spring-boot.md
         - name: Configuration options
           href: app/java-standalone-config.md
         - name: Advanced configurations