Použití OpenTelemetry a sledování aktivit

Tvůrce rozhraní DATA API (DAB) podporuje OpenTelemetry pro distribuované trasování a metriky, které umožňují monitorovat a diagnostikovat chování napříč rozhraními REST, GraphQL, databázovými operacemi a interním middlewarem.

Diagram znázorňující tok OpenTelemetry

Požadavky

  • Existující konfigurační soubor DAB.
  • Spuštění kolekce OpenTelemetry nebo back-endu (například Azure Monitor nebo Jaeger).
  • Rozhraní příkazového řádku pro tvorbu API dat. Instalace rozhraní příkazového řádku

Spustit nástroj

Slouží dab add-telemetry k přidání nastavení OpenTelemetry do konfigurace.

  1. Ujistěte se, že máte konfigurační soubor. Pokud ho potřebujete vytvořit, spusťte:

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

  2. Do konfiguračního souboru přidejte nastavení OpenTelemetry.

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

  3. Spusťte DAB.

    dab start

Testování v back-endu telemetrie

  1. Otevřete uživatelské rozhraní backendu nebo kolektoru OpenTelemetry.

  2. Ověřte, že trasovací data a metriky jsou přijímána pro volání REST, GraphQL nebo databází.

Poznámka:

Řídicí panel .NET Aspire je ideální součástí vývojové smyčky. Zahrnuje integrovaná zobrazení pro trasování a metriky OpenTelemetry.

Trasování tvůrce rozhraní Data API

DAB vytvoří aktivity OpenTelemetry pro:

  • Příchozí požadavky HTTP (koncové body REST)
  • Operace GraphQL
  • Databázové dotazy (na entitu)
  • Interní kroky middlewaru (například zpracování požadavků, sledování chyb)
  • Provádění nástrojů MCP (volání jednotlivých jazyků pro manipulaci s daty (DML) a volání vlastních nástrojů)

Poznámka:

Funkce tvůrce rozhraní Data API 2.0 popsané v této části jsou aktuálně ve verzi Preview a můžou se změnit před obecnou dostupností. Další informace najdete v tématu Co je nového ve verzi 2.0.

Každá aktivita zahrnuje podrobné značky (metadata), například:

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

Chyby a výjimky jsou také sledovány s podrobnými informacemi.

Metriky tvůrce rozhraní Data API

DAB generuje metriky OpenTelemetry, například:

  • Celkový počet požadavků: Počítadlo, označené podle metody HTTP, stavu, koncového bodu a typu API.
  • Chyby: Čítač označený typem chyby, metodou HTTP, stavem, koncovým bodem a typem rozhraní API
  • Doba trvání požadavku: Histogram (v milisekundách), označený metodou HTTP, stavem, koncovým bodem a typem rozhraní API.
  • Aktivní požadavky: Čítač nahoru/dolů pro souběžné požadavky.

Metriky používají rozhraní .NET Meter API a sadu OpenTelemetry SDK.

Configuration

Do svého konfiguračního souboru přidejte oddíl open-telemetry pod runtime.telemetry.

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

Command-line

Konfigurace OpenTelemetry přes 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"

Výsledná konfigurace

Poznámka:

Možnosti OpenTelemetry nejsou k dispozici na .dab configure

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

Export a vizualizace

Telemetrie se exportuje prostřednictvím sady .NET OpenTelemetry SDK do nakonfigurovaného back-endu, jako je Azure Monitor nebo Jaeger. Ujistěte se, že je backend spuštěný a dostupný na zadané adrese endpoint. Pro vizualizaci můžete použít jakýkoli back-end kompatibilní s OpenTelemetry.

Sada OpenTelemetry SDK řídí časování exportu. Exportuje trasování po dokončení aktivit. Exportuje metriky v pravidelných intervalech nakonfigurovaných sadou SDK. Pokud interval nenastavíte, sada SDK použije výchozí hodnotu.

Poznámka:

Dočasné kontejnery, které se rychle vypnou, se můžou před dokončením exportu ukončit. Povolte okno pro řádné ukončení a vyhněte se násilnému ukončení, aby mohlo dojít k vyprázdnění nevyřízené telemetrie.

Poznámky k implementaci

  • Trasování a metriky pokrývají všechny operace REST, GraphQL, MCP a databázové operace.
  • Middleware a zpracování chyb také generují telemetrii
  • Kontext se šíří prostřednictvím požadavků.

Související obsah

  • Last updated on