Wat is gedistribueerde tracering en telemetriecorrelatie?

  • Artikel

Notitie

De volgende documentatie is afhankelijk van de klassieke Application Insights-API. Het langetermijnplan voor Application Insights is het verzamelen van gegevens met behulp van OpenTelemetry. Zie Azure Monitor OpenTelemetry inschakelen voor .NET-, Node.js-, Python- en Java-toepassingen voor meer informatie.

Moderne architecturen voor cloud- en microservices hebben eenvoudige, onafhankelijk implementeerbare services ingeschakeld die de kosten verlagen en tegelijkertijd de beschikbaarheid en doorvoer verhogen. Het heeft echter al het hele systeem moeilijker gemaakt om te redeneren over en fouten op te sporen. Gedistribueerde tracering lost dit probleem op door een prestatieprofiel te bieden dat werkt als aanroepstacks voor cloud- en microservicesarchitecturen.

Azure Monitor biedt twee ervaringen voor het gebruik van gedistribueerde traceringsgegevens: de weergave voor transactiediagnose voor één transactie/aanvraag en de toepassingsoverzichtsweergave om te laten zien hoe systemen communiceren.

Application Insights kan elk onderdeel afzonderlijk bewaken en detecteren welk onderdeel verantwoordelijk is voor fouten of prestatievermindering met behulp van gedistribueerde telemetriecorrelatie. In dit artikel wordt het gegevensmodel, technieken voor contextdoorgifte, protocollen en implementatie van correlatietactieken uitgelegd op verschillende talen en platforms die worden gebruikt door Application Insights.

Gedistribueerde tracering inschakelen

Als u gedistribueerde tracering voor een toepassing wilt inschakelen, voegt u de juiste agent, SDK of bibliotheek toe aan elke service op basis van de programmeertaal.

Inschakelen via Application Insights via auto-instrumentatie of SDK's

De Application Insights-agents en SDK's voor .NET, .NET Core, Java, Node.js en JavaScript ondersteunen allemaal systeemeigen gedistribueerde tracering. Instructies voor het installeren en configureren van elke Application Insights SDK zijn beschikbaar voor:

Wanneer de juiste Application Insights SDK is geïnstalleerd en geconfigureerd, worden traceringsgegevens automatisch verzameld voor populaire frameworks, bibliotheken en technologieën door autocollectors voor SDK-afhankelijkheden. De volledige lijst met ondersteunde technologieën is beschikbaar in de documentatie voor automatisch verzamelen van afhankelijkheden.

Elke technologie kan ook handmatig worden bijgehouden met een aanroep naar TrackDependency op de TelemetryClient.

Inschakelen via OpenTelemetry

Application Insights ondersteunt nu gedistribueerde tracering via OpenTelemetry. OpenTelemetry biedt een leverancierneutrale instrumentatie voor het verzenden van traceringen, metrische gegevens en logboeken naar Application Insights. In eerste instantie heeft de OpenTelemetry-community gedistribueerde tracering uitgevoerd. Er worden nog steeds metrische gegevens en logboeken uitgevoerd.

Een volledig waarneembaarheidsverhaal omvat alle drie de pijlers. Controleer de status van onze op Azure Monitor OpenTelemetry gebaseerde aanbiedingen om de meest recente status te zien over wat er is inbegrepen, welke aanbiedingen algemeen beschikbaar zijn en ondersteuningsopties.

De volgende pagina's bestaan uit taalrichtlijnen voor het inschakelen en configureren van op OpenTelemetry gebaseerde aanbiedingen van Microsoft. Belangrijk is dat we de beschikbare functionaliteit en beperkingen van elk aanbod delen, zodat u kunt bepalen of OpenTelemetry geschikt is voor uw project.

Inschakelen via OpenCensus

Naast de Application Insights SDK's biedt Application Insights ook ondersteuning voor gedistribueerde tracering via OpenCensus. OpenCensus is een opensource,leverancierneutraal, één distributie van bibliotheken om metrische gegevensverzameling en gedistribueerde tracering voor services te bieden. Ook kan de opensource-community gedistribueerde tracering mogelijk maken met populaire technologieën zoals Redis, Memcached of MongoDB. Microsoft werkt samen aan OpenCensus met verschillende andere bewakings- en cloudpartners.

