Condividi tramite

Che cos'è la traccia distribuita e la correlazione dei dati di telemetria?

  • Articolo

Nota

La documentazione seguente si basa sull'API classica di Application Insights. Il piano a lungo termine per Application Insights consiste nel raccogliere dati usando OpenTelemetry. Per altre informazioni, vedere Abilitare OpenTelemetry di Monitoraggio di Azure per le applicazioni .NET, Node.js, Python e Java.

Le architetture moderne di cloud e microservizi hanno abilitato servizi semplici e indipendenti che riducono i costi aumentando la disponibilità e la velocità effettiva. Tuttavia, ha reso i sistemi generali più difficili da ragionare e eseguire il debug. La traccia distribuita risolve questo problema fornendo un profiler prestazioni che funziona come gli stack di chiamate per le architetture cloud e microservizi.

Monitoraggio di Azure offre due esperienze per l'utilizzo dei dati di traccia distribuiti: la visualizzazione diagnostica delle transazioni per una singola transazione/richiesta e la visualizzazione mappa dell'applicazione per mostrare l'interazione dei sistemi.

Application Insights può monitorare ogni componente separatamente e rilevare quale componente è responsabile di errori o riduzione delle prestazioni usando la correlazione di telemetria distribuita. Questo articolo illustra il modello di dati, le tecniche di propagazione del contesto, i protocolli e l'implementazione di tattiche di correlazione su linguaggi e piattaforme diversi usati da Application Insights.

Abilitare la traccia distribuita

Per abilitare la traccia distribuita per un'applicazione, aggiungere l'agente, l'SDK o la libreria corretti a ogni servizio in base al linguaggio di programmazione.

Abilitare tramite Application Insights tramite strumenti automatici o SDK

Gli agenti e gli SDK di Application Insights per .NET, .NET Core, Java, Node.js e JavaScript supportano la traccia distribuita in modo nativo. Le istruzioni per l'installazione e la configurazione di ogni SDK di Application Insights sono disponibili per:

Con l'SDK di Application Insights appropriato installato e configurato, le informazioni di traccia vengono raccolte automaticamente per framework, librerie e tecnologie comuni in base aicolletori delle dipendenze sdk. L'elenco completo delle tecnologie supportate è disponibile nella documentazione relativa alla raccolta automatica delle dipendenze.

Qualsiasi tecnologia può anche essere rilevata manualmente con una chiamata a TrackDependency in TelemetryClient.

Abilitare tramite OpenTelemetry

Application Insights supporta ora la traccia distribuita tramite OpenTelemetry. OpenTelemetry fornisce una strumentazione indipendente dal fornitore per inviare tracce, metriche e log ad Application Insights. Inizialmente, la community di OpenTelemetry ha assunto la traccia distribuita. Le metriche e i log sono ancora in corso.

Una storia di osservabilità completa include tutti e tre i pilastri. Controllare lo stato delle offerte basate su OpenTelemetry di Monitoraggio di Azure per visualizzare lo stato più recente delle opzioni incluse, quali offerte sono disponibili a livello generale e opzioni di supporto.

Le pagine seguenti sono costituite da linee guida relative alla lingua per linguaggio per abilitare e configurare le offerte basate su OpenTelemetry di Microsoft. È importante condividere le funzionalità e le limitazioni disponibili di ogni offerta in modo da determinare se OpenTelemetry è adatto al progetto.

Eseguire l'abilitazione tramite OpenCensus

Oltre che tramite Application Insights SDK, Application Insights supporta la traccia distribuita anche tramite OpenCensus. OpenCensus è una distribuzione singola e indipendente dal fornitore open source delle librerie per fornire la raccolta delle metriche e la traccia distribuita per i servizi. Consente inoltre alla community open source di abilitare la traccia distribuita con tecnologie comuni come Redis, Memcached o MongoDB. Microsoft collabora al progetto OpenCensus con diversi altri partner cloud e che si occupano di monitoraggio.

Per altre informazioni su OpenCensus per Python, vedere Configurare Monitoraggio di Azure per l'applicazione Python.

Il sito Web OpenCensus gestisce la documentazione di riferimento sulle API per Python, Go e varie guide per l'uso di OpenCensus.

Modello di dati per la correlazione di dati di telemetria

Application Insights definisce un modello di dati per la correlazione di dati di telemetria distribuita. Per associare i dati di telemetria a un'operazione logica, ogni elemento di telemetria ha un campo di contesto denominato operation_Id. Ogni elemento di telemetria nella traccia distribuita condivide questo identificatore. Pertanto, anche se si perdono i dati di telemetria da un singolo livello, è comunque possibile associare i dati di telemetria segnalati da altri componenti.

