Merge pull request #235007 from jeanbisutti/ai-java-improvement

Application Insights Java doc improvement

Author: v-regandowner

.openpublishing.redirection.json

@@ -22547,6 +22547,11 @@
             "source_path_from_root": "/articles/principles-for-ai-generated-content.md",
             "redirect_url": "https://aka.ms/ai-content-principles",
             "redirect_document_id": false
-        } 
+        },
+        {
+          "source_path_from_root": "/articles/azure-monitor/app/java-standalone-arguments.md",
+          "redirect_url": "/azure/azure-monitor/app/java-get-started-supplemental",
+          "redirect_document_id": true
+        }
     ]
 }

articles/azure-monitor/app/java-standalone-arguments.md renamed to articles/azure-monitor/app/java-get-started-supplemental.md

@@ -1,14 +1,16 @@
 ---
-title: Add the JVM arg - Application Insights for Java
-description: Learn how to add the JVM arg that enables Application Insights for Java.
+title: Application Insights with containers
+description: This article shows you how to set-up Application Insights
 ms.topic: conceptual
-ms.date: 03/31/2023
+ms.date: 04/06/2023
 ms.devlang: java
 ms.custom: devx-track-java
 ms.reviewer: mmcc
 ---
 
-# Update your JVM args: Application Insights for Java
+# Get Started (Supplemental)
+
+In the following sections, you will find information on how to get Java auto-instrumentation for specific technical environments.
 
 ## Azure App Service
 
