Azure Monitor OpenTelemetry-baserad automatisk instrumentation för Java-program

I den här artikeln beskrivs hur du aktiverar och konfigurerar OpenTelemetry-baserade Azure Monitor Java-erbjudandet. När du har avslutat anvisningarna i den här artikeln kommer du att kunna använda Azure Monitor Application Insights för att övervaka ditt program.

Kom igång

Automatisk Java-instrumentation kan aktiveras utan kodändringar.

Förutsättningar

• Java-program med Java 8+
• Azure-prenumeration: Skapa en Azure-prenumeration kostnadsfritt
• Program Insights resurs: Skapa en programresurs Insights program

Aktivera Azure Monitor-Insights

Det här avsnittet visar hur du laddar ned JAR-filen för automatisk instrumentation.

Ladda ned jar-filen

Ladda ned filen applicationinsights-agent-3.2.3.jar.

Peka JVM till jar-filen

Lägg -javaagent:path/to/applicationinsights-agent-3.2.3.jar till i programmets JVM-args.

Ange anslutningssträngen Insights Application Insights

1. Det finns två sätt att peka jar-filen på din Application Insights resurs:

   • Du kan ange en miljövariabel:

     APPLICATIONINSIGHTS_CONNECTION_STRING=InstrumentationKey=...
     

   • Eller så kan du skapa en konfigurationsfil med namnet applicationinsights.json . Placera den i samma katalog applicationinsights-agent-3.2.3.jar som med följande innehåll:

     {
       "connectionString": "InstrumentationKey=..."
     }
     

2. Leta reda på anslutningssträngen på Insights programresursen.

   

Bekräfta att data flödar

Kör programmet och öppna fliken Insights Programresurs i Azure Portal. Det kan ta några minuter innan data visas i portalen.

Som en del av att Insights application-instrumentation samlar vi in och skickar diagnostikdata till Microsoft. Dessa data hjälper oss att köra och förbättra Insights. Du kan välja att inaktivera inhämtning av oinaktiella data. Mer information finns i Statistikbeat i Azure Application Insights.

Konfigurationsalternativ

I filen applicationinsights.json kan du också konfigurera följande inställningar:

• Namn på molnroll
• Molnrollinstans
• Samling
• JMX-mått
• Anpassade dimensioner
• Telemetriprocessorer (förhandsversion)
• Automatiskt samlad loggning
• Autosamlade Micrometer-mått, inklusive Spring Boot Actuator-mått
• Pulsslag
• HTTP-proxy
• Självdiagnostik

Mer information finns i Konfigurationsalternativ.

Instrumenteringsbibliotek

Java 3.x innehåller följande instrumentationsbibliotek.

Automatiskt insamlade begäranden

• JMS-konsumenter
• Kafka-konsumenter
• Netty/WebFlux
• Servlets
• Vårschemaläggning

Automatiskt insamlade beroenden

Automatiskt insamlade beroenden plus underordnad distribuerad spårningsspridning:

• Apache HttpClient
• Apache HttpAsyncClient
• AsyncHttpClient
• Google HttpClient
• gRPC
• java.net.HttpURLConnection
• Java 11 HttpClient
• JAX-RS-klient
• Jetty HttpClient
• JMS
• Kafka
• Netty-klient
• OkHttp

Automatiskt insamlade beroenden utan spridning av distribuerad spårning nedströms:

• Cassandra
• JDBC
• MongoDB (asynkron och synkronisering)
• Redis (Lettuce och Jedis)

Automatiskt insamlade loggar

• java.util.logging
• Log4j, som innehåller MDC-egenskaper
• SLF4J/Logback, som innehåller MDC-egenskaper

Automatiskt insamlat mått

• Micrometer, som innehåller Spring Boot Actuator-mått
• JMX-mått

Azure-SDK:er

Telemetri som genereras av dessa Azure-SDK:er samlas automatiskt in som standard:

