Merge pull request #221533 from trask/classic-sdk

Update 2.x -> Classic SDK, also added some details about structured logging

Author: prmerger-automator[bot]

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

@@ -168,8 +168,8 @@ Autocollected dependencies without downstream distributed trace propagation:
 
 ### Autocollected logs
 
-* Log4j (including MDC/Thread Context properties)
 * Logback (including MDC properties)
+* Log4j (including MDC/Thread Context properties)
 * JBoss Logging (including MDC properties)
 * java.util.logging
 
@@ -409,30 +409,26 @@ You can use `opentelemetry-api` to get the trace ID or span ID. This action can
 
 Our goal in Application Insights Java 3.x is to allow you to send your custom telemetry by using standard APIs.
 
-We currently support Micrometer, popular logging frameworks, and the Application Insights Java 2.x SDK. Application Insights Java 3.x automatically captures the telemetry sent through these APIs and correlates it with autocollected telemetry.
+We currently support Micrometer, popular logging frameworks, and the Application Insights Java Classic SDK. Application Insights Java 3.x automatically captures the telemetry sent through these APIs and correlates it with autocollected telemetry.
 
 ### Supported custom telemetry
 
 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 exceptions and traces are supported through logging frameworks.
-- Custom requests, dependencies, metrics, and exceptions are supported through `opentelemetry-api`.
-- All types of the custom telemetry is supported through the [Application Insights Java 2.x SDK](#send-custom-telemetry-by-using-the-2x-sdk).
-
-| Custom telemetry type | Micrometer | Log4j, logback, JUL | 2.x SDK | opentelemetry-api |
-|-----------------------|------------|---------------------|---------|-------------------|
-| Custom events         |            |                     |  Yes    |                   |
-| Custom metrics        |  Yes       |                     |  Yes    |  Yes              |
-| Dependencies          |            |                     |  Yes    |  Yes              |
-| Exceptions            |            |  Yes                |  Yes    |  Yes              |
-| Page views            |            |                     |  Yes    |                   |
-| Requests              |            |                     |  Yes    |  Yes              |
-| Traces                |            |  Yes                |  Yes    |                   |
-
-Currently, we're not planning to release an SDK with Application Insights 3.x.
-
-Application Insights Java 3.x is already listening for telemetry that's sent to the Application Insights Java 2.x SDK. This functionality is an important part of the upgrade story for existing 2.x users. And it fills an important gap in our custom telemetry support until all custom telemetry types are supported via the OpenTelemetry API.
+- 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).
+
+| Custom telemetry type | Micrometer | Logback, Log4j, JUL | OpenTelemetry API | AI Classic SDK |
+|-----------------------|------------|---------------------|-------------------|----------------|
+| Custom events         |            |                     |                   | Yes            |
+| Custom metrics        |  Yes       |                     | Yes               | Yes            |
+| Dependencies          |            |                     | Yes               | Yes            |
+| Exceptions            |            | Yes                 | Yes               | Yes            |
+| Page views            |            |                     |                   | Yes            |
+| Requests              |            |                     | Yes               | Yes            |
+| Traces                |            | Yes                 |                   | Yes            |
 
 ### Send custom metrics by using Micrometer
 
@@ -469,22 +465,26 @@ Application Insights Java 3.x is already listening for telemetry that's sent to
 
 ### Send custom traces and exceptions by using your favorite logging framework
 
-Log4j, Logback, and java.util.logging are auto-instrumented. Logging performed via these logging frameworks is autocollected as trace and exception telemetry.
+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.
 To change this level, see the [configuration options](./java-standalone-config.md#auto-collected-logging).
 
-If you want to attach custom dimensions to your logs, use [Log4j 1.2 MDC](https://logging.apache.org/log4j/1.2/apidocs/org/apache/log4j/MDC.html), [Log4j 2 MDC](https://logging.apache.org/log4j/2.x/manual/thread-context.html), or [Logback MDC](http://logback.qos.ch/manual/mdc.html). Application Insights Java 3.x automatically captures those MDC properties as custom dimensions on your trace and exception telemetry.
+Structured logging (attaching custom dimensions to your logs) can be accomplished in these ways:
+* [Logback MDC](http://logback.qos.ch/manual/mdc.html)
+* [Log4j 2 MapMessage](https://logging.apache.org/log4j/2.x/log4j-api/apidocs/org/apache/logging/log4j/message/MapMessage.html) (a `MapMessage` key of `"message"` will be captured as the log message)
+* [Log4j 2 Thread Context](https://logging.apache.org/log4j/2.x/manual/thread-context.html)
+* [Log4j 1.2 MDC](https://logging.apache.org/log4j/1.2/apidocs/org/apache/log4j/MDC.html)
 
-### Send custom telemetry by using the 2.x SDK
+### Send custom telemetry by using the Application Insights Classic SDK
 
-1. Add `applicationinsights-core-2.6.4.jar` to your application. All 2.x versions are supported by Application Insights Java 3.x. If you have a choice, it's worth using the latest version:
+1. Add `applicationinsights-core` to your application:
 
     ```xml
     <dependency>
       <groupId>com.microsoft.azure</groupId>
       <artifactId>applicationinsights-core</artifactId>
-      <version>2.6.4</version>
+      <version>3.4.7</version>
     </dependency>
     ```