Automatická instrumentace založená na OpenTelemetry na Azure Monitoru pro aplikace v Javě

Tento článek popisuje, jak povolit a nakonfigurovat nabídku Azure Monitor Java založené na OpenTelemetry. Dá se použít pro jakékoli prostředí, včetně místního prostředí. Po dokončení pokynů v tomto článku budete moct pomocí Application Insights služby Azure Monitor monitorovat vaši aplikaci.

Poznámka

Podpora příjmu dat založeného na instrumentačním klíči skončí 31. března 2025. Příjem klíčů instrumentace bude dál fungovat, ale už nebudeme poskytovat aktualizace ani podporu této funkce. Přechod na připojovací řetězce , abyste mohli využívat nové funkce.

Začínáme

Automatická instrumentace Java je povolená prostřednictvím změn konfigurace; nejsou vyžadovány žádné změny kódu.

Požadavky

Povolení služby Azure Monitor Application Insights

V této části se dozvíte, jak stáhnout soubor JAR automatické instrumentace.

Stažení souboru JAR

Stáhněte soubor applicationinsights-agent-3.3.0.jar .

Upozornění

Pokud upgradujete z verze 3.2.x na verzi 3.3.0:

  • Od verze 3.3.0 se ve výchozím nastavení nezachytí jako součást vlastní dimenze Traces, LoggingLevel protože tato data jsou už v SeverityLevel poli zachycená. Podrobnosti o tom, jak tuto možnost v případě potřeby znovu povolit, najdete v možnostech konfigurace.
  • Záznamy výjimek se už nezaznamenají pro neúspěšné závislosti, zaznamenávají se pouze pro neúspěšné požadavky.

Pokud upgradujete z verze 3.1.x:

  • Od verze 3.2.0 se ve výchozím nastavení nezachytí závislosti kontroleru InProc. Podrobnosti o tom, jak to povolit, najdete v možnostech konfigurace.
  • Názvy závislostí databáze jsou teď stručnější s úplným (sanitizovaným) dotazem data , který je stále v poli. Názvy závislostí HTTP jsou teď popisnější. Tato změna může mít vliv na vlastní řídicí panely nebo výstrahy, pokud se spoléhají na předchozí hodnoty. Podrobnosti najdete v poznámkách k verzi 3.2.0.

Pokud upgradujete z verze 3.0.x:

  • Názvy operací a názvy telemetrie požadavků jsou nyní předponou metody HTTP, například GET a POST. Tato změna může mít vliv na vlastní řídicí panely nebo výstrahy, pokud se spoléhají na předchozí hodnoty. Podrobnosti najdete v poznámkách k verzi verze 3.1.0.

Nasměrujte JVM na soubor JAR.

Přidejte -javaagent:path/to/applicationinsights-agent-3.3.0.jar do skupin JVM vaší aplikace.

Tip

Nápovědu k konfiguraci skupin JVM vaší aplikace najdete v tématu Tipy pro aktualizaci skupin prostředí JVM.

Nastavení připojovacího řetězce Application Insights

  1. Soubor JAR můžete nasměrovat na prostředek Application Insights dvěma způsoby:

    • Proměnnou prostředí můžete nastavit:

      APPLICATIONINSIGHTS_CONNECTION_STRING = <Copy connection string from Application Insights Resource Overview>
      
    • Nebo můžete vytvořit konfigurační soubor s názvem applicationinsights.json. Umístěte ho do stejného adresáře jako applicationinsights-agent-3.3.0.jar s následujícím obsahem:

      {
        "connectionString": "Copy connection string from Application Insights Resource Overview"
      }
      
  2. Najděte připojovací řetězec pro prostředek Application Insights.

    Snímek obrazovky zobrazující přehled Application Insights a připojovací řetězec

Potvrzení toku dat

Spusťte aplikaci a otevřete kartu Prostředek Application Insights v Azure Portal. Zobrazení dat na portálu může trvat několik minut.

Poznámka

Pokud aplikaci nemůžete spustit nebo nedostáváte data podle očekávání, přečtěte si část Řešení potíží .

