edit pass: app-articles-batch-16

Author: paulth1

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

@@ -1,6 +1,6 @@
 ---
 title: Azure Monitor Application Insights Java
-description: Application performance monitoring for Java applications running in any environment without requiring code modification. Distributed tracing and application map.
+description: Application performance monitoring for Java applications running in any environment without requiring code modification. The article also discusses distributed tracing and the application map.
 ms.topic: conceptual
 ms.date: 12/14/2022
 ms.devlang: java
@@ -10,19 +10,21 @@ ms.reviewer: mmcc
 
 # Azure Monitor OpenTelemetry-based auto-instrumentation for Java applications
 
-This article describes how to enable and configure the OpenTelemetry-based Azure Monitor Java offering. It can be used for any environment, including on-premises. After you finish the instructions in this article, you'll be able to use Azure Monitor Application Insights to monitor your application.
+This article describes how to enable and configure the OpenTelemetry-based Azure Monitor Java offering. It can be used for any environment, including on-premises. After you finish the instructions in this article, you can use Azure Monitor Application Insights to monitor your application.
 
 [!INCLUDE [azure-monitor-log-analytics-rebrand](../../../includes/azure-monitor-instrumentation-key-deprecation.md)]
 
 ## Get started
 
-Java auto-instrumentation is enabled through configuration changes; no code changes are required.
+Java auto-instrumentation is enabled through configuration changes. No code changes are required.
 
 ### Prerequisites
 
