Korelacja danych telemetrycznych w usłudze Application Insights

  • Artykuł
  • Czas czytania: 10 min

W świecie mikrousług każda operacja logiczna wymaga wykonania pracy w różnych składnikach usługi. Każdy z tych składników można monitorować oddzielnie przy użyciu usługi Application Insights. Usługa Application Insights obsługuje korelację telemetrii rozproszonej, która służy do wykrywania, który składnik jest odpowiedzialny za awarie lub obniżenie wydajności.

W tym artykule wyjaśniono model danych używany przez usługę Application Insights do korelowania danych telemetrycznych wysyłanych przez wiele składników. Obejmuje ona techniki i protokoły propagacji kontekstu. Obejmuje również implementację taktyki korelacji na różnych językach i platformach.

Uwaga

31 marca 2025 r. zostanie zakończone świadczenie pomocy technicznej dla pozyskiwania klucza instrumentacji. Pozyskiwanie klucza instrumentacji będzie nadal działać, ale nie będziemy już zapewniać aktualizacji ani obsługi funkcji. Przejście do parametrów połączenia w celu skorzystania z nowych możliwości.

Model danych dla korelacji telemetrii

Usługa Application Insights definiuje model danych dla korelacji rozproszonej telemetrii. Aby skojarzyć telemetrię z operacją logiczną, każdy element telemetrii ma pole kontekstu o nazwie operation_Id. Ten identyfikator jest współużytkowany przez każdy element telemetrii w śladzie rozproszonym. Nawet jeśli utracisz dane telemetryczne z jednej warstwy, nadal można skojarzyć dane telemetryczne zgłaszane przez inne składniki.

Rozproszona operacja logiczna zwykle składa się z zestawu mniejszych operacji, które są żądaniami przetwarzanymi przez jeden ze składników. Te operacje są definiowane przez dane telemetryczne żądań. Każdy element telemetrii żądania ma swój własny id element, który identyfikuje go unikatowo i globalnie. Wszystkie elementy telemetrii (takie jak ślady i wyjątki), które są skojarzone z żądaniem, powinny ustawić operation_parentId wartość żądania na wartość .id

Każda operacja wychodząca, taka jak wywołanie HTTP do innego składnika, jest reprezentowana przez telemetrię zależności. Telemetria zależności definiuje również własne id , które jest globalnie unikatowe. Żądanie telemetrii zainicjowanej przez to wywołanie zależności używa tej id wartości jako .operation_parentId

Widok rozproszonej operacji logicznej można utworzyć przy użyciu elementów operation_Id, operation_parentIdi request.id .dependency.id Te pola definiują również kolejność przyczynowości wywołań telemetrii.

W środowisku mikrousług ślady ze składników mogą przechodzić do różnych elementów magazynu. Każdy składnik może mieć własne parametry połączenia w usłudze Application Insights. Aby uzyskać dane telemetryczne dla operacji logicznej, usługa Application Insights wysyła zapytania o dane z każdego elementu magazynu.

Gdy liczba elementów magazynu jest duża, potrzebujesz wskazówki dotyczącej tego, gdzie szukać dalej. Model danych usługi Application Insights definiuje dwa pola, aby rozwiązać ten problem: request.source i dependency.target. Pierwsze pole identyfikuje składnik, który zainicjował żądanie zależności. Drugie pole identyfikuje, który składnik zwrócił odpowiedź wywołania zależności.

Aby uzyskać informacje na temat wykonywania zapytań z wielu różnych wystąpień przy użyciu app wyrażenia zapytania, zobacz wyrażenie app() w zapytaniu usługi Azure Monitor.

Przykład

Spójrzmy na przykład. Aplikacja o nazwie Ceny akcji pokazuje bieżącą cenę rynkową akcji przy użyciu zewnętrznego interfejsu API o nazwie Stock. Aplikacja Ceny akcji ma stronę o nazwie Strona giełdowa, która zostanie otwarta w przeglądarce internetowej klienta przy użyciu polecenia GET /Home/Stock. Aplikacja wysyła zapytanie do interfejsu API stock przy użyciu wywołania GET /api/stock/valueHTTP .