Snímek obrazovky znázorňující kartu Přehled Application Insights se zvýrazněnou dobou odezvy serveru a požadavky na server

Důležité

Pokud máte dvě nebo více služeb, které generují telemetrii do stejného prostředku Application Insights, musíte nastavit názvy cloudových rolí tak, aby je správně reprezentovaly na mapě aplikace.

V rámci instrumentace Application Insights shromažďujeme a odesíláme diagnostická data microsoftu. Tato data nám pomáhají spouštět a zlepšovat Application Insights. Shromažďování dat můžete zakázat. Další informace najdete v tématu Statsbeat v Aplikace Azure Insights.

Možnosti konfigurace

applicationinsights.json V souboru můžete také nakonfigurovat tato nastavení:

  • Název cloudové role
  • Instance cloudové role
  • Vzorkování
  • Metriky JMX
  • Vlastní dimenze
  • Procesory telemetrie (Preview)
  • Automatické protokolování
  • Metriky mikrometrů s automatickým kolektovanými metrikami, mezi které patří metriky pohonu Spring Boot
  • Tep
  • Proxy server HTTP
  • Samoobslužná diagnostika

Další informace najdete v tématu Možnosti konfigurace.

Knihovny instrumentace

Java 3.x obsahuje následující knihovny instrumentace.

Automatickycollected requests

  • Uživatelé JMS
  • Příjemci Kafka
  • Netty/WebFlux
  • Křemen
  • Servlety
  • Plánování pružiny

Automatické kolektované závislosti

Automatické kolektované závislosti plus šíření distribuovaného trasování podřízeného procesu:

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

Automatické kolektované závislosti bez šíření distribuovaného trasování podřízeného procesu:

  • Cassandra
  • JDBC
  • MongoDB (asynchronní a synchronizační)
  • Redis (Lettuce a Jedis)

Protokoly s automatickým kolektovanými protokoly

  • Log4j (včetně vlastností kontextu MDC nebo vlákna)
  • Zpětný protokol (včetně vlastností MDC)
  • Protokolování JBoss (včetně vlastností MDC)
  • java.util.logging

Metriky s automatickým kolektovanými daty

  • Mikrometr, který zahrnuje metriky poháněcího zařízení Spring Boot
  • Metriky JMX

Sady Azure SDK

Telemetrie generovaná těmito sadami Azure SDK se ve výchozím nastavení automaticky shromažďuje:

Úprava telemetrie

Tato část vysvětluje, jak upravit telemetrii.

Přidání rozsahů

Můžete použít opentelemetry-api k vytváření trasovacích objektů a rozsahů. Naplní tabulku závislostí v Application Insights. Řetězec předaný pro název rozsahu se uloží do cílového pole v rámci závislosti.

Poznámka

Tato funkce je pouze ve verzi 3.2.0 a novější.

  1. Přidejte opentelemetry-api-1.6.0.jar do své aplikace:

    <dependency>
      <groupId>io.opentelemetry</groupId>
      <artifactId>opentelemetry-api</artifactId>
      <version>1.6.0</version>
    </dependency>
    
  2. Přidejte rozsahy do kódu:

     import io.opentelemetry.api.trace.Span;
    
     Span span = tracer.spanBuilder("mySpan").startSpan();
    

Přidání událostí rozsahu

Můžete použít opentelemetry-api k vytvoření událostí rozsahu, které naplní tabulku trasování v Application Insights. Řetězec předaný se addEvent() uloží do pole zprávy v rámci trasování.

Poznámka

Tato funkce je pouze ve verzi 3.2.0 a novější.

  1. Přidejte opentelemetry-api-1.6.0.jar do své aplikace:

    <dependency>
      <groupId>io.opentelemetry</groupId>
      <artifactId>opentelemetry-api</artifactId>
      <version>1.6.0</version>
    </dependency>
    
  2. Přidejte události rozsahu do kódu:

     import io.opentelemetry.api.trace.Span;
    
     span.addEvent("eventName");
    

Přidání atributů span

