Uso de OpenTelemetry y seguimientos de actividad

Data API Builder (DAB) admite OpenTelemetry para el seguimiento distribuido y las métricas, lo que le permite supervisar y diagnosticar el comportamiento en REST, GraphQL, operaciones de base de datos y middleware interno.

Prerrequisitos

• Archivo de configuración DAB existente.
• Ejecutar el recopilador o back-end de OpenTelemetry (por ejemplo, Azure Monitor o Jaeger).
• CLI para el generador de APIs de datos. Instalación de la CLI

Ejecutar herramienta

Use dab add-telemetry para agregar la configuración de OpenTelemetry a tu sistema.

1. Asegúrese de que tiene un archivo de configuración. Si necesita crear una, ejecute:

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

2. Agregue la configuración de OpenTelemetry al archivo de configuración.

   • Bash
   • Símbolo del sistemaCommand Prompt

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

3. Inicie DAB.

   dab start
   

Prueba en el back-end de telemetría

1. Abra la interfaz de usuario del servidor o recopilador de OpenTelemetry.

2. Confirme que llegan seguimientos y métricas para las llamadas a REST, GraphQL o bases de datos.

Seguimientos de Data API Builder

DAB crea "actividades" de OpenTelemetry para:

• Solicitudes HTTP entrantes (puntos de conexión REST)
• Operaciones de GraphQL
• Consultas de base de datos (por entidad)
• Pasos internos del middleware (por ejemplo, control de solicitudes, seguimiento de errores)

Cada actividad incluye etiquetas detalladas (metadatos), como:

• http.method, http.url, , http.querystring, status.code
• action.type (CRUD, operación GraphQL)
• user.role, user-agent
• data-source.type, data-source.name
• api.type (REST o GraphQL)

También se realiza un seguimiento de errores y excepciones con información detallada.

Métricas del generador de API de datos

DAB emite métricas de OpenTelemetry como:

• Total de solicitudes: contador, etiquetado por método HTTP, estado, punto de conexión y tipo de API.
• Errores: contador, etiquetado por tipo de error, método HTTP, estado, punto de conexión y tipo de API.
• Duración de la solicitud: histograma (en milisegundos), etiquetado por método HTTP, estado, punto de conexión y tipo de API.
• Solicitudes activas: contador activo/inactivo para solicitudes simultáneas.

Las métricas usan la API de .NET Meter y el SDK de OpenTelemetry.

Configuration

Agregue una open-telemetry sección en runtime.telemetry en el archivo de configuración.

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

Command-line

Configura OpenTelemetry mediante 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"

Configuración resultante

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

Exportación y visualización

La telemetría se exporta a través del SDK de OpenTelemetry de .NET al back-end configurado, como Azure Monitor o Jaeger. Asegúrese de que el back end se esté ejecutando y sea accesible en el especificado endpoint. Puede usar cualquier back-end compatible con OpenTelemetry para su visualización.

El SDK de OpenTelemetry controla el tiempo de exportación. Exporta trazas cuando las actividades se completan. Exporta las métricas en un intervalo periódico configurado por el SDK. Si no establece un intervalo, el SDK usa su valor predeterminado.

Notas de implementación

• Los seguimientos y las métricas cubren todas las operaciones rest, GraphQL y base de datos
• El middleware y los controladores de errores también emiten telemetría
• El contexto se propaga a través de solicitudes

Contenido relacionado

• Configuración en tiempo de ejecución
• Uso de Azure Application Insights