Możesz przeanalizować wynikową telemetrię, uruchamiając zapytanie:

(requests | union dependencies | union pageViews)
| where operation_Id == "STYz"
| project timestamp, itemType, name, id, operation_ParentId, operation_Id

W wynikach wszystkie elementy telemetrii współużytkuje katalog główny operation_Id. Po nawiązaniu wywołania Ajax ze strony nowy unikatowy identyfikator (qJSXU) jest przypisywany do telemetrii zależności, a identyfikator elementu pageView jest używany jako operation_ParentId. Następnie żądanie serwera używa identyfikatora Ajax jako operation_ParentId.

Itemtype name ID (Identyfikator) operation_ParentId operation_Id
pageView Strona stockowa STYz STYz
Zależności GET /Home/Stock qJSXU STYz STYz
Żądanie GET Home/Stock KqKwlrSt9PA= qJSXU STYz
Zależności GET /api/stock/value bBrf2L7mm2g= KqKwlrSt9PA= STYz

Po wywołaniu GET /api/stock/value usługi zewnętrznej należy znać tożsamość tego serwera, aby można było odpowiednio ustawić dependency.target pole. Jeśli usługa zewnętrzna nie obsługuje monitorowania, target jest ustawiona na nazwę hosta usługi. Może to być na przykład stock-prices-api.com. Jeśli jednak usługa identyfikuje się, zwracając wstępnie zdefiniowany nagłówek HTTP, zawiera tożsamość usługi, target która umożliwia usłudze Application Insights tworzenie rozproszonego śledzenia przez wykonywanie zapytań dotyczących danych telemetrycznych z tej usługi.

Nagłówki korelacji używające elementu TraceContext W3C

Usługa Application Insights przechodzi do kontekstu śledzenia W3C, który definiuje:

  • traceparent: zawiera globalnie unikatowy identyfikator operacji i unikatowy identyfikator wywołania.
  • tracestate: przenosi kontekst śledzenia specyficzny dla systemu.

Najnowsza wersja zestawu SDK usługi Application Insights obsługuje protokół Trace-Context, ale może być konieczne jego wybranie. (Zachowana będzie zgodność z poprzednim protokołem korelacji obsługiwanym przez zestaw SDK usługi Application Insights).

Protokół HTTP korelacji, nazywany również identyfikatorem żądania, jest przestarzały. Ten protokół definiuje dwa nagłówki:

  • Request-Id: prowadzi globalnie unikatowy identyfikator wywołania.
  • Correlation-Context: zawiera kolekcję par name-value właściwości rozproszonego śledzenia.

Usługa Application Insights definiuje również rozszerzenie dla protokołu HTTP korelacji. Używa Request-Context par name-value do propagowania kolekcji właściwości używanych przez bezpośredniego wywołującego lub wywoływanego. Zestaw SDK usługi Application Insights używa tego nagłówka do ustawiania dependency.target pól i request.source .

Modele danych Trace-Context i Application Insights W3C są mapowe w następujący sposób:

Application Insights W3C TraceContext
Idz i RequestDependency identyfikator-nadrzędny
Operation_Id trace-id
Operation_ParentId parent-id tego zakresu nadrzędnego. To pole musi być puste, jeśli jest to zakres główny.

Aby uzyskać więcej informacji, zobacz Model danych telemetrycznych usługi Application Insights.

Włączanie obsługi śledzenia rozproszonego W3C dla aplikacji .NET

Śledzenie rozproszone oparte na protokole W3C TraceContext jest domyślnie włączone we wszystkich ostatnich zestawach SDK platformy .NET Framework/.NET Core oraz zgodność z poprzednimi wersjami protokołu Request-Id.

Włączanie obsługi śledzenia rozproszonego W3C dla aplikacji Java

Agent java 3.0

Agent java 3.0 obsługuje gotowe środowisko W3C i nie jest wymagana żadna konfiguracja.