• Azure App Configuration 1.1.10+
• Azure Cognitive Search 11.3.0+
• Azure Communication Chat 1.0.0+
• Azure Communication Common 1.0.0+
• Azure Communication Identity 1.0.0+
• Azure Communication Telefon Numbers 1.0.0+
• Azure Communication SMS 1.0.0+
• Azure Cosmos DB 4.13.0+
• Azure Digital Twins – Core 1.1.0+
• Azure Event Grid 4.0.0+
• Azure Event Hubs 5.6.0+
• Azure Event Hubs – Azure Blob Storage Checkpoint Store 1.5.1+
• Azure Formigenkänning 3.0.6+
• Azure Identity 1.2.4+
• Azure Key Vault – Certifikat 4.1.6+
• Azure Key Vault – Nycklar 4.2.6+
• Azure Key Vault – Secrets 4.2.6+
• Azure Service Bus 7.1.0+
• Azure Storage – Blobar 12.11.0+
• Azure Storage – Blobar Batch 12.9.0+
• Azure Storage – Blobs Cryptography 12.11.0+
• Azure Storage – Common 12.11.0+
• Azure Storage – Files Data Lake 12.5.0+
• Azure Storage – Filresurser 12.9.0+
• Azure Storage – Köer 12.9.0+
• Azure Textanalys 5.0.4+

Ändra telemetri

I det här avsnittet beskrivs hur du ändrar telemetri.

Lägga till span-attribut

Du kan använda opentelemetry-api för att lägga till attribut i intervall. Dessa attribut kan inkludera att lägga till en anpassad företagsdimension i din telemetri. Du kan också använda attribut för att ange valfria fält i Insights schema, till exempel användar-ID eller klient-IP.

Lägga till en anpassad dimension

När du lägger till en eller flera anpassade dimensioner fylls fältet customDimensions i tabellen begäranden, beroenden eller undantag.

1. Lägg opentelemetry-api-1.6.0.jar till i ditt program:

   <dependency>
     <groupId>io.opentelemetry</groupId>
     <artifactId>opentelemetry-api</artifactId>
     <version>1.6.0</version>
   </dependency>
   

2. Lägg till anpassade dimensioner i koden:

   import io.opentelemetry.api.trace.Span;
   
   Span.current().setAttribute("mycustomdimension", "myvalue1");
   

Ange användar-ID

Fyll i fältet användar-ID i tabellen begäranden, beroenden eller undantag.

1. Lägg opentelemetry-api-1.6.0.jar till i ditt program:

   <dependency>
     <groupId>io.opentelemetry</groupId>
     <artifactId>opentelemetry-api</artifactId>
     <version>1.6.0</version>
   </dependency>
   

2. Ange user_Id i koden:

   import io.opentelemetry.api.trace.Span;
   
   Span.current().setAttribute("enduser.id", "myuser");
   

Hämta spårnings-ID eller span-ID

Du kan använda för opentelemetry-api att hämta spårnings-ID eller span-ID. Den här åtgärden kan göras för att lägga till dessa identifierare i befintlig loggningstelemetri för att förbättra korrelationen när du felsöker och diagnostiserar problem.

1. Lägg opentelemetry-api-1.6.0.jar till i ditt program:

   <dependency>
     <groupId>io.opentelemetry</groupId>
     <artifactId>opentelemetry-api</artifactId>
     <version>1.6.0</version>
   </dependency>
   

2. Hämta spårnings-ID:t för begäran och span-ID:t i koden:

   import io.opentelemetry.api.trace.Span;
   
   String traceId = Span.current().getSpanContext().getTraceId();
   String spanId = Span.current().getSpanContext().getSpanId();
   

Anpassad telemetri

Vårt mål i Application Insights Java 3.x är att du ska kunna skicka din anpassade telemetri med hjälp av standard-API:er.

Vi stöder för närvarande Micrometer, populära loggningsramverk och Application Insights Java 2.x SDK. Program Insights Java 3.x samlar automatiskt in telemetri som skickas via dessa API:er och korrelerar den med automatiskt samlad telemetri.

Anpassad telemetri som stöds

Följande tabell representerar de anpassade telemetrityper som stöds för närvarande och som du kan aktivera för att komplettera Java 3.x-agenten. Sammanfattningsvis:

• Anpassade mått stöds via mikrometer.
• Anpassade undantag och spårningar stöds via loggningsramverk.
• Anpassade begäranden, beroenden och undantag stöds via opentelemetry-api .
• Alla typer av anpassad telemetri stöds via Application Insights Java 2.x SDK.