Zie Azure Monitor instellen voor uw Python-toepassing voor meer informatie over OpenCensus voor Python.

De OpenCensus-website onderhoudt API-referentiedocumentatie voor Python, Go en verschillende handleidingen voor het gebruik van OpenCensus.

Gegevensmodel voor telemetriecorrelatie

Application Insights definieert een gegevensmodel voor gedistribueerde telemetriecorrelatie. Als u telemetrie wilt koppelen aan een logische bewerking, heeft elk telemetrie-item een contextveld met de naam operation_Id. Elk telemetrie-item in de gedistribueerde tracering deelt deze id. Zelfs als u telemetrie van één laag kwijtraakt, kunt u nog steeds telemetrie koppelen die door andere onderdelen is gerapporteerd.

Een gedistribueerde logische bewerking bestaat doorgaans uit een set kleinere bewerkingen die worden verwerkt door een van de onderdelen. Telemetrie van aanvragen definieert deze bewerkingen. Elk aanvraagtelemetrie-item heeft een eigen id item dat het uniek en wereldwijd identificeert. En alle telemetrie-items (zoals traceringen en uitzonderingen) die aan de aanvraag zijn gekoppeld, moeten de operation_parentId waarde van de aanvraag idinstellen.

Afhankelijkheidstelemetrie vertegenwoordigt elke uitgaande bewerking, zoals een HTTP-aanroep naar een ander onderdeel. Het definieert ook een eigen id dat wereldwijd uniek is. Telemetrie aanvragen, geïnitieerd door deze afhankelijkheidsaanroep, gebruikt dit id als de bijbehorende operation_parentId.

U kunt een weergave van de gedistribueerde logische bewerking maken met behulp operation_Idvan , operation_parentIden request.id met dependency.id. Deze velden definiëren ook de causaliteitsvolgorde van telemetriegesprekken.

In een microservicesomgeving kunnen traceringen van onderdelen naar verschillende opslagitems gaan. Elk onderdeel kan een eigen verbindingsreeks hebben in Application Insights. Application Insights vraagt gegevens op uit elk opslagitem om telemetrie voor de logische bewerking op te halen.

Wanneer het aantal opslagitems groot is, hebt u een hint nodig over waar u hierna moet zoeken. Het Application Insights-gegevensmodel definieert twee velden om dit probleem op te lossen: request.source en dependency.target. Het eerste veld identificeert het onderdeel dat de afhankelijkheidsaanvraag heeft gestart. Het tweede veld identificeert welk onderdeel het antwoord van de afhankelijkheidsaanroep heeft geretourneerd.

Zie de app()-expressie in de Azure Monitor-query voor informatie over het uitvoeren van query's vanuit meerdere verschillende exemplaren met behulp van de app query-expressie.

Opmerking

We kijken naar een voorbeeld. In een toepassing met de naam Aandelenprijzen wordt de huidige marktkoers van een aandelen weergegeven met behulp van een externe API met de naam Aandelen. De toepassing Aandelenprijzen heeft een pagina met de naam Stock-pagina die de webbrowser van de client opent met behulp van GET /Home/Stock. De toepassing voert een query uit op de Stock-API met behulp van de HTTP-aanroep GET /api/stock/value.

U kunt de resulterende telemetrie analyseren door een query uit te voeren:

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

In de resultaten delen alle telemetrie-items de hoofdmap operation_Id. Wanneer een Ajax-aanroep vanaf de pagina wordt gedaan, wordt er een nieuwe unieke id (qJSXU) toegewezen aan de telemetrie van de afhankelijkheid en wordt de id van de pageView gebruikt als operation_ParentId. De serveraanvraag gebruikt vervolgens de Ajax-id als operation_ParentId.

itemType naam Id operation_ParentId operation_Id
Paginaweergave Voorraadpagina STYz STYz
Afhankelijkheid GET /Home/Stock qJSXU STYz STYz
aanvraag GET Home/Stock KqKwlrSt9PA= qJSXU STYz
Afhankelijkheid GET /api/stock/value bBrf2L7mm2g= KqKwlrSt9PA= STYz

