Cos’è la correlazione tra traccia distribuita e telemetria?

Articolo
11/12/2023

Nota

La documentazione seguente si basa sull'API classica di Application Insights. Il piano a lungo termine per Application Insights prevede la raccolta di dati con OpenTelemetry. Per altre informazioni, vedere Abilitare OpenTelemetry di Monitoraggio di Azure per le applicazioni .NET, Node.js, Python e Java oltre che la Roadmap OpenTelemetry. Le indicazioni sulla migrazione sono disponibili per .NET, Node.js e Python.

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, i sistemi generali più difficili sono stati resi più difficili su cui ragionare ed 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 i 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 delle applicazioni 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 via Application Insights tramite strumenti automatici o SDK

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

Dopo avere installato e configurato la versione corretta di Application Insights SDK, le informazioni di traccia vengono raccolte automaticamente per le librerie, le tecnologie e i framework più diffusi da agenti di raccolta delle dipendenze dell'SDK automatici. L'elenco completo delle tecnologie supportate è disponibile nella documentazione sulla raccolta automatica delle dipendenze.

È anche possibile tenere traccia manualmente di qualsiasi tecnologia 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 lingua per lingua 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.

Abilitare tramite OpenCensus

Oltre che tramite Application Insights SDK, Application Insights supporta la traccia distribuita anche tramite OpenCensus. OpenCensus è una singola distribuzione di librerie open source indipendente dal fornitore che fornisce raccolta di metriche e traccia distribuita per i servizi. Permette inoltre alla community open source di abilitare la traccia distribuita con tecnologie diffuse, 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 dispone di un campo di contesto denominato operation_Id. Ogni elemento di telemetria nella traccia distribuita condivide questo identificatore. Quindi, anche se si perdono dati di telemetria da un singolo livello, è comunque possibile associare i dati di telemetria segnalati da altri componenti.

Un'operazione logica distribuita consiste in genere in un set di operazioni più piccole, vale a dire richieste elaborate da uno dei componenti. I dati di telemetria delle richieste definiscono queste operazioni. Ogni elemento di telemetria delle richieste è dotato di un proprio id che la identifica in modo univoco e a livello globale. Tutti gli elementi della telemetria (ad esempio, tracce ed eccezioni) associati alla richiesta devono impostare operation_parentId sul valore di id della richiesta.

La telemetria delle dipendenze rappresenta ogni operazione in uscita, ad esempio una chiamata HTTP a un altro componente. Definisce anche il proprio id che è 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 una propria 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 è molto elevato, è necessario un hint per sapere dove cercare dopo. 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 di un'azione attuale, usando un'API esterna denominata Stock. L'applicazione Stock Prices ha una pagina denominata Stock che viene aperta dal Web browser client con GET /Home/Stock. L'applicazione esegue una query l’API Stock mediante una chiamata HTTP GET /api/stock/value.

È 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 l'elemento operation_Id radice. Quando viene eseguita una chiamata Ajax dalla pagina, viene assegnato un nuovo ID univoco (qJSXU) alla 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, si deve conoscere l'identità del relativo server per poter impostare correttamente il campo dependency.target. Quando il servizio esterno non supporta il monitoraggio, target è impostato sul nome host del servizio. Un esempio è stock-prices-api.com. Se tuttavia il servizio identifica se stesso restituendo un'intestazione HTTP predefinita, target contiene l'identità del servizio che consente ad Application Insights di creare una traccia distribuita eseguendo query sui dati di telemetria di quel servizio.

Intestazioni di correlazione con TraceContext W3C

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

traceparent: contiene l'ID operazione globalmente univoco e un 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: contiene l'ID globalmente univoco 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 per la 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 campi dependency.target 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. Questo campo deve essere vuoto se si tratta di un intervallo radice.

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

Abilitare il supporto di analisi 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 EE, aggiungere il codice seguente al tag <TelemetryModules> all'interno di 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 di analisi 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 campo di configurazione distributedTracingMode. AI_AND_W3C viene fornito per impostazione predefinita per garantire la compatibilità con le versioni precedenti con tutti i servizi legacy strumentati da Application Insights.

Configurazione basata su npm

Aggiungere la configurazione seguente:
```
  distributedTracingMode: DistributedTracingModes.W3C
```
Configurazione basata su script del caricatore SDK JavaScript (Web)

Aggiungere la configurazione seguente:
```
    distributedTracingMode: 2 // DistributedTracingModes.W3C
```

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 campo di configurazione enableCorsCorrelation su true. Se si imposta enableCorsCorrelation su true, 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 o la versione possa convalidare la richiesta in base alle intestazioni accettate dal server. È possibile usare il campo di configurazione correlationHeaderExcludedDomains 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 W3C Trace-Context 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 W3C Trace-Context 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 la 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 comando curl:

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.

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

Il campo operation_ParentId è nel formato <trace-id>.<parent-id>, dove trace-id e parent-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 per il 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 module1 e module2. 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 di dati di telemetria in Java

L'agente Java supporta la correlazione automatica dei dati di telemetria. Popola automaticamente operation_id per tutti i dati di telemetria (come tracce, eccezioni ed eventi personalizzati) rilasciati nell'ambito di una richiesta. Propaga anche le intestazioni di correlazione che sono state 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 l’SDK Java, la funzionalità di correlazione sono supportate solo le chiamate effettuate tramite Apache HTTPClient. La propagazione automatica del contesto attraverso tecnologie di messaggistica come Kafka, RabbitMQ, bus di servizio di Azure non è supportata nell’SDK.

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

Nome dei ruoli

Potrebbe a volte essere necessario personalizzare il modo in cui i nomi dei componenti vengono visualizzati nella mappa delle 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 di ambiente APPLICATIONINSIGHTS_ROLE_NAME.

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

<?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 l'utilità di avvio Spring Boot di Application Insights, 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

Mappa delle applicazioni
Scrivere dati di telemetria personalizzati.
Per scenari di correlazione avanzati in ASP.NET Core e ASP.NET, vedere Tenere traccia delle operazioni personalizzate.
Altre informazioni sull'impostazione di cloud_RoleName per altri SDK.
Caricare tutti i componenti del microservizio in Application Insights. Controllare le piattaforme supportate.
Per informazioni sui tipi di Application Insights, vedere il modello di dati.
Informazioni su come estendere e filtrare i dati di telemetria.
Vedere le informazioni di riferimento sulla configurazione di Application Insights.

Condividi tramite