Un'operazione logica distribuita è in genere costituita da un set di operazioni più piccole elaborate da uno dei componenti. I dati di telemetria delle richieste definiscono queste operazioni. Ogni elemento di telemetria della richiesta ha un proprio id elemento che lo identifica in modo univoco e globale. E tutti gli elementi di telemetria, ad esempio tracce ed eccezioni, associati alla richiesta devono impostare su operation_parentId il valore della richiesta id.

La telemetria delle dipendenze rappresenta ogni operazione in uscita, ad esempio una chiamata HTTP a un altro componente. Definisce anche il proprio id oggetto univoco a livello globale. La telemetria delle richieste, avviata dalla chiamata di dipendenza, usa questo id come operation_parentId.

È possibile creare una visualizzazione dell'operazione logica distribuita usando operation_Id, operation_parentId e request.id con dependency.id. Questi campi definiscono anche l'ordine della causalità delle chiamate di telemetria.

In un ambiente di microservizi, le tracce dai componenti possono finire in elementi di archiviazione diversi. Ogni componente può avere un proprio stringa di connessione in Application Insights. Per ottenere dati di telemetria per l'operazione logica, Application Insights esegue query sui dati da ogni elemento di archiviazione.

Quando il numero di elementi di archiviazione è elevato, è necessario un suggerimento sulla posizione successiva. Per risolvere questo problema, nel modello di dati di Application Insights sono definiti due campi: request.source e dependency.target. Il primo campo identifica il componente che ha avviato la richiesta di dipendenza. Il secondo campo identifica il componente che ha restituito la risposta della chiamata di dipendenza.

Per informazioni sull'esecuzione di query da più istanze diverse usando l'espressione app di query, vedere espressione app() nella query di Monitoraggio di Azure.

Esempio

Di seguito è descritto un esempio. Un'applicazione denominata Stock Prices mostra il prezzo di mercato corrente di un titolo usando un'API esterna denominata Stock. L'applicazione Prezzi azionari ha una pagina denominata Pagina stock visualizzata dal Web browser client tramite GET /Home/Stock. L'applicazione esegue una query sull'API Stock usando la chiamata GET /api/stock/valueHTTP .

È possibile analizzare i dati di telemetria risultanti eseguendo una query:

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

Nei risultati tutti gli elementi di telemetria condividono la radice operation_Id. Quando viene effettuata una chiamata Ajax dalla pagina, viene assegnato un nuovo ID univoco (qJSXU) ai dati di telemetria delle dipendenze e l'ID di pageView viene usato come operation_ParentId. La richiesta server usa quindi l'ID Ajax come operation_ParentId.

itemType name ID operation_ParentId operation_Id
pageView Pagina Stock STYz STYz
dependency GET /Home/Stock qJSXU STYz STYz
request GET /Home/Stock KqKwlrSt9PA= qJSXU STYz
dependency GET /api/stock/value bBrf2L7mm2g= KqKwlrSt9PA= STYz

Quando la chiamata GET /api/stock/value viene effettuata a un servizio esterno, è necessario conoscere l'identità del server in modo da poter impostare il dependency.target campo in modo appropriato. Quando il servizio esterno non supporta il monitoraggio, target viene impostato sul nome host del servizio. Un esempio è stock-prices-api.com. Tuttavia, se il servizio si identifica restituendo un'intestazione HTTP predefinita, target contiene l'identità del servizio che consente ad Application Insights di compilare una traccia distribuita eseguendo query sui dati di telemetria da tale servizio.

Intestazioni di correlazione con TraceContext W3C

Application Insights esegue la transizione a W3C Trace-Context, che definisce:

  • traceparent: porta l'ID operazione univoco globale e l'identificatore univoco della chiamata.
  • tracestate: porta il contesto di traccia specifico del sistema.

La versione più recente di Application Insights SDK supporta il protocollo Trace-Context, ma potrebbe essere necessario acconsentire esplicitamente. La compatibilità con le versioni precedenti con il protocollo di correlazione precedente supportato da Application Insights SDK viene mantenuta.

Il protocollo HTTP di correlazione, detto anche Request-Id, è deprecato. Questo protocollo definisce due intestazioni:

  • Request-Id: porta l'ID univoco globale della chiamata.
  • Correlation-Context: contiene la raccolta di coppie nome-valore delle proprietà della traccia distribuita.

Application Insights definisce anche l'estensione per il protocollo HTTP di correlazione. Usa le coppie nome-valore Request-Context per propagare la raccolta di proprietà usate dal chiamante o dal destinatario della chiamata. Application Insights SDK usa questa intestazione per impostare i dependency.target campi e request.source .

I modelli di dati W3C Trace-Context e Application Insights sono mappati nel modo seguente:

Application Insights W3C TraceContext
Id di Request e Dependency parent-id
Operation_Id trace-id
Operation_ParentId parent-id dell'intervallo padre di questo intervallo padre. Questo campo deve essere vuoto se si tratta di un intervallo radice.

Per altre informazioni, vedere Modello di dati di telemetria di Application Insights.

Abilitare il supporto della traccia distribuita W3C per le app .NET

La traccia distribuita basata su W3C TraceContext è abilitata per impostazione predefinita in tutti gli SDK recenti di .NET Framework/.NET Core, insieme alla compatibilità con le versioni precedenti con il protocollo Request-Id legacy.

Abilitare il supporto di analisi distribuita W3C per le app Java

Agente Java 3.0

L'agente Java 3.0 supporta W3C per impostazione predefinita e non sono necessarie altre configurazioni.

SDK per Java

  • Configurazione in ingresso

    Per le app Java edizione Enterprise, aggiungere il codice seguente al <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>

    Per le app Spring Boot, aggiungere queste proprietà:

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

  • Configurazione in uscita

    Aggiungere il codice seguente a AI-Agent.xml:

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

    Nota

    La modalità di compatibilità con le versioni precedenti è abilitata per impostazione predefinita e il parametro enableW3CBackCompat è facoltativo. Usarlo solo per disattivare la compatibilità con le versioni precedenti.

    Idealmente, si disattiva questa modalità quando tutti i servizi vengono aggiornati alle versioni più recenti degli SDK che supportano il protocollo W3C. È consigliabile passare a questi SDK più recenti il prima possibile.

È importante assicurarsi che le configurazioni in ingresso e in uscita siano esattamente le stesse.

Abilitare il supporto della traccia distribuita W3C per le app Web

Questa funzionalità è abilitata per impostazione predefinita per JavaScript e le intestazioni vengono incluse automaticamente quando il dominio della pagina di hosting corrisponde al dominio a cui vengono inviate le richieste ( ad esempio, la pagina di hosting è example.com e le richieste Ajax vengono inviate a example.com). Per modificare la modalità di traccia distribuita, usare il distributedTracingMode campo di configurazione. AI_AND_W3C viene fornito per impostazione predefinita per garantire la compatibilità con le versioni precedenti con tutti i servizi legacy instrumentati da Application Insights.

Se le richieste XMLHttpRequest o Fetch Ajax vengono inviate a un host di dominio diverso, inclusi i sottodomini, le intestazioni di correlazione non sono incluse per impostazione predefinita. Per abilitare questa funzionalità, impostare il enableCorsCorrelation campo di configurazione su true. Se si imposta su enableCorsCorrelationtrue, tutte le richieste XMLHttpRequest e Fetch Ajax includono le intestazioni di correlazione. Di conseguenza, se l'applicazione sul server chiamato non supporta l'intestazione traceparent , la richiesta potrebbe non riuscire, a seconda che il browser/versione possa convalidare la richiesta in base alle intestazioni accettate dal server. È possibile usare il correlationHeaderExcludedDomains campo di configurazione per escludere il dominio del server dall'inserimento dell'intestazione di correlazione tra componenti. Ad esempio, è possibile usare correlationHeaderExcludedDomains: ['*.auth0.com'] per escludere le intestazioni di correlazione dalle richieste inviate al provider di identità Auth0.

Importante

Per visualizzare tutte le configurazioni necessarie per abilitare la correlazione, vedere la documentazione sulla correlazione JavaScript.

Correlazione dei dati di telemetria in OpenCensus Python

OpenCensus Python supporta il contesto di traccia W3C senza richiedere una configurazione aggiuntiva.

Per un riferimento, è possibile trovare il modello di dati OpenCensus in questa pagina di GitHub.

Correlazione delle richieste in ingresso

OpenCensus Python correla le intestazioni del contesto di traccia W3C dalle richieste in ingresso agli intervalli generati dalle richieste stesse. OpenCensus correla automaticamente con le integrazioni per questi framework di applicazioni Web più diffusi: Flask, Django e Pyramid. È sufficiente popolare le intestazioni W3C Trace-Context con il formato corretto e inviarle con la richiesta.

Esplorare questa applicazione Flask di esempio. Installare Flask, OpenCensus e le estensioni per Flask e Azure.


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

È necessario aggiungere il stringa di connessione di Application Insights alla variabile di ambiente.

APPLICATIONINSIGHTS_CONNECTION_STRING=<appinsights-connection-string>

Applicazione Flask di esempio

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)

Questo codice esegue un'applicazione Flask di esempio nel computer locale, in ascolto della porta 8080. Per correlare il contesto di traccia, inviare una richiesta all'endpoint. In questo esempio è possibile usare un curl comando:

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