Wanneer de aanroep GET /api/stock/value naar een externe service wordt uitgevoerd, moet u de identiteit van die server weten, zodat u het veld op de dependency.target juiste manier kunt instellen. Wanneer de externe service geen ondersteuning biedt voor bewaking, target wordt deze ingesteld op de hostnaam van de service. Een voorbeeld is stock-prices-api.com. Maar als de service zichzelf identificeert door een vooraf gedefinieerde HTTP-header te retourneren, target bevat deze de service-identiteit waarmee Application Insights een gedistribueerde tracering kan maken door een query uit te voeren op telemetrie van die service.

Correlatieheaders met W3C TraceContext

Application Insights gaat over naar W3C Trace-Context, waarmee het volgende wordt gedefinieerd:

  • traceparent: draagt de globaal unieke bewerkings-id en unieke id van de aanroep.
  • tracestate: Draagt systeemspecifieke traceringscontext.

De nieuwste versie van de Application Insights SDK ondersteunt het Trace-Context-protocol, maar mogelijk moet u zich hiervoor aanmelden. (Compatibiliteit met eerdere versies met het vorige correlatieprotocol dat wordt ondersteund door de Application Insights SDK wordt gehandhaafd.)

Het HTTP-correlatieprotocol, ook wel Request-Id genoemd, wordt afgeschaft. Dit protocol definieert twee headers:

  • Request-Id: draagt de wereldwijd unieke id van de aanroep.
  • Correlation-Context: bevat de verzameling naam-waardeparen van de gedistribueerde traceringseigenschappen.

Application Insights definieert ook de extensie voor het HTTP-correlatieprotocol. Het maakt gebruik Request-Context van naam-waardeparen om de verzameling eigenschappen door te geven die door de directe beller of aanroeper worden gebruikt. De Application Insights SDK gebruikt deze header om de dependency.target velden en request.source velden in te stellen.

De W3C Trace-Context - en Application Insights-gegevensmodellen worden op de volgende manier toegewezen:

Analyses van toepassingen W3C TraceContext
Id van Request en Dependency bovenliggende id
Operation_Id trace-id
Operation_ParentId bovenliggende id van het bovenliggende bereik van deze span. Dit veld moet leeg zijn als het een hoofdspanne is.

Zie het Application Insights-telemetriegegevensmodel voor meer informatie.

W3C-ondersteuning voor gedistribueerde tracering inschakelen voor .NET-apps

Gedistribueerde tracering op basis van W3C TraceContext is standaard ingeschakeld in alle recente .NET Framework/.NET Core SDK's, samen met achterwaartse compatibiliteit met het verouderde Request-Id-protocol.

Ondersteuning voor gedistribueerde W3C-tracering inschakelen voor Java-apps

Java 3.0-agent

Java 3.0-agent ondersteunt standaard W3C en er is geen configuratie meer nodig.

Java-SDK

  • Binnenkomende configuratie

    Voor Java EE-apps voegt u de volgende code toe aan de <TelemetryModules> tag in ApplicationInsights.xml:

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

    Voeg voor Spring Boot-apps de volgende eigenschappen toe:

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

  • Uitgaande configuratie

    Voeg de volgende code toe aan AI-Agent.xml:

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

    Notitie

    De compatibiliteitsmodus voor eerdere versies is standaard ingeschakeld en de enableW3CBackCompat parameter is optioneel. Gebruik deze alleen als u compatibiliteit met eerdere versies wilt uitschakelen.

    In het ideale gevallen schakelt u deze modus uit wanneer al uw services worden bijgewerkt naar nieuwere versies van SDK's die ondersteuning bieden voor het W3C-protocol. We raden u ten zeerste aan om zo snel mogelijk over te stappen op deze nieuwere SDK's.

Het is belangrijk om ervoor te zorgen dat de binnenkomende en uitgaande configuraties precies hetzelfde zijn.

Ondersteuning voor gedistribueerde W3C-tracering inschakelen voor web-apps

Deze functie is standaard ingeschakeld voor JavaScript en de headers worden automatisch opgenomen wanneer het domein van de hostingpagina hetzelfde is als het domein waar de aanvragen naar worden verzonden (bijvoorbeeld de hostingpagina is example.com en de Ajax-aanvragen worden verzonden naar example.com). Als u de modus gedistribueerde tracering wilt wijzigen, gebruikt u het distributedTracingMode configuratieveld. AI_AND_W3C wordt standaard geleverd voor achterwaartse compatibiliteit met oudere services die door Application Insights zijn geïnstrueerd.

