Uso de Azure Application Insights en data API Builder

Azure Application Insights es un servicio de supervisión del rendimiento de aplicaciones (APM) que captura automáticamente las solicitudes, seguimientos, excepciones y métricas de rendimiento. La integración con Data API Builder (DAB) le ayuda a supervisar el comportamiento en tiempo de ejecución, diagnosticar problemas y optimizar el rendimiento en producción.

Prerrequisitos

• Archivo de configuración DAB existente.
• Recurso de Azure Application Insights.
• Cadena de conexión de Application Insights.
• CLI para el generador de APIs de datos. Instalación de la CLI

Obtener cadena de conexión

Antes de configurar DAB, obtenga la cadena de conexión de Application Insights de Azure.

Portal de Azure

1. Vaya al recurso de Application Insights en Azure Portal.
2. Vaya a Información general o Propiedades.
3. Copie la cadena de conexión (no la clave de instrumentación).

CLI de Azure

az monitor app-insights component show \
  --app my-app-insights \
  --resource-group my-rg \
  --query connectionString -o tsv

az monitor app-insights component show ^
  --app my-app-insights ^
  --resource-group my-rg ^
  --query connectionString -o tsv

Formato de la cadena de conexión

InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://<region>.in.applicationinsights.azure.com/;LiveEndpoint=https://<region>.livediagnostics.monitor.azure.com/

Configurar Application Insights

Agregue una application-insights sección bajo runtime.telemetry en su archivo de configuración.

{
  "runtime": {
    "telemetry": {
      "application-insights": {
        "enabled": true,
        "connection-string": "@env('app-insights-connection-string')"
      }
    }
  }
}

Esta configuración usa una variable de entorno para la cadena de conexión. Defínelo en un .env archivo:

app-insights-connection-string="InstrumentationKey=...;IngestionEndpoint=...;LiveEndpoint=..."

Command-line

Configure el Application Insights mediante dab add-telemetry.

Habilitación de Application Insights

dab add-telemetry \
  --app-insights-enabled true \
  --app-insights-conn-string "@env('app-insights-connection-string')"

dab add-telemetry ^
  --app-insights-enabled true ^
  --app-insights-conn-string "@env('app-insights-connection-string')"

Deshabilitación de Application Insights

dab add-telemetry \
  --app-insights-enabled false

dab add-telemetry ^
  --app-insights-enabled false

Ejecución de DAB

Inicie DAB con el archivo de configuración:

dab start

Compruebe los registros de inicio para obtener confirmación:

Application Insights telemetry is enabled with connection string from config.

Cómo funciona

Cuando Application Insights está habilitado, DAB:

1. Registra el SDK de Application Insights mediante AddApplicationInsightsTelemetry().
2. Registra un inicializador de telemetría personalizado para enriquecer todos los datos de telemetría con propiedades específicas de DAB.
3. Configura TelemetryClient con la cadena de conexión de la configuración.
4. Se integra con el registro de ASP.NET Core para capturar registros de consola como seguimientos.

Flujo de datos

DAB Application
    ↓
ILogger (ASP.NET Core)
    ↓
ApplicationInsightsLoggerProvider
    ↓
AppInsightsTelemetryInitializer (adds custom properties)
    ↓
TelemetryClient
    ↓
Application Insights (Azure)

¿Qué se captura?

Enriquecimiento de telemetría

DAB enriquece automáticamente toda la telemetría de Application Insights con propiedades personalizadas:

Estas propiedades ayudan a filtrar y correlacionar la telemetría específica de DAB en Application Insights.

Consulta de telemetría en Azure

Seguimientos (registros)

traces
| where customDimensions["ProductName"] startswith "dab-"
| order by timestamp desc
| project timestamp, message, severityLevel

Asignación de LogLevel:

Requests

requests
| where customDimensions["ProductName"] startswith "dab-"
| order by timestamp desc
| project timestamp, name, duration, resultCode, success

Excepciones

exceptions
| where customDimensions["ProductName"] startswith "dab-"
| order by timestamp desc
| project timestamp, type, outerMessage, details

Filtrar por versión de DAB

traces
| where customDimensions["Component.Version"] == "1.2.3"
| project timestamp, message, severityLevel

Encuentra consultas lentas de GraphQL

requests
| where name contains "/graphql"
| where duration > 1000
| project timestamp, name, duration, resultCode
| order by duration desc

Tasa de éxito de solicitudes

