Usare OpenTelemetry e il tracciamento delle attività

Il generatore di API dati supporta OpenTelemetry per la traccia distribuita e le metriche, consentendo di monitorare e diagnosticare il comportamento in REST, GraphQL, operazioni di database e middleware interno.

Prerequisiti

• File di configurazione DAB esistente.
• Esecuzione del collector o back-end OpenTelemetry, ad esempio Azure Monitor o Jaeger.
• CLI generatore di API dati. Installare l'interfaccia della riga di comando

Eseguire lo strumento

Usare dab add-telemetry per aggiungere le impostazioni di OpenTelemetry alla configurazione.

1. Assicurarsi di disporre di un file di configurazione. Se è necessario crearne uno, eseguire:

   dab init \
       --database-type mssql \
       --connection-string "<sql-connection-string>"
   

2. Aggiungere le impostazioni di OpenTelemetry al file di configurazione.

   • Bash
   • Prompt dei comandi

   dab add-telemetry \
       -c dab-config.json \
       --otel-enabled true \
       --otel-endpoint "http://localhost:4317" \
       --otel-protocol "grpc" \
       --otel-service-name "dab"
   

3. Avviare DAB.

   dab start
   

Testare nel back-end di telemetria

1. Aprire l'interfaccia utente del back-end o dell'agente di raccolta OpenTelemetry.

2. Verificare che le tracce e le metriche arrivino per chiamate REST, GraphQL o al database.

Tracce del generatore di API dati

DAB crea "attività" di OpenTelemetry per:

• Richieste HTTP in ingresso (endpoint REST)
• operazioni GraphQL
• Query di database (per entità)
• Passaggi del middleware interno (ad esempio, gestione delle richieste, rilevamento degli errori)

Ogni attività include tag dettagliati (metadati), ad esempio:

• http.method, http.url, http.querystringstatus.code
• action.type (CRUD, operazione GraphQL)
• user.role, user-agent
• data-source.type, data-source.name
• api.type (REST o GraphQL)

Anche gli errori e le eccezioni vengono tracciati con informazioni dettagliate.

Metriche del generatore di API dati

DAB genera metriche OpenTelemetry, ad esempio:

• Totale richieste: contatore, etichettato da metodo HTTP, stato, endpoint e tipo di API.
• Errori: contatore, etichettato per tipo di errore, metodo HTTP, stato, endpoint e tipo di API.
• Durata richiesta: istogramma (in millisecondi), etichettato da metodo HTTP, stato, endpoint e tipo di API.
• Richieste attive: contatore su/giù per le richieste simultanee.

Le metriche usano l'API .NET Meter e OpenTelemetry SDK.

Configuration

Aggiungere una open-telemetry sezione in runtime.telemetry nel file di configurazione.

{
    "runtime": {
        "telemetry": {
            "open-telemetry": {
                "enabled": true,
                "endpoint": "http://otel-collector:4317",
                "service-name": "dab",
                "exporter-protocol": "grpc"
            }
        }
    }
}

Command-line

Configurare OpenTelemetry tramite dab add-telemetry.

• --otel-enabled
• --otel-endpoint
• --otel-protocol
• --otel-service-name
• --otel-headers

Example

dab add-telemetry \
    -c dab-config.json \
    --otel-enabled true \
    --otel-endpoint "http://localhost:4317" \
    --otel-protocol "grpc" \
    --otel-service-name "dab"

dab add-telemetry ^
    -c dab-config.json ^
    --otel-enabled true ^
    --otel-endpoint "http://localhost:4317" ^
    --otel-protocol "grpc" ^
    --otel-service-name "dab"

Configurazione risultante

{
    "runtime": {
        "telemetry": {
            "open-telemetry": {
                "enabled": true,
                "endpoint": "http://localhost:4317",
                "service-name": "dab",
                "exporter-protocol": "grpc"
            }
        }
    }
}

Esportare e visualizzare

I dati di telemetria vengono esportati tramite il .NET OpenTelemetry SDK nel back-end configurato, come Azure Monitor o Jaeger. Verificare che il back-end sia in esecuzione e raggiungibile all'indirizzo specificato endpoint. È possibile usare qualsiasi back-end compatibile con OpenTelemetry per la visualizzazione.

OpenTelemetry SDK controlla i tempi di esportazione. Esporta tracce al termine delle attività. Esporta le metriche in un intervallo periodico configurato dall'SDK. Se non si imposta un intervallo, l'SDK usa il valore predefinito.

Note sull'implementazione

• Le tracce e le metriche coprono tutte le operazioni REST, GraphQL e database
• I gestori di middleware e di errore generano anche dati di telemetria
• Il contesto viene propagato tramite richieste

Contenuti correlati

• Configurazione del runtime
• Usare Azure Application Insights