Als de XMLHttpRequest- of Fetch Ajax-aanvragen worden verzonden naar een andere domeinhost, inclusief subdomeinen, worden de correlatieheaders niet standaard opgenomen. Als u deze functie wilt inschakelen, stelt u het enableCorsCorrelation configuratieveld in op true. Als u deze optie instelt enableCorsCorrelationtrue, bevatten alle XMLHttpRequest- en Fetch Ajax-aanvragen de correlatieheaders. Als de toepassing op de server die wordt aangeroepen, de header niet ondersteunt traceparent , kan de aanvraag mislukken, afhankelijk van of de browser/versie de aanvraag kan valideren op basis van welke headers de server accepteert. U kunt het correlationHeaderExcludedDomains configuratieveld gebruiken om het domein van de server uit te sluiten van correlatieheaderinjectie tussen onderdelen. U kunt correlationHeaderExcludedDomains: ['*.auth0.com'] bijvoorbeeld correlatieheaders uitsluiten van aanvragen die naar de Auth0-id-provider worden verzonden.

Belangrijk

Als u alle configuraties wilt zien die nodig zijn om correlatie in te schakelen, raadpleegt u de JavaScript-correlatiedocumentatie.

Telemetriecorrelatie in OpenCensus Python

OpenCensus Python ondersteunt W3C Trace-Context zonder extra configuratie.

Voor een referentie vindt u het OpenCensus-gegevensmodel op deze GitHub-pagina.

Correlatie van binnenkomende aanvragen

OpenCensus Python correleert W3C Trace-Context-headers van binnenkomende aanvragen tot de periodes die worden gegenereerd op basis van de aanvragen zelf. OpenCensus correleert automatisch met integraties voor deze populaire webtoepassingsframeworks: Flask, Django en Pyramid. U hoeft alleen de W3C Trace-Context-headers te vullen met de juiste indeling en deze te verzenden met de aanvraag.

Bekijk deze Flask-voorbeeldtoepassing. Installeer Flask, OpenCensus en de extensies voor Flask en Azure.


pip install flask opencensus opencensus-ext-flask opencensus-ext-azure

U moet uw Application Insights-verbindingsreeks toevoegen aan de omgevingsvariabele.

APPLICATIONINSIGHTS_CONNECTION_STRING=<appinsights-connection-string>

Voorbeeld van Flask-toepassing

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(
        connection_string='<appinsights-connection-string>', # or set environment variable APPLICATION_INSIGHTS_CONNECTION_STRING
    ), 
    sampler=ProbabilitySampler(rate=1.0),
)

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

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

Met deze code wordt een Flask-voorbeeldtoepassing uitgevoerd op uw lokale computer, die luistert naar de poort 8080. Als u traceringscontext wilt correleren, verzendt u een aanvraag naar het eindpunt. In dit voorbeeld kunt u een curl opdracht gebruiken:

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

Door de header-indeling Trace-Context te bekijken, kunt u de volgende informatie afleiden:

version: 00

trace-id: 4bf92f3577b34da6a3ce929d0e0e4736

parent-id/span-id: 00f067aa0ba902b7

trace-flags: 01

Als u de aanvraagvermelding bekijkt die naar Azure Monitor is verzonden, ziet u velden die zijn gevuld met de traceringsheadergegevens. U vindt de gegevens onder Logs (Analytics) in de Azure Monitor Application Insights-resource.

Screenshot that shows Request telemetry in Logs (Analytics).

Het id veld heeft de notatie <trace-id>.<span-id>, waar trace-id deze wordt opgehaald uit de traceringsheader die is doorgegeven in de aanvraag en span-id een gegenereerde matrix met 8 bytes voor deze periode is.

Het operation_ParentId veld heeft de indeling <trace-id>.<parent-id>, waarbij beide trace-idparent-id en afkomstig zijn van de traceringsheader die is doorgegeven in de aanvraag.

Logboekcorrelatie