För närvarande planerar vi inte att släppa en SDK med Application Insights 3.x.

Program Insights Java 3.x lyssnar redan efter telemetri som skickas till Application Insights Java 2.x SDK. Den här funktionen är en viktig del av uppgraderingsberättelsen för befintliga 2.x-användare. Och det fyller en viktig lucka i vårt anpassade telemetristöd tills OpenTelemetry-API:et är allmänt tillgängligt.

Skicka anpassade mått med hjälp av Micrometer

1. Lägg till Micrometer i ditt program:

   <dependency>
     <groupId>io.micrometer</groupId>
     <artifactId>micrometer-core</artifactId>
     <version>1.6.1</version>
   </dependency>
   

2. Använd det globala registret Micrometer för att skapa en mätare:

   static final Counter counter = Metrics.counter("test_counter");
   

3. Använd räknaren för att registrera mått:

   counter.increment();
   

Skicka anpassade spårningar och undantag med hjälp av ditt favoritramverk för loggning

Log4j, Logback och java.util.logging instrumenteras automatiskt. Loggning som utförs via dessa loggningsramverk insamlas automatiskt som spårnings- och undantagstelemetri.

Som standard samlas loggning bara in när loggning utförs på INFO-nivå eller högre. Information om hur du ändrar den här nivån finns i konfigurationsalternativen.

Om du vill koppla anpassade dimensioner till loggarna använder du Log4j 1.2 MDC, Log4j 2 MDCeller Logback MDC. Program Insights Java 3.x samlar automatiskt in dessa MDC-egenskaper som anpassade dimensioner i spårnings- och undantagstelemetri.

Skicka anpassad telemetri med hjälp av 2.x SDK

1. Lägg applicationinsights-core-2.6.3.jar till i ditt program. Alla 2.x-versioner stöds av Application Insights Java 3.x. Om du har ett val. Det är värt att använda den senaste versionen:

   <dependency>
     <groupId>com.microsoft.azure</groupId>
     <artifactId>applicationinsights-core</artifactId>
     <version>2.6.3</version>
   </dependency>
   

2. Skapa en TelemetryClient:

   static final TelemetryClient telemetryClient = new TelemetryClient();
   

3. Använd klienten för att skicka anpassad telemetri:

   Händelser

   telemetryClient.trackEvent("WinGame");
   

   Mått

   telemetryClient.trackMetric("queueLength", 42.0);
   

   Beroenden

   boolean success = false;
   long startTime = System.currentTimeMillis();
   try {
       success = dependency.call();
   } finally {
       long endTime = System.currentTimeMillis();
       RemoteDependencyTelemetry telemetry = new RemoteDependencyTelemetry();
       telemetry.setSuccess(success);
       telemetry.setTimestamp(new Date(startTime));
       telemetry.setDuration(new Duration(endTime - startTime));
       telemetryClient.trackDependency(telemetry);
   }
   

   Loggar

   telemetryClient.trackTrace(message, SeverityLevel.Warning, properties);
   

   Undantag

   try {
       ...
   } catch (Exception e) {
       telemetryClient.trackException(e);
   }
   

Felsökning

Om du behöver hjälp med felsökning kan du gå till Felsöka.

Support

Så här får du support:

• Om du behöver hjälp med felsökning kan du läsa felsökningsstegen.
• För Azure-supportproblem öppnar du ett Azure-support ärende.
• Om du har problem med OpenTelemetry kontaktar du OpenTelemetry-communityn direkt.

OpenTelemetry-feedback

Så här ger du feedback:

• Fyll i OpenTelemetry-communityns undersökning om kundfeedback.
• Berätta för Microsoft om dig själv genom att gå med i vår OpenTelemetry Early Adopter Community.
• Interagera med andra Azure Monitor användare i Microsoft Tech Community.
• Skicka en funktionsbegäran på Azure Feedback Forum.

Nästa steg

• Information om hur du granskar källkoden finns i Azure Monitor java auto-instrumentation GitHub repository.
• Mer information om OpenTelemetry och dess community finns i OpenTelemetry Java GitHub-lagringsplatsen.
• Information om hur du aktiverar användningsupplevelser finns i Aktivera användarövervakning av webb- eller webbläsare.