Esaminando il formato di intestazione Trace-Context, è possibile derivare le informazioni seguenti:

version: 00

trace-id: 4bf92f3577b34da6a3ce929d0e0e4736

parent-id/span-id: 00f067aa0ba902b7

trace-flags: 01

Se si esamina la voce di richiesta inviata a Monitoraggio di Azure, è possibile visualizzare i campi popolati con le informazioni sull'intestazione di traccia. È possibile trovare i dati in Log (Analisi) nella risorsa Application Insights di Monitoraggio di Azure.

Screenshot that shows Request telemetry in Logs (Analytics).

Il id campo è nel formato <trace-id>.<span-id>, dove trace-id viene ricavato dall'intestazione di traccia passata nella richiesta ed span-id è una matrice a 8 byte generata per questo intervallo.

Il operation_ParentId campo è nel formato <trace-id>.<parent-id>, dove e trace-idparent-id vengono ricavati dall'intestazione di traccia passata nella richiesta.

Correlazione dei registri

OpenCensus Python consente di correlare i log aggiungendo un ID di traccia, un ID intervallo e un flag di campionamento per registrare i record. Questi attributi vengono aggiunti installando l'integrazione della registrazione OpenCensus. Gli attributi seguenti vengono aggiunti agli oggetti Python LogRecord : traceId, spanIde traceSampled (applicabile solo per i logger creati dopo l'integrazione).

Installare l'integrazione della registrazione OpenCensus:

python -m pip install opencensus-ext-logging

Applicazione di esempio

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

Quando questo codice viene eseguito, nella console viene stampato quanto segue:

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

Si noti che è presente un spanId messaggio di log compreso nell'intervallo. è spanId uguale a quello che appartiene all'intervallo denominato hello.

È possibile esportare i dati di log usando AzureLogHandler. Per altre informazioni, vedere Configurare Monitoraggio di Azure per l'applicazione Python.

È anche possibile passare informazioni di traccia da un componente a un altro per una correlazione corretta. Si consideri, ad esempio, uno scenario in cui sono presenti due componenti e module1module2. Il modulo 1 chiama le funzioni nel modulo 2. Per ottenere i log sia da module1 che module2 in una singola traccia, è possibile usare l'approccio seguente:

# 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")

Correlazione di dati di telemetria in .NET

La correlazione viene gestita per impostazione predefinita durante l'onboarding di un'app. Non sono necessarie azioni speciali.

Il runtime .NET supporta la distribuzione con l'aiuto di Activity e DiagnosticSource

Application Insights .NET SDK usa DiagnosticSource e Activity per raccogliere e correlare i dati di telemetria.

Correlazione dei dati di telemetria in Java

L'agente Java supporta la correlazione automatica dei dati di telemetria. Popola operation_id automaticamente per tutti i dati di telemetria,ad esempio tracce, eccezioni ed eventi personalizzati, rilasciati nell'ambito di una richiesta. Propaga anche le intestazioni di correlazione descritte in precedenza per le chiamate da servizio a servizio tramite HTTP, se l'agente Java SDK è configurato.

Nota

L'agente Java di Application Insights rileva automaticamente le richieste e le dipendenze per JMS, Kafka, Netty/Webflux e altro ancora. Per Java SDK, per la funzionalità di correlazione sono supportate solo le chiamate effettuate tramite Apache HttpClient. La propagazione automatica del contesto tra tecnologie di messaggistica come Kafka, RabbitMQ e bus di servizio di Azure non è supportata nell'SDK.

Per raccogliere dati di telemetria personalizzati, è necessario instrumentare l'applicazione con Java 2.6 SDK.

Nome dei ruoli

È possibile personalizzare il modo in cui i nomi dei componenti vengono visualizzati in Mappa applicazioni. A tale scopo, è possibile impostare cloud_RoleName manualmente eseguendo una delle azioni seguenti:

  • Per Application Insights Java, impostare il nome del ruolo cloud come indicato di seguito:

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

    È anche possibile impostare il nome del ruolo cloud usando la variabile APPLICATIONINSIGHTS_ROLE_NAMEdi ambiente .

  • Con Application Insights Java SDK 2.5.0 e versioni successive, è possibile specificare cloud_RoleName aggiungendo <RoleName> al file ApplicationInsights.xml :

    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>

  • Se si usa Spring Boot con Application Insights Spring Boot Starter, impostare il nome personalizzato per l'applicazione nel file application.properties :

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

È anche possibile impostare il nome del ruolo cloud tramite la variabile di ambiente o la proprietà di sistema. Per informazioni dettagliate, vedere Configurazione del nome del ruolo cloud.

Passaggi successivi