Met OpenCensus Python kunt u logboeken correleren door een tracerings-id, een span-id en een steekproefvlag toe te voegen om records te registreren. U voegt deze kenmerken toe door de integratie van OpenCensus-logboekregistratie te installeren. De volgende kenmerken worden toegevoegd aan Python-objecten LogRecord : traceId, spanIden traceSampled (alleen van toepassing op logboekregistraties die na de integratie worden gemaakt).

Installeer de integratie van OpenCensus-logboekregistratie:

python -m pip install opencensus-ext-logging

Voorbeeldtoepassing

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')

Wanneer deze code wordt uitgevoerd, wordt het volgende afgedrukt in de console:

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

U ziet dat er een spanId presentatie is voor het logboekbericht dat binnen het bereik valt. Het spanId is hetzelfde als die waartoe de naam hellobehoort.

U kunt de logboekgegevens exporteren met behulp van AzureLogHandler. Zie Azure Monitor instellen voor uw Python-toepassing voor meer informatie.

We kunnen ook traceringsinformatie van het ene onderdeel naar het andere doorgeven voor een juiste correlatie. Denk bijvoorbeeld aan een scenario waarin er twee onderdelen zijn, module1 en module2. Module 1 roept functies aan in module 2. Voor het ophalen van logboeken van zowel als module1module2 in één trace, kunnen we de volgende aanpak gebruiken:

# module1.py
import logging

from opencensus.trace import config_integration
from opencensus.trace.samplers import AlwaysOnSampler
from opencensus.trace.tracer import Tracer
from module_2 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(logger, tracer)
logger.warning("After the span")

# module_2.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"
)
logger = logging.getLogger(__name__)
tracer = Tracer(sampler=AlwaysOnSampler())


def function_1(logger=logger, 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")

Telemetriecorrelatie in .NET

Correlatie wordt standaard verwerkt bij het onboarden van een app. Er zijn geen speciale acties vereist.

.NET Runtime ondersteunt gedistribueerd met behulp van Activiteit en DiagnosticSource

De .NET SDK van Application Insights gebruikt DiagnosticSource en Activity om telemetrie te verzamelen en correleren.

Telemetriecorrelatie in Java

Java-agent ondersteunt automatische correlatie van telemetrie. Deze wordt automatisch ingevuld operation_id voor alle telemetriegegevens (zoals traceringen, uitzonderingen en aangepaste gebeurtenissen) die zijn uitgegeven binnen het bereik van een aanvraag. Ook worden de correlatieheaders doorgegeven die eerder zijn beschreven voor service-naar-service-aanroepen via HTTP, als de Java SDK-agent is geconfigureerd.

Notitie

Application Insights Java-agent verwijdert automatisch aanvragen en afhankelijkheden voor JMS, Kafka, Netty/Webflux en meer. Voor Java SDK worden alleen aanroepen via Apache HttpClient ondersteund voor de correlatiefunctie. Automatische doorgifte van context in berichtentechnologieën zoals Kafka, RabbitMQ en Azure Service Bus wordt niet ondersteund in de SDK.

Als u aangepaste telemetrie wilt verzamelen, moet u de toepassing instrumenteren met de Java 2.6 SDK.

Rolnamen

Mogelijk wilt u de manier aanpassen waarop onderdeelnamen worden weergegeven in Toepassingsoverzicht. Hiervoor kunt u handmatig instellen cloud_RoleName door een van de volgende acties uit te voeren:

  • Stel voor Application Insights Java de naam van de cloudrol als volgt in:

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

    U kunt ook de naam van de cloudrol instellen met behulp van de omgevingsvariabele APPLICATIONINSIGHTS_ROLE_NAME.

  • Met Application Insights Java SDK 2.5.0 en hoger kunt u opgeven cloud_RoleName door dit toe te voegen aan <RoleName> uw ApplicationInsights.xml-bestand :

    Screenshot that shows Application Insights overview and connection string. 

    <?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>

  • Als u Spring Boot gebruikt met Application Insights Spring Boot Starter, stelt u uw aangepaste naam in voor de toepassing in het bestand application.properties :

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

U kunt ook de naam van de cloudrol instellen via omgevingsvariabele of systeemeigenschap. Zie Naam van cloudrol configureren voor meer informatie.

Volgende stappen