@@ -18,26 +20,63 @@ For more information, see [Application monitoring for Azure App Service and Java
 
 For more information, see [Monitoring Azure Functions with Azure Monitor Application Insights](./monitor-functions.md#distributed-tracing-for-java-applications-preview).
 
-## Spring Boot
+## Containers
 
-For more information, see [Using Azure Monitor Application Insights with Spring Boot](./java-spring-boot.md).
+### Docker entry point
+
+If you're using the *exec* form, add the parameter `-javaagent:"path/to/applicationinsights-agent-3.4.11.jar"` to the parameter list somewhere before the `"-jar"` parameter, for example:
+
+```
+ENTRYPOINT ["java", "-javaagent:path/to/applicationinsights-agent-3.4.11.jar", "-jar", "<myapp.jar>"]
+```
+
+If you're using the *shell* form, add the JVM arg `-javaagent:"path/to/applicationinsights-agent-3.4.11.jar"` somewhere before `-jar`, for example:
+
+```
+ENTRYPOINT java -javaagent:"path/to/applicationinsights-agent-3.4.11.jar" -jar <myapp.jar>
+```
+
+
+### Docker file
+
+A Dockerfile example:
+
+```
+FROM ...
+
+COPY target/*.jar app.jar
+
+COPY agent/applicationinsights-agent-3.4.11.jar applicationinsights-agent-3.4.11.jar 
+
+COPY agent/applicationinsights.json applicationinsights.json
 
-## Third-party container images
+ENV APPLICATIONINSIGHTS_CONNECTION_STRING="CONNECTION-STRING"
+        
+ENTRYPOINT["java", "-javaagent:applicationinsights-agent-3.4.11.jar", "-jar", "app.jar"]
+```
+
+### Third-party container images
 
 If you're using a third-party container image that you can't modify, mount the Application Insights Java agent jar into the container from outside. Set the environment variable for the container
 `JAVA_TOOL_OPTIONS=-javaagent:/path/to/applicationinsights-agent.jar`.
 
-## Tomcat 8 (Linux)
+## Spring Boot
 
-### Tomcat installed via apt-get or yum
+For more information, see [Using Azure Monitor Application Insights with Spring Boot](./java-spring-boot.md).
+
+## Java Application servers
+
+### Tomcat 8 (Linux)
+
+#### Tomcat installed via apt-get or yum
 
 If you installed Tomcat via `apt-get` or `yum`, you should have a file `/etc/tomcat8/tomcat8.conf`. Add this line to the end of that file:
 
 ```
 JAVA_OPTS="$JAVA_OPTS -javaagent:path/to/applicationinsights-agent-3.4.11.jar"
 ```
 
-### Tomcat installed via download and unzip
+#### Tomcat installed via download and unzip
 
 If you installed Tomcat via download and unzip from [https://tomcat.apache.org](https://tomcat.apache.org), you should have a file `<tomcat>/bin/catalina.sh`. Create a new file in the same directory named `<tomcat>/bin/setenv.sh` with the following content:
 
@@ -47,9 +86,9 @@ CATALINA_OPTS="$CATALINA_OPTS -javaagent:path/to/applicationinsights-agent-3.4.1
 
 If the file `<tomcat>/bin/setenv.sh` already exists, modify that file and add `-javaagent:path/to/applicationinsights-agent-3.4.11.jar` to `CATALINA_OPTS`.
 
-## Tomcat 8 (Windows)
+### Tomcat 8 (Windows)
 
-### Run Tomcat from the command line
+#### Run Tomcat from the command line
 
 Locate the file `<tomcat>/bin/catalina.bat`. Create a new file in the same directory named `<tomcat>/bin/setenv.bat` with the following content:
 
@@ -65,13 +104,13 @@ set "CATALINA_OPTS=%CATALINA_OPTS% -javaagent:path/to/applicationinsights-agent-
 
 If the file `<tomcat>/bin/setenv.bat` already exists, modify that file and add `-javaagent:path/to/applicationinsights-agent-3.4.11.jar` to `CATALINA_OPTS`.
 
-### Run Tomcat as a Windows service
+#### Run Tomcat as a Windows service
 
 Locate the file `<tomcat>/bin/tomcat8w.exe`. Run that executable and add `-javaagent:path/to/applicationinsights-agent-3.4.11.jar` to the `Java Options` under the `Java` tab.
 
-## JBoss EAP 7
+### JBoss EAP 7
 
-### Standalone server
+#### Standalone server
 
 Add `-javaagent:path/to/applicationinsights-agent-3.4.11.jar` to the existing `JAVA_OPTS` environment variable in the file `JBOSS_HOME/bin/standalone.conf` (Linux) or `JBOSS_HOME/bin/standalone.conf.bat` (Windows):
 
@@ -80,7 +119,7 @@ Add `-javaagent:path/to/applicationinsights-agent-3.4.11.jar` to the existing `J
     ...
 ```
 
-### Domain server
+#### Domain server
 
 Add `-javaagent:path/to/applicationinsights-agent-3.4.11.jar` to the existing `jvm-options` in `JBOSS_HOME/domain/configuration/host.xml`:
 
@@ -125,7 +164,7 @@ If you're running multiple managed servers on a single host, you'll need to add
 
 The specified `applicationinsights.agent.id` value must be unique. It's used to create a subdirectory under the Application Insights directory. 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, so the specified `applicationinsights.agent.id` is needed to override the `agent.id` setting in that shared file. The `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
+### Jetty 9
 
 Add these lines to `start.ini`:
 
@@ -134,7 +173,7 @@ Add these lines to `start.ini`:
 -javaagent:path/to/applicationinsights-agent-3.4.11.jar
 ```
 
-## Payara 5
+### Payara 5
 
 Add `-javaagent:path/to/applicationinsights-agent-3.4.11.jar` to the existing `jvm-options` in `glassfish/domains/domain1/config/domain.xml`:
 
@@ -150,31 +189,32 @@ Add `-javaagent:path/to/applicationinsights-agent-3.4.11.jar` to the existing `j
 ...
 ```
 
-## WebSphere 8
+### WebSphere 8
 
 1. Open Management Console.
 1. Go to **Servers** > **WebSphere application servers** > **Application servers**. Choose the appropriate application servers and select:
-    
+
     ```
     Java and Process Management > Process definition >  Java Virtual Machine
     ```
-    
+
 1. In `Generic JVM arguments`, add the following JVM argument:
-    
+
     ```
     -javaagent:path/to/applicationinsights-agent-3.4.11.jar
     ```
 
 1. Save and restart the application server.
 
-## OpenLiberty 18
+### OpenLiberty 18
 
 Create a new file `jvm.options` in the server directory (for example, `<openliberty>/usr/servers/defaultServer`), and add this line:
 
 ```
 -javaagent:path/to/applicationinsights-agent-3.4.11.jar
 ```
 
-## Others
+### Others
 
 See your application server documentation on how to add JVM args.
+

articles/azure-monitor/app/opentelemetry-enable.md

@@ -184,9 +184,10 @@ Java auto-instrumentation is enabled through configuration changes; no code chan
 Point the JVM to the jar file by adding `-javaagent:"path/to/applicationinsights-agent-3.4.11.jar"` to your application's JVM args.
 
 > [!TIP]
-> For help with configuring your application's JVM args, see [Tips for updating your JVM args](./java-standalone-arguments.md).
-    
-If you develop a Spring Boot application, you can optionally replace the JVM argument by a programmatic configuration. For more information, see [Using Azure Monitor Application Insights with Spring Boot](./java-spring-boot.md).
+> For scenario-specific guidance, see [Get Started (Supplemental)](./java-get-started-supplemental.md).
+
+> [!TIP]
+> If you develop a Spring Boot application, you can optionally replace the JVM argument by a programmatic configuration. For more information, see [Using Azure Monitor Application Insights with Spring Boot](./java-spring-boot.md).
 
 ##### [Node.js](#tab/nodejs)
 

articles/azure-monitor/toc.yml

@@ -734,6 +734,8 @@ items:
             href: app/java-spring-boot.md
           - name: Profiler
             href: app/java-standalone-profiler.md
+          - name: Get started (supplemental)
+            href: app/java-get-started-supplemental.md
           - name: Configuration
             items:
             - name: General
@@ -748,8 +750,6 @@ items:
                   href: app/java-standalone-telemetry-processors.md
                 - name: Examples
                   href: app/java-standalone-telemetry-processors-examples.md
-          - name: JVM arguments setup
-            href: app/java-standalone-arguments.md
           - name: Upgrade from 2.x
             href: app/java-standalone-upgrade-from-2x.md
         - name: FAQ