Azure Monitor automatische instrumentatie op basis van OpenTelemetry voor Java-toepassingen

In dit artikel wordt beschreven hoe u de aanbieding op basis van OpenTelemetry Azure Monitor Java inschakelen en configureren. Nadat u de instructies in dit artikel hebt gevolgd, kunt u Azure Monitor Application Insights gebruiken om uw toepassing te bewaken.

Aan de slag

Automatische instrumentatie van Java kan worden ingeschakeld zonder codewijzigingen.

Vereisten

• Java-toepassing met Java 8+
• Azure-abonnement: Gratis een Azure-abonnement maken
• Toepassingsresource Insights: Een Application Insights maken

Toepassings Azure Monitor inschakelen Insights

In deze sectie ziet u hoe u het JAR-bestand voor automatische instrumentatie downloadt.

Het JAR-bestand downloaden

Download het bestand applicationinsights-agent-3.2.3.jar.

De JVM naar het JAR-bestand laten wijzen

Voeg -javaagent:path/to/applicationinsights-agent-3.2.3.jar toe aan de JVM-args van uw toepassing.

De toepassingstoepassing Insights connection string

1. Er zijn twee manieren waarop u het JAR-bestand kunt laten wijzen naar uw Application Insights resource:

   • U kunt een omgevingsvariabele instellen:

     APPLICATIONINSIGHTS_CONNECTION_STRING=InstrumentationKey=...
     

   • U kunt ook een configuratiebestand maken met de naam applicationinsights.json . Plaats deze in dezelfde map als applicationinsights-agent-3.2.3.jar met de volgende inhoud:

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

2. Zoek de connection string uw Application Insights-resource.

   

Controleren of de gegevens stromen

Voer uw toepassing uit en open het tabblad Application Insights Resource in het Azure Portal. Het kan enkele minuten duren voordat gegevens worden weer geven in de portal.

Als onderdeel van het gebruik van Application Insights-instrumentatie, verzamelen en verzenden we diagnostische gegevens naar Microsoft. Deze gegevens helpen ons bij het uitvoeren en verbeteren van application Insights. U hebt de mogelijkheid om het verzamelen van niet-essentiële gegevens uit te schakelen. Zie Statsbeat in Azure-toepassing Insightsvoor meer informatie.

Configuratie-opties

In het applicationinsights.json bestand kunt u ook deze instellingen configureren:

• Naam van cloudrol
• Cloudrol-exemplaar
• Steekproeven
• Metrische JMX-gegevens
• Aangepaste dimensies
• Telemetrieprocessors (preview)
• Automatisch opgehaalde logboekregistratie
• Automatisch opgehaalde metrische gegevens van micrometers, waaronder Spring Boot Actuator-metrische gegevens
• Hartslag
• HTTP-proxy
• Zelfdiagnose

Zie Configuratieopties voor meer informatie.

Instrumentatiebibliotheken

Java 3.x bevat de volgende instrumentatiebibliotheken.

Automatisch opgehaalde aanvragen

• JMS-consumenten
• Kafka-consumenten
• Netty/WebFhost
• Servlets
• Lenteplanning

Automatisch opgehaalde afhankelijkheden

Automatisch verwerkte afhankelijkheden plus downstream gedistribueerde traceer doorgeven:

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

Automatisch verwerkte afhankelijkheden zonder downstream gedistribueerde traceer door te gaan:

• Cassandra
• JDBC
• MongoDB (async en sync)
• Redis (Sla en Jedis)

Automatisch opgehaalde logboeken

• java.util.logging
• Log4j, dat MDC-eigenschappen bevat
• SLF4J/Logback, dat MDC-eigenschappen bevat

Automatisch opgehaalde metrische gegevens

• Micrometer, die metrische gegevens Spring Boot Actuator bevat
• Metrische JMX-gegevens

Azure-SDK's

Telemetrie die door deze Azure SDK's wordt uitgezonden, wordt standaard automatisch opgehaald:

• 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 Telefoon 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 Form Recognizer 3.0.6+
• Azure Identity 1.2.4+
• Azure Key Vault - Certificaten 4.1.6+
• Azure Key Vault - Sleutels 4.2.6+
• Azure Key Vault - Geheimen 4.2.6+
• Azure Service Bus 7.1.0+
• Azure Storage - Blobs 12.11.0+
• Azure Storage - Blobs Batch 12.9.0+
• Azure Storage - Blobs-cryptografie 12.11.0+
• Azure Storage - Algemeen 12.11.0+
• Azure Storage- Files Data Lake 12.5.0+
• Azure Storage - Bestands shares 12.9.0+
• Azure Storage - Wachtrijen 12.9.0+
• Azure Text Analytics 5.0.4+

Telemetrie wijzigen

In deze sectie wordt uitgelegd hoe u telemetrie kunt wijzigen.

Spankenmerken toevoegen

U kunt gebruiken opentelemetry-api om kenmerken toe te voegen aan spans. Deze kenmerken kunnen bestaan uit het toevoegen van een aangepaste bedrijfsdimensie aan uw telemetrie. U kunt ook kenmerken gebruiken om optionele velden in te stellen in het Insights toepassing, zoals gebruikers-id of client-IP.

Een aangepaste dimensie toevoegen

Als u een of meer aangepaste dimensies toevoegt, wordt het veld customDimensions in de tabel aanvragen, afhankelijkheden of uitzonderingen ingevuld.

1. Voeg opentelemetry-api-1.6.0.jar toe aan uw toepassing:

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

2. Voeg aangepaste dimensies toe aan uw code:

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