Zestaw SDK Java

  • Konfiguracja przychodząca

    W przypadku aplikacji Java EE dodaj następujący kod do tagu <TelemetryModules> w ApplicationInsights.xml:

    <Add type="com.microsoft.applicationinsights.web.extensibility.modules.WebRequestTrackingTelemetryModule>
   <Param name = "W3CEnabled" value ="true"/>
   <Param name ="enableW3CBackCompat" value = "true" />
</Add>

    W przypadku aplikacji Spring Boot dodaj następujące właściwości:

    • azure.application-insights.web.enable-W3C=true
    • azure.application-insights.web.enable-W3C-backcompat-mode=true

  • Konfiguracja wychodząca

    Dodaj następujący kod do AI-Agent.xml:

    <Instrumentation>
  <BuiltIn enabled="true">
    <HTTP enabled="true" W3C="true" enableW3CBackCompat="true"/>
  </BuiltIn>
</Instrumentation>

    Uwaga

    Tryb zgodności z poprzednimi wersjami jest domyślnie włączony, a enableW3CBackCompat parametr jest opcjonalny. Używaj jej tylko wtedy, gdy chcesz wyłączyć zgodność z poprzednimi wersjami.

    W idealnym przypadku wyłączysz ten tryb, gdy wszystkie usługi zostaną zaktualizowane do nowszych wersji zestawów SDK obsługujących protokół W3C. Zdecydowanie zalecamy jak najszybsze przejście do tych nowszych zestawów SDK.

Ważne jest, aby upewnić się, że konfiguracje przychodzące i wychodzące są dokładnie takie same.

Włączanie obsługi śledzenia rozproszonego W3C dla aplikacji internetowych

Ta funkcja jest dostępna w programie Microsoft.ApplicationInsights.JavaScript. Jest ona domyślnie wyłączona. Aby ją włączyć, użyj distributedTracingMode konfiguracji. AI_AND_W3C zapewnia się zgodność z poprzednimi wersjami usług instrumentowanych przez usługę Application Insights.

Ważne

Aby wyświetlić wszystkie konfiguracje wymagane do włączenia korelacji, zobacz dokumentację korelacji języka JavaScript.

Korelacja telemetrii w języku OpenCensus Python

Język OpenCensus Python obsługuje kontekst śledzenia W3C bez konieczności dodatkowej konfiguracji.

Aby zapoznać się z dokumentacją, możesz znaleźć model danych OpenCensus na tej stronie usługi GitHub.

Korelacja żądań przychodzących

Język Python OpenCensus koreluje nagłówki Trace-Context W3C z żądań przychodzących do zakresów generowanych na podstawie samych żądań. Biblioteka OpenCensus będzie automatycznie korelować z integracją dla tych popularnych struktur aplikacji internetowych: Flask, Django i Pyramid. Wystarczy wypełnić nagłówki W3C Trace-Context poprawnym formatem i wysłać je za pomocą żądania.

Przykładowa aplikacja platformy Flask

from flask import Flask
from opencensus.ext.azure.trace_exporter import AzureExporter
from opencensus.ext.flask.flask_middleware import FlaskMiddleware
from opencensus.trace.samplers import ProbabilitySampler

app = Flask(__name__)
middleware = FlaskMiddleware(
    app,
    exporter=AzureExporter(),
    sampler=ProbabilitySampler(rate=1.0),
)

@app.route('/')
def hello():
    return 'Hello World!'

if __name__ == '__main__':
    app.run(host='localhost', port=8080, threaded=True)

Ten kod uruchamia przykładową aplikację Platformy Flask na komputerze lokalnym, nasłuchując na porcie 8080. Aby skorelować kontekst śledzenia, należy wysłać żądanie do punktu końcowego. W tym przykładzie curl można użyć polecenia :

curl --header "traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01" localhost:8080

Patrząc na format nagłówka Trace-Context, można uzyskać następujące informacje:

version: 00

trace-id: 4bf92f3577b34da6a3ce929d0e0e4736

