Partilhar via

Use OpenTelemetry e traces de atividade

O Data API Builder (DAB) suporta OpenTelemetry para rastreamento distribuído e métricas, permitindo-lhe monitorizar e diagnosticar comportamentos em REST, GraphQL, operações de base de dados e middleware interno.

Diagrama que mostra o fluxo da OpenTelemetry.

Pré-requisitos

  • Ficheiro de configuração DAB existente.
  • Executando o coletor OpenTelemetry ou backend (por exemplo, Azure Monitor ou Jaeger).
  • CLI do construtor de API de dados. Instalar a CLI

Executar ferramenta

Usa dab add-telemetry para adicionar definições do OpenTelemetry à tua configuração.

  1. Certifica-te de que tens um ficheiro de configuração. Se precisares de criar uma, executa:

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

  2. Adicione as definições do OpenTelemetry ao seu ficheiro de configuração.

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

  3. Inicia DAB.

    dab start

Teste no seu backend de telemetria

  1. Abre o backend do OpenTelemetry ou da interface do coletor.

  2. Confirme que os traços e métricas estão a chegar para chamadas REST, GraphQL ou bases de dados.

Observação

O painel .NET Aspire é uma parte ideal do ciclo de programação. Inclui vistas incorporadas para traços e métricas do OpenTelemetry.

Traços construtores de APIs de dados

O DAB cria "atividades" OpenTelemetry para:

  • Solicitações HTTP de entrada (pontos de extremidade REST)
  • Operações GraphQL
  • Consultas à base de dados (por entidade)
  • Etapas internas do middleware (por exemplo, tratamento de pedidos, rastreio de erros)

Cada atividade inclui tags detalhadas (metadados), tais como:

  • http.method, http.url, http.querystring, status.code
  • action.type (CRUD, operação GraphQL)
  • user.role, user-agent
  • data-source.type, data-source.name
  • api.type (REST ou GraphQL)

Erros e exceções também são rastreados com informações detalhadas.

Métricas do construtor de APIs de dados

O DAB emite métricas OpenTelemetry como:

  • Total de Pedidos: Contador, rotulado por método HTTP, estado, endpoint e tipo de API.
  • Erros: Contador, rotulado por tipo de erro, método HTTP, estado, endpoint e tipo de API.
  • Duração do Pedido: Histograma (em milissegundos), rotulado pelo método HTTP, estado, endpoint e tipo de API.
  • Pedidos Ativos: Contador para subir/descer para pedidos concorrentes.

As métricas usam a API do .NET Meter e o SDK do OpenTelemetria.

Configuration

Adicione uma open-telemetry seção em runtime.telemetry seu arquivo de configuração.

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

Command-line

Configure OpenTelemetry via 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"

Configuração resultante

Observação

As opções OpenTelemetry não estão disponíveis em dab configure.

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

Exportação e visualização

A telemetria é exportada via .NET OpenTelemetry SDK para o seu backend configurado, como Azure Monitor ou Jaeger. Certifique-se de que o seu back-end está a funcionar e acessível no local especificado endpoint. Podes usar qualquer backend compatível com OpenTelemetry para visualização.

O SDK OpenTelemetry controla o tempo de exportação. Exporta traços quando as atividades terminam. Exporta métricas num intervalo periódico configurado pelo SDK. Se não definires um intervalo, o SDK usa o seu padrão.

Observação

Contentores efémeros que desligam rapidamente podem sair antes das exportações estarem concluídas. Permita uma janela de desligamento controlado e evite terminação agressiva para que a telemetria pendente possa ser concluída.

Notas sobre a aplicação

  • Os traços e métricas abrangem todas as operações REST, GraphQL e bases de dados
  • Middleware e manipuladores de erros também emitem telemetria
  • O contexto é propagado por meio de solicitações

Conteúdo relacionado

  • Last updated on