Můžete použít opentelemetry-api k přidání atributů do rozsahů. Tyto atributy můžou zahrnovat přidání vlastní obchodní dimenze do telemetrie. Atributy můžete použít také k nastavení volitelných polí ve schématu Application Insights, jako je ID uživatele nebo IP adresa klienta.

Přidání vlastní dimenze

Přidání jedné nebo více vlastních dimenzí naplní pole customDimensions v tabulce požadavků, závislostí, trasování nebo výjimek.

Poznámka

Tato funkce je pouze ve verzi 3.2.0 a novější.

  1. Přidejte opentelemetry-api-1.6.0.jar do své aplikace:

    <dependency>
      <groupId>io.opentelemetry</groupId>
      <artifactId>opentelemetry-api</artifactId>
      <version>1.6.0</version>
    </dependency>
    
  2. Přidejte do kódu vlastní dimenze:

     import io.opentelemetry.api.trace.Span;
     import io.opentelemetry.api.common.AttributeKey;
     import io.opentelemetry.api.common.Attributes;
    
     Attributes attributes = Attributes.of(AttributeKey.stringKey("mycustomdimension"), "myvalue1");
     span.setAllAttributes(attributes);
     span.addEvent("eventName", attributes);
    

Aktualizace výjimek stavu rozsahu a záznamů

Můžete použít opentelemetry-api k aktualizaci stavu výjimek rozsahu a záznamů.

Poznámka

Tato funkce je pouze ve verzi 3.2.0 a novější.

  1. Přidejte opentelemetry-api-1.6.0.jar do své aplikace:

    <dependency>
      <groupId>io.opentelemetry</groupId>
      <artifactId>opentelemetry-api</artifactId>
      <version>1.6.0</version>
    </dependency>
    
  2. Nastavte stav na chybu a zaznamenejte výjimku v kódu:

     import io.opentelemetry.api.trace.Span;
     import io.opentelemetry.api.trace.StatusCode;
    
     span.setStatus(StatusCode.ERROR, "errorMessage");
     span.recordException(e);
    

Nastavení ID uživatele

Vyplňte pole ID uživatele v tabulce požadavků, závislostí nebo výjimek.

Důležité

Než nastavíte OVĚŘENÉ ID uživatele, obraťte se na příslušné zákony o ochraně osobních údajů.

Poznámka

Tato funkce je pouze ve verzi 3.2.0 a novější.

  1. Přidejte opentelemetry-api-1.6.0.jar do své aplikace:

    <dependency>
      <groupId>io.opentelemetry</groupId>
      <artifactId>opentelemetry-api</artifactId>
      <version>1.6.0</version>
    </dependency>
    
  2. Nastavte user_Id v kódu:

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

Získání ID trasování nebo ID rozsahu

Můžete použít opentelemetry-api k získání ID trasování nebo ID rozsahu. Tuto akci můžete provést přidáním těchto identifikátorů do existující telemetrie protokolování, aby se zlepšila korelace při ladění a diagnostice problémů.

Poznámka

Tato funkce je pouze ve verzi 3.2.0 a novější.

  1. Přidejte opentelemetry-api-1.6.0.jar do své aplikace:

    <dependency>
      <groupId>io.opentelemetry</groupId>
      <artifactId>opentelemetry-api</artifactId>
      <version>1.6.0</version>
    </dependency>
    
  2. Získejte ID trasování požadavku a ID rozsahu v kódu:

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

Vlastní telemetrická data

Naším cílem v Application Insights Java 3.x je umožnit odesílání vlastní telemetrie pomocí standardních rozhraní API.

V současné době podporujeme micrometer, oblíbené protokolovací architektury a sadu Application Insights Java 2.x SDK. Application Insights Java 3.x automaticky zachycuje telemetrii odesílanou prostřednictvím těchto rozhraní API a koreluje ji s automatickou telemetrií.

Podporovaná vlastní telemetrie

Následující tabulka představuje aktuálně podporované vlastní typy telemetrie, které můžete povolit doplnění agenta Java 3.x. Shrnutí:

  • Vlastní metriky se podporují prostřednictvím mikrometrů.
  • Vlastní výjimky a trasování se podporují prostřednictvím rozhraní protokolování.
  • Vlastní požadavky, závislosti a výjimky jsou podporovány prostřednictvím opentelemetry-api.
  • Každý typ vlastní telemetrie se podporuje prostřednictvím sady Application Insights Java 2.x SDK.