De gebruikers-id instellen

Vul het veld gebruikers-id in de tabel aanvragen, afhankelijkheden of uitzonderingen in.

1. Voeg opentelemetry-api-1.6.0.jar toe aan uw toepassing:

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

2. Stel user_Id in uw code in:

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

De traceer-id of span-id op te halen

U kunt gebruiken om opentelemetry-api de traceer-id of span-id op te halen. Deze actie kan worden uitgevoerd om deze id's toe te voegen aan bestaande logboekregistratie-telemetrie om de correlatie te verbeteren wanneer u problemen opsport en diagnosticeert.

1. Voeg opentelemetry-api-1.6.0.jar toe aan uw toepassing:

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

2. Haal de traceer-id van de aanvraag en de span-id in uw code op:

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

Aangepaste telemetrie

Ons doel in Application Insights Java 3.x is om u in staat te stellen uw aangepaste telemetrie te verzenden met behulp van standaard-API's.

We ondersteunen momenteel Micrometer, populaire frameworks voor logboekregistratie en de Application Insights Java 2.x SDK. Application Insights Java 3.x legt automatisch de telemetrie vast die via deze API's wordt verzonden en correleert deze met automatisch in elkaar geplaatste telemetrie.

Ondersteunde aangepaste telemetrie

De volgende tabel vertegenwoordigt momenteel ondersteunde aangepaste telemetrietypen die u kunt inschakelen als aanvulling op de Java 3.x-agent. Samenvatting:

• Aangepaste metrische gegevens worden ondersteund via micrometer.
• Aangepaste uitzonderingen en traceringen worden ondersteund via frameworks voor logboekregistratie.
• Aangepaste aanvragen, afhankelijkheden en uitzonderingen worden ondersteund via opentelemetry-api .
• Elk type aangepaste telemetrie wordt ondersteund via de Application Insights Java 2.x SDK.

Momenteel zijn we niet van plan om een SDK uit te brengen met Application Insights 3.x.

Application Insights Java 3.x luistert al naar telemetrie die is verzonden naar de Application Insights Java 2.x SDK. Deze functionaliteit is een belangrijk onderdeel van de upgrade voor bestaande 2.x-gebruikers. En het vult een belangrijke hiaat in onze ondersteuning voor aangepaste telemetrie totdat de OpenTelemetry-API algemeen beschikbaar is.

Aangepaste metrische gegevens verzenden met behulp van Micrometer

1. Micrometer toevoegen aan uw toepassing:

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

2. Gebruik het globale register van Micrometer om een meter te maken:

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

3. Gebruik de teller om metrische gegevens vast te registreren:

   counter.increment();
   

Aangepaste traceringen en uitzonderingen verzenden met behulp van uw favoriete framework voor logboekregistratie

Log4j, Logback en java.util.logging worden automatisch instrumenteerd. Logboekregistratie die via deze frameworks voor logboekregistratie wordt uitgevoerd, wordt automatisch als traceer- en uitzonderings-telemetrie opgehaald.

Standaard wordt logboekregistratie alleen verzameld wanneer die logboekregistratie wordt uitgevoerd op infoniveau of hoger. Zie de configuratieopties om dit niveau te wijzigen.

Als u aangepaste dimensies aan uw logboeken wilt koppelen, gebruikt u Log4j 1.2 MDC, Log4j 2 MDCof Logback MDC. Application Insights Java 3.x legt deze MDC-eigenschappen automatisch vast als aangepaste dimensies voor uw traceer- en uitzonderings-telemetrie.

Aangepaste telemetrie verzenden met behulp van de 2.x SDK

1. Voeg applicationinsights-core-2.6.3.jar toe aan uw toepassing. Alle 2.x-versies worden ondersteund door Application Insights Java 3.x. Als u een keuze hebt. het is de moeite waard om de nieuwste versie te gebruiken:

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

2. Een TelemetryClient maken:

   static final TelemetryClient telemetryClient = new TelemetryClient();
   

3. Gebruik de client om aangepaste telemetrie te verzenden:

   Gebeurtenissen

   telemetryClient.trackEvent("WinGame");
   

   Metrische gegevens

   telemetryClient.trackMetric("queueLength", 42.0);
   

   Afhankelijkheden

   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);
   }
   

   Logboeken

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

   Uitzonderingen

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

Problemen oplossen

Zie Problemen oplossen voor hulp bij het oplossen van problemen.

Ondersteuning

Ondersteuning krijgen:

• Bekijk de stappen voor probleemoplossing voor hulp bij het oplossen van problemen.
• Voor ondersteuning voor Azure problemen opent u een ondersteuning voor Azure ticket.
• Voor problemen met OpenTelemetry kunt u rechtstreeks contact opnemen met de OpenTelemetry-community.

OpenTelemetry-feedback

Feedback geven:

• Vul het klantenfeedback-enquête van de OpenTelemetry-community in.
• Vertel Microsoft over uzelf door lid te worden van onze OpenTelemetry Early Adopter Community.
• Neem contact op met Azure Monitor gebruikers in de Microsoft Tech Community.
• Maak een functieaanvraag op het Azure Feedback Forum.

Volgende stappen

• Als u de broncode wilt bekijken, gaat u naar Azure Monitor Java auto-instrumentation GitHub opslagplaats.
• Zie de OpenTelemetry Java GitHub opslagplaats voor meer informatie over OpenTelemetry en de community.
• Zie Gebruikersbewaking voor webbrowsers of browsers inschakelen als u gebruikservaringen wilt inschakelen.