requests
| where customDimensions["ProductName"] startswith "dab-"
| summarize 
    Total = count(),
    Success = countif(success == true),
    Failed = countif(success == false)
| extend SuccessRate = (Success * 100.0) / Total

Principales operaciones lentas de base de datos

dependencies
| where type == "SQL" or type == "Azure Cosmos DB"
| top 10 by duration desc
| project timestamp, name, duration, target, data

Métricas en Tiempo Real

Live Metrics proporciona supervisión en tiempo real con <una latencia de 1 segundo. Se habilita automáticamente cuando Application Insights está configurado.

Acceso a las métricas dinámicas

1. Abra su recurso de Application Insights en Azure Portal.
2. Vaya a Live Metrics en el menú de la izquierda.
3. Inicie la aplicación DAB.
4. En segundos, aparecen datos en tiempo real.

Lo que ve

Muestreo y retención de datos

Muestreo adaptable

El SDK de Application Insights muestra automáticamente la telemetría cuando el volumen es alto para reducir los costos y mantenerse dentro de los límites de velocidad. La frecuencia de muestreo se muestra en la interfaz de usuario de Application Insights.

Comportamiento predeterminado:

• Tráfico bajo: toda la telemetría enviada (100%)
• Tráfico elevado: el muestreo automáticamente reduce el volumen.
• Datos representativos mantenidos

Retención de datos

Configurar retención: Application Insights → Uso y costos estimados → retención de datos.

Consideraciones sobre el rendimiento

Sobrecarga de telemetría

Application Insights agrega una sobrecarga mínima:

• Memoria: ~10-50 MB en función del tráfico
• CPU: <1% bajo carga normal
• Latencia: <1 ms por solicitud (asincrónico)

procedimientos recomendados

• Use variables de entorno para cadenas de conexión.
• Desactívelo en el desarrollo local si no es necesario.
• Controle la frecuencia de muestreo en producción.
• Establezca la retención de datos adecuada para administrar los costos.

Deshabilitación en el desarrollo

{
  "runtime": {
    "telemetry": {
      "application-insights": {
        "enabled": false
      }
    }
  }
}

Exportación y visualización

La telemetría se exporta mediante el SDK de Application Insights. El SDK realiza lotes y envía datos periódicamente.

Cadena de conexión frente a clave de instrumentación

Uso de cadenas de conexión (recomendado)

{
  "connection-string": "InstrumentationKey=...;IngestionEndpoint=https://eastus.in.applicationinsights.azure.com/"
}

Ventajas:

• Puntos de conexión específicos de la región (menor latencia)
• Admite nubes soberanas
• Preparado para el futuro (enfoque recomendado de Microsoft)

Clave de instrumentación heredada

Aunque Microsoft todavía admite su uso, recomienda cadenas de conexión para nuevas implementaciones.

{
  "connection-string": "InstrumentationKey=00000000-0000-0000-0000-000000000000"
}

Solución de problemas

Error: "La cadena de conexión de Application Insights no puede ser nula ni estar vacía si está habilitada"

Causa: enabled está establecido en true pero connection-string falta o está vacío.

Solución: Proporcione una cadena de conexión válida al habilitar Application Insights, o establezca enabled en false.

{
  "runtime": {
    "telemetry": {
      "application-insights": {
        "enabled": true,
        "connection-string": "@env('app-insights-connection-string')"
      }
    }
  }
}

DAB se inicia, pero no aparece telemetría

Compruebe los registros de inicio de estos mensajes:

dab start --LogLevel Information

dab start --LogLevel Information

Mensaje de éxito:

Application Insights telemetry is enabled with connection string from config.

Mensajes de advertencia:

Logs won't be sent to Application Insights because an Application Insights connection string is not available in the runtime config.

Application Insights are disabled.

Mensaje de error:

Telemetry client is not initialized.

Comprobación de la variable de entorno

echo $app-insights-connection-string

echo %app-insights-connection-string%

Prueba con cadena de conexión directa

Use temporalmente una cadena de conexión directa (no variable de entorno) para comprobar que la cadena es válida:

{
  "connection-string": "InstrumentationKey=...;IngestionEndpoint=..."
}

Si esto funciona, el problema es con la carga de variables de entorno.

Contenido relacionado

• Uso de Azure Log Analytics
• Uso de OpenTelemetry
• Personalizar la verbosidad del registro
• Introducción a Application Insights
• Application Insights para ASP.NET Core