Vlastní typ telemetrie Mikrometr Log4j, logback, JUL 2.x SDK opentelemetry-api
Vlastní události Ano
Vlastní metriky Ano Ano
Závislosti Ano Ano
Výjimky Ano Ano Ano
Zobrazení stránek Ano
Žádosti Ano Ano
Trasování Ano Ano Ano

V současné době neplánujeme vydat sadu SDK se službou Application Insights 3.x.

Application Insights Java 3.x už naslouchá telemetrii odesílané do sady Application Insights Java 2.x SDK. Tato funkce je důležitou součástí scénáře upgradu pro stávající uživatele verze 2.x. A vyplní důležitou mezeru v naší vlastní podpoře telemetrie, dokud nebude rozhraní API OpenTelemetry obecně dostupné.

Odesílání vlastních metrik pomocí mikrometru

  1. Přidejte do aplikace mikrometr:

    <dependency>
      <groupId>io.micrometer</groupId>
      <artifactId>micrometer-core</artifactId>
      <version>1.6.1</version>
    </dependency>
    
  2. K vytvoření měřiče použijte globální registr Micrometer:

    static final Counter counter = Metrics.counter("test.counter");
    
  3. K zaznamenání metrik použijte čítač:

    counter.increment();
    
  4. Metriky se budou ingestovat do vlastní tabulky Metriky se značkami zachycenými ve sloupci customDimensions . Metriky můžete zobrazit také v Průzkumníku metrik v oboru názvů metrik založených na protokolech.

    Poznámka

    Application Insights Java nahradí všechny nealnumerické znaky (kromě pomlček) v názvu metriky Mikrometru podtržítky, takže test.counter výše uvedená metrika se zobrazí jako test_counter.

Odesílání vlastních trasování a výjimek pomocí oblíbené architektury protokolování

Log4j, Logback a java.util.logging jsou automaticky instrumentované. Protokolování prováděné prostřednictvím těchto rozhraní protokolování se automaticky shromažďuje jako telemetrie trasování a výjimek.

Ve výchozím nastavení se protokolování shromažďuje pouze v případě, že se protokolování provádí na úrovni INFO nebo vyšší. Pokud chcete tuto úroveň změnit, podívejte se na možnosti konfigurace.

Pokud chcete k protokolům připojit vlastní dimenze, použijte MDC Log4j 1.2, Log4j 2 MDC nebo Logback MDC. Application Insights Java 3.x automaticky zachycuje tyto vlastnosti MDC jako vlastní dimenze v telemetrii trasování a výjimek.

Odeslání vlastní telemetrie pomocí sady SDK verze 2.x

  1. Přidejte applicationinsights-core-2.6.4.jar do aplikace. Application Insights Java 3.x podporuje všechny verze 2.x. Pokud máte na výběr, je vhodné použít nejnovější verzi:

    <dependency>
      <groupId>com.microsoft.azure</groupId>
      <artifactId>applicationinsights-core</artifactId>
      <version>2.6.4</version>
    </dependency>
    
  2. Vytvoření TelemetryClient:

    static final TelemetryClient telemetryClient = new TelemetryClient();
    
  3. Pomocí klienta odešlete vlastní telemetrii:

    událost
    telemetryClient.trackEvent("WinGame");
    
    Metriky
    telemetryClient.trackMetric("queueLength", 42.0);
    
    Závislosti
    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);
    }
    
    Protokoly
    telemetryClient.trackTrace(message, SeverityLevel.Warning, properties);
    
    Výjimky
    try {
        ...
    } catch (Exception e) {
        telemetryClient.trackException(e);
    }
    

Řešení potíží

Projděte si vyhrazený článek o řešení potíží.

Poznámky k verzi

Podívejte se na poznámky k verzi na GitHubu.

Podpora

Získání podpory:

Zpětná vazba k OpenTelemetry

Poskytnutí zpětné vazby:

Další kroky