parent-id/span-id: 00f067aa0ba902b7

trace-flags: 01

Jeśli spojrzysz na wpis żądania, który został wysłany do usługi Azure Monitor, zobaczysz pola wypełnione informacjami nagłówka śledzenia. Dane można znaleźć w obszarze Dzienniki (analiza) w zasobie usługi Azure Monitor Application Insights.

Zrzut ekranu przedstawiający żądanie telemetrii w obszarze Dzienniki (analiza).

Pole id jest w formacie <trace-id>.<span-id>, gdzie trace-id jest pobierany z nagłówka śledzenia, który został przekazany w żądaniu i span-id jest wygenerowaną tablicą 8-bajtową dla tego zakresu.

Pole operation_ParentId jest w formacie <trace-id>.<parent-id>, gdzie zarówno trace-id i parent-id są pobierane z nagłówka śledzenia, który został przekazany w żądaniu.

Korelacja dzienników

Język OpenCensus w języku Python umożliwia korelowanie dzienników przez dodanie identyfikatora śledzenia, identyfikatora zakresu i flagi próbkowania do rejestrowania rekordów. Te atrybuty można dodać, instalując integrację rejestrowania openCensus. Następujące atrybuty zostaną dodane do obiektów języka Python LogRecord : traceId, spanIdi traceSampled (dotyczy tylko rejestratorów utworzonych po integracji).

Zainstaluj integrację rejestrowania openCensus:

python -m pip install opencensus-ext-logging

Przykładowa aplikacja

import logging

from opencensus.trace import config_integration
from opencensus.trace.samplers import AlwaysOnSampler
from opencensus.trace.tracer import Tracer

config_integration.trace_integrations(['logging'])
logging.basicConfig(format='%(asctime)s traceId=%(traceId)s spanId=%(spanId)s %(message)s')
tracer = Tracer(sampler=AlwaysOnSampler())

logger = logging.getLogger(__name__)
logger.warning('Before the span')
with tracer.span(name='hello'):
    logger.warning('In the span')
logger.warning('After the span')

Po uruchomieniu tego kodu w konsoli programu są drukowane następujące elementy:

2019-10-17 11:25:59,382 traceId=c54cb1d4bbbec5864bf0917c64aeacdc spanId=0000000000000000 Before the span
2019-10-17 11:25:59,384 traceId=c54cb1d4bbbec5864bf0917c64aeacdc spanId=70da28f5a4831014 In the span
2019-10-17 11:25:59,385 traceId=c54cb1d4bbbec5864bf0917c64aeacdc spanId=0000000000000000 After the span

Zwróć uwagę, że istnieje spanId komunikat dziennika, który znajduje się w obrębie zakresu. Wartość spanId jest taka sama jak ta, która należy do zakresu o nazwie hello.

Dane dziennika można wyeksportować przy użyciu polecenia AzureLogHandler. Aby uzyskać więcej informacji, zobacz Konfigurowanie usługi Azure Monitor dla aplikacji w języku Python.

Możemy również przekazać informacje śledzenia z jednego składnika do drugiego w celu prawidłowej korelacji. Rozważmy na przykład scenariusz, w którym istnieją dwa składniki: module1 i module2. Moduł1 wywołuje funkcje w module 2. Aby pobrać dzienniki zarówno z module1 jednego śladu, jak i module2 w jednym śladzie, możemy użyć następującego podejścia:

# module1.py
import logging

from opencensus.trace import config_integration
from opencensus.trace.samplers import AlwaysOnSampler
from opencensus.trace.tracer import Tracer
from module2 import function_1

config_integration.trace_integrations(['logging'])
logging.basicConfig(format='%(asctime)s traceId=%(traceId)s spanId=%(spanId)s %(message)s')
tracer = Tracer(sampler=AlwaysOnSampler())

logger = logging.getLogger(__name__)
logger.warning('Before the span')
with tracer.span(name='hello'):
   logger.warning('In the span')
   function_1(tracer)
logger.warning('After the span')

# module2.py

import logging

from opencensus.trace import config_integration
from opencensus.trace.samplers import AlwaysOnSampler
from opencensus.trace.tracer import Tracer

config_integration.trace_integrations(['logging'])
logging.basicConfig(format='%(asctime)s traceId=%(traceId)s spanId=%(spanId)s %(message)s')
tracer = Tracer(sampler=AlwaysOnSampler())

def function_1(parent_tracer=None):
    if parent_tracer is not None:
        tracer = Tracer(
                    span_context=parent_tracer.span_context,
                    sampler=AlwaysOnSampler(),
                )
    else:
        tracer = Tracer(sampler=AlwaysOnSampler())

    with tracer.span("function_1"):
        logger.info("In function_1")

Korelacja telemetrii na platformie .NET

Korelacja jest domyślnie obsługiwana podczas dołączania aplikacji. Nie są wymagane żadne akcje specjalne.

Środowisko uruchomieniowe platformy .NET obsługuje dystrybucję za pomocą działania i źródła diagnostycznego

Zestaw .NET SDK usługi Application Insights używa funkcji DiagnosticSource i Activity do zbierania i korelowania danych telemetrycznych.

Korelacja telemetrii w języku Java

Agent języka Java obsługuje automatyczną korelację danych telemetrycznych. Automatycznie wypełnia wszystkie dane telemetryczne operation_id (takie jak ślady, wyjątki i zdarzenia niestandardowe) wystawione w zakresie żądania. Propaguje również nagłówki korelacji, które zostały opisane wcześniej dla wywołań między usługami za pośrednictwem protokołu HTTP, jeśli agent zestawu JAVA SDK jest skonfigurowany.

Uwaga

Agent Java usługi Application Insights automatycznie wykonuje żądania i zależności dla programów JMS, Kafka, Netty/Webflux i nie tylko. W przypadku zestawu JAVA SDK obsługiwane są tylko wywołania wykonywane za pośrednictwem klienta Apache HttpClient dla funkcji korelacji. Automatyczne propagacja kontekstu między technologiami obsługi komunikatów, takimi jak Kafka, RabbitMQ i Azure Service Bus, nie jest obsługiwana w zestawie SDK.

Aby zbierać niestandardowe dane telemetryczne, należy instrumentować aplikację przy użyciu zestawu JAVA 2.6 SDK.

Nazwy ról

Możesz dostosować sposób wyświetlania nazw składników na mapie aplikacji. W tym celu można ustawić ręcznie cloud_RoleName , wykonując jedną z następujących akcji:

  • W przypadku języka Java usługi Application Insights ustaw nazwę roli w chmurze w następujący sposób:

    {
  "role": {
    "name": "my cloud role name"
  }
}

    Nazwę roli chmury można również ustawić przy użyciu zmiennej środowiskowej APPLICATIONINSIGHTS_ROLE_NAME.

  • Zestaw Java SDK usługi Application Insights w wersji 2.5.0 lub nowszej można określić cloud_RoleName , dodając <RoleName> do pliku ApplicationInsights.xml :

    Zrzut ekranu przedstawiający przegląd usługi Application Insights i parametry połączenia. 

    <?xml version="1.0" encoding="utf-8"?>
<ApplicationInsights xmlns="http://schemas.microsoft.com/ApplicationInsights/2013/Settings" schemaVersion="2014-05-30">
   <ConnectionString>InstrumentationKey=00000000-0000-0000-0000-000000000000</ConnectionString>
   <RoleName>** Your role name **</RoleName>
   ...
</ApplicationInsights>

  • Jeśli używasz platformy Spring Boot z szablonem startowym Application Insights Spring Boot, ustaw niestandardową nazwę aplikacji w pliku application.properties :

    spring.application.name=<name-of-app>

Nazwę roli chmury można również ustawić za pomocą zmiennej środowiskowej lub właściwości systemowej. Aby uzyskać szczegółowe informacje, zobacz Konfigurowanie nazwy roli w chmurze .

Następne kroki