-- Java application using Java 8+
-- Azure subscription: [Create an Azure subscription for free](https://azure.microsoft.com/free/)
-- Application Insights resource: [Create an Application Insights resource](create-workspace-resource.md#create-a-workspace-based-resource)
+You need:
+
+- A Java application using Java 8+.
+- An Azure subscription: [Create an Azure subscription for free](https://azure.microsoft.com/free/).
+- An Application Insights resource: [Create an Application Insights resource](create-workspace-resource.md#create-a-workspace-based-resource).
 
 ### Enable Azure Monitor Application Insights
 
@@ -34,32 +36,31 @@ Download the [applicationinsights-agent-3.4.7.jar](https://github.com/microsoft/
 
 > [!WARNING]
 >
-> If you are upgrading from an earlier 3.x version,
+> If you're upgrading from an earlier 3.x version:
 >
 > Starting from 3.4.0:
 >
->    - Rate-limited sampling is now the default (if you have not configured a fixed percentage previously). By default, it will capture at most around 5 requests per second (along with their dependencies, traces and custom events). See [fixed-percentage sampling](./java-standalone-config.md#fixed-percentage-sampling) if you wish to revert to the previous behavior of capturing 100% of requests.
+>    - Rate-limited sampling is now the default, if you haven't configured a fixed percentage previously. By default, it will capture at most around five requests per second, along with their dependencies, traces, and custom events. See [fixed-percentage sampling](./java-standalone-config.md#fixed-percentage-sampling) if you want to revert to the previous behavior of capturing 100% of requests.
 >
 > Starting from 3.3.0:
 >
->    - `LoggingLevel` is not captured by default as part of Traces' custom dimension since that data is already captured in the `SeverityLevel` field. For details on how to re-enable this if needed, please see the [config options](./java-standalone-config.md#logging-level-as-a-custom-dimension)
->    - Exception records are no longer recorded for failed dependencies, they are only recorded for failed requests.
+>    - `LoggingLevel` isn't captured by default as part of Traces' custom dimension because that data is already captured in the `SeverityLevel` field. For information on how to reenable it, see the [config options](./java-standalone-config.md#logging-level-as-a-custom-dimension).
+>    - Exception records are no longer recorded for failed dependencies. They're only recorded for failed requests.
 >
 > Starting from 3.2.0:
-> 
->    - Controller "InProc" dependencies are no longer captured by default. For details on how to re-enable these, please see the [config options](./java-standalone-config.md#autocollect-inproc-dependencies-preview).
+>
+>    - Controller `InProc` dependencies are no longer captured by default. For information on how to reenable these dependencies, see the [config options](./java-standalone-config.md#autocollect-inproc-dependencies-preview).
 >    - Database dependency names are now more concise with the full (sanitized) query still present in the `data` field. HTTP dependency names are now more descriptive.
 >    This change can affect custom dashboards or alerts if they relied on the previous values.
->    For details, see the [3.2.0 release notes](https://github.com/microsoft/ApplicationInsights-Java/releases/tag/3.2.0).
-> 
+>    For more information, see the [3.2.0 release notes](https://github.com/microsoft/ApplicationInsights-Java/releases/tag/3.2.0).
+>
 > Starting from 3.1.0:
-> 
+>
 >    - The operation names and request telemetry names are now prefixed by the HTTP method, such as `GET` and `POST`.
 >    This change can affect custom dashboards or alerts if they relied on the previous values.
->    For details, see the [3.1.0 release notes](https://github.com/microsoft/ApplicationInsights-Java/releases/tag/3.1.0).
+>    For more information, see the [3.1.0 release notes](https://github.com/microsoft/ApplicationInsights-Java/releases/tag/3.1.0).
 >
 
-
 #### Point the JVM to the jar file
 
 Add `-javaagent:"path/to/applicationinsights-agent-3.4.7.jar"` to your application's JVM args.
@@ -68,7 +69,7 @@ Add `-javaagent:"path/to/applicationinsights-agent-3.4.7.jar"` to your applicati
 > 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).
+> If you develop a Spring Boot application, you can replace the JVM argument by a programmatic configuration. For more information, see [Using Azure Monitor Application Insights with Spring Boot](./java-spring-boot.md).
 
 #### Set the Application Insights connection string
 
@@ -90,8 +91,8 @@ Add `-javaagent:"path/to/applicationinsights-agent-3.4.7.jar"` to your applicati
 
 1. Find the connection string on your Application Insights resource.
 
-    :::image type="content" source="media/migrate-from-instrumentation-keys-to-connection-strings/migrate-from-instrumentation-keys-to-connection-strings.png" alt-text="Screenshot displaying Application Insights overview and connection string." lightbox="media/migrate-from-instrumentation-keys-to-connection-strings/migrate-from-instrumentation-keys-to-connection-strings.png":::
-    
+    :::image type="content" source="media/migrate-from-instrumentation-keys-to-connection-strings/migrate-from-instrumentation-keys-to-connection-strings.png" alt-text="Screenshot that shows Application Insights overview and connection string." lightbox="media/migrate-from-instrumentation-keys-to-connection-strings/migrate-from-instrumentation-keys-to-connection-strings.png":::
+
 #### Confirm data is flowing
 
 Run your application and open your **Application Insights Resource** tab in the Azure portal. It can take a few minutes for data to show up in the portal.
@@ -108,7 +109,7 @@ As part of using Application Insights instrumentation, we collect and send diagn
 
 ## Configuration options
 
-In the `applicationinsights.json` file, you can also configure these settings:
+In the *applicationinsights.json* file, you can also configure these settings:
 
 * Cloud role name
 * Cloud role instance
@@ -117,14 +118,14 @@ In the `applicationinsights.json` file, you can also configure these settings:
 * Custom dimensions
 * Telemetry processors (preview)
 * Autocollected logging
-* Autocollected Micrometer metrics, which include Spring Boot Actuator metrics
+* Autocollected Micrometer metrics, including Spring Boot Actuator metrics
 * Heartbeat
 * HTTP proxy
 * Self-diagnostics
 
 For more information, see [Configuration options](./java-standalone-config.md).
 
-## Auto-Instrumentation
+## Auto-instrumentation
 
 Java 3.x includes the following auto-instrumentation.
 
@@ -138,8 +139,7 @@ Java 3.x includes the following auto-instrumentation.
 * Spring scheduling
 
 > [!NOTE]
-> Servlet and Netty auto-instrumentation covers the majority of Java HTTP services
-> including Java EE, Jakarta EE, Spring Boot, Quarkus, and Micronaut.
+> Servlet and Netty auto-instrumentation covers the majority of Java HTTP services, including Java EE, Jakarta EE, Spring Boot, Quarkus, and Micronaut.
 
 ### Autocollected dependencies
 
@@ -175,7 +175,7 @@ Autocollected dependencies without downstream distributed trace propagation:
 
 ### Autocollected metrics
 
-* Micrometer, which includes Spring Boot Actuator metrics
+* Micrometer, including Spring Boot Actuator metrics
 * JMX Metrics
 
 ### Azure SDKs
@@ -233,9 +233,9 @@ Telemetry emitted by these Azure SDKs is automatically collected by default:
 
 This section explains how to modify telemetry.
 
-### Add spans using the OpenTelemetry annotation
+### Add spans by using the OpenTelemetry annotation
 
-The simplest way to add your own spans is using OpenTelemetry's `@WithSpan` annotation.
+The simplest way to add your own spans is by using OpenTelemetry's `@WithSpan` annotation.
 
 Spans populate the `requests` and `dependencies` tables in Application Insights.
 
@@ -262,16 +262,15 @@ Spans populate the `requests` and `dependencies` tables in Application Insights.
     }
    ```
 
-By default the span will end up in the dependencies table with dependency type `InProc`.
+By default, the span will end up in the `dependencies` table with dependency type `InProc`.
 
-If your method represents a background job that is not already captured by auto-instrumentation,
-it is recommended to apply the attribute `kind = SpanKind.SERVER` to the `@WithSpan` annotation
+If your method represents a background job that isn't already captured by auto-instrumentation,
+we recommend that you apply the attribute `kind = SpanKind.SERVER` to the `@WithSpan` annotation
 so that it will end up in the Application Insights `requests` table.
 
-### Add spans using the OpenTelemetry API
+### Add spans by using the OpenTelemetry API
 
-If the OpenTelemetry `@WithSpan` annotation above doesn't meet your needs,
-then you can add your spans using the OpenTelemetry API.
+If the preceding OpenTelemetry `@WithSpan` annotation doesn't meet your needs, you can add your spans by using the OpenTelemetry API.
 
 > [!NOTE]
 > This feature is only in 3.2.0 and later.
@@ -286,7 +285,7 @@ then you can add your spans using the OpenTelemetry API.
    </dependency>
    ```
 
-1. Use the `GlobalOpenTelemetry` class to create a `Tracer`
+1. Use the `GlobalOpenTelemetry` class to create a `Tracer`:
 
    ```java
     import io.opentelemetry.api.GlobalOpenTelemetry;
@@ -310,7 +309,7 @@ then you can add your spans using the OpenTelemetry API.
 
 ### Add span events
 
-You can use `opentelemetry-api` to create span events, which populate the traces table in Application Insights. The string passed in to `addEvent()` is saved to the _message_ field within the trace.
+You can use `opentelemetry-api` to create span events, which populate the `traces` table in Application Insights. The string passed in to `addEvent()` is saved to the `message` field within the trace.
 
 > [!NOTE]
 > This feature is only in 3.2.0 and later.
@@ -337,7 +336,7 @@ You can use `opentelemetry-api` to create span events, which populate the traces
 
 You can use `opentelemetry-api` to add attributes to spans. These attributes can include adding a custom business dimension to your telemetry. You can also use attributes to set optional fields in the Application Insights schema, such as User ID or Client IP.
 
-Adding one or more span attributes populates the _customDimensions_ field in the requests, dependencies, traces, or exceptions table.
+Adding one or more span attributes populates the `customDimensions` field in the `requests`, `dependencies`, `traces`, or `exceptions` table.
 
 > [!NOTE]
 > This feature is only in 3.2.0 and later.
@@ -379,7 +378,7 @@ You can use `opentelemetry-api` to update the status of a span and record except
    </dependency>
    ```
 
-1. Set status to error and record an exception in your code:
+1. Set status to `error` and record an exception in your code:
 
    ```java
     import io.opentelemetry.api.trace.Span;
@@ -392,10 +391,9 @@ You can use `opentelemetry-api` to update the status of a span and record except
 
 #### Set the user ID
 
-Populate the _user ID_ field in the requests, dependencies, or exceptions table.
+Populate the `user ID` field in the `requests`, `dependencies`, or `exceptions` table.
 
-> [!IMPORTANT]
-> Consult applicable privacy laws before you set Authenticated User ID.
+Consult applicable privacy laws before you set the Authenticated User ID.
 
 > [!NOTE]
 > This feature is only in 3.2.0 and later.
@@ -455,7 +453,7 @@ We currently support Micrometer, popular logging frameworks, and the Application
 
 The following table represents currently supported custom telemetry types that you can enable to supplement the Java 3.x agent. To summarize:
 
-- Custom metrics are supported through micrometer.
+- Custom metrics are supported through Micrometer.
 - Custom exceptions and traces are supported through logging frameworks.
 - Custom requests, dependencies, metrics, and exceptions are supported through the OpenTelemetry API.
 - The remaining telemetry types are supported through the [Application Insights Classic SDK](#send-custom-telemetry-by-using-the-application-insights-classic-sdk).
@@ -482,32 +480,31 @@ The following table represents currently supported custom telemetry types that y
     </dependency>
     ```
 
-2. Use the Micrometer [global registry](https://micrometer.io/docs/concepts#_global_registry) to create a meter:
+1. Use the Micrometer [global registry](https://micrometer.io/docs/concepts#_global_registry) to create a meter:
 
     ```java
     static final Counter counter = Metrics.counter("test.counter");
     ```
 
-3. Use the counter to record metrics:
+1. Use the counter to record metrics:
 
     ```java
     counter.increment();
     ```
 
-4. The metrics will be ingested into the
+1. The metrics will be ingested into the
    [customMetrics](/azure/azure-monitor/reference/tables/custommetrics) table, with tags captured in the
    `customDimensions` column. You can also view the metrics in the
-   [Metrics explorer](../essentials/metrics-getting-started.md) under the "Log-based metrics" metric namespace.
+   [metrics explorer](../essentials/metrics-getting-started.md) under the `Log-based metrics` metric namespace.
 
     > [!NOTE]
-    > Application Insights Java replaces all non-alphanumeric characters (except dashes) in the Micrometer metric name
-    > with underscores, so the `test.counter` metric above will show up as `test_counter`.
+    > Application Insights Java replaces all non-alphanumeric characters (except dashes) in the Micrometer metric name with underscores. As a result, the preceding `test.counter` metric will show up as `test_counter`.
 
 ### Send custom traces and exceptions by using your favorite logging framework
 
 Logback, Log4j, and java.util.logging are auto-instrumented. Logging performed via these logging frameworks is autocollected as trace and exception telemetry.
 
-By default, logging is only collected when that logging is performed at the INFO level or above.
+By default, logging is only collected when that logging is performed at the INFO level or higher.
 To change this level, see the [configuration options](./java-standalone-config.md#auto-collected-logging).
 
 Structured logging (attaching custom dimensions to your logs) can be accomplished in these ways:
@@ -528,7 +525,7 @@ Structured logging (attaching custom dimensions to your logs) can be accomplishe
     </dependency>
     ```
 
-1. Create a TelemetryClient:
+1. Create a `TelemetryClient` instance:
 
     ```java
     static final TelemetryClient telemetryClient = new TelemetryClient();
@@ -605,7 +602,7 @@ To provide feedback:
 
 - Fill out the OpenTelemetry community's [customer feedback survey](https://docs.google.com/forms/d/e/1FAIpQLScUt4reClurLi60xyHwGozgM9ZAz8pNAfBHhbTZ4gFWaaXIRQ/viewform).
 - Tell Microsoft about yourself by joining our [OpenTelemetry Early Adopter Community](https://aka.ms/AzMonOTel/).
-- Engage with other Azure Monitor users in the  [Microsoft Tech Community](https://techcommunity.microsoft.com/t5/azure-monitor/bd-p/AzureMonitor).
+- Engage with other Azure Monitor users in the [Microsoft Tech Community](https://techcommunity.microsoft.com/t5/azure-monitor/bd-p/AzureMonitor).
 - Make a feature request at the [Azure Feedback Forum](https://feedback.azure.com/d365community/forum/8849e04d-1325-ec11-b6e6-000d3a4f09d0).
 
 ## Next steps