Uso de Azure Log Analytics en Data API Builder

Azure Log Analytics es una plataforma de registro centralizada que agrega registros de aplicaciones, recursos de Azure, máquinas virtuales, contenedores, etc. La integración con Data API Builder (DAB) ayuda a las empresas a cumplir los requisitos de cumplimiento, gobernanza y observabilidad. A diferencia de Application Insights (que se centra en APM), Log Analytics proporciona una agregación de registros más amplia con compatibilidad con el lenguaje de consulta kusto (KQL).

Prerrequisitos

• Archivo de configuración DAB existente.
• Suscripción de Azure con permisos para crear recursos de Log Analytics.
• Área de trabajo de Azure Log Analytics con:
  • Una tabla personalizada (que termina en _CL)
  • Una regla de recopilación de datos (DCR)
  • Un punto de conexión de recopilación de datos (DCE)
• Identidad administrada habilitada en el host de DAB (Azure App Service, Container Apps, VM, etc.).
• CLI para el generador de APIs de datos. Instalación de la CLI

Configuración de recursos de Azure Log Analytics

Antes de configurar DAB, cree los recursos de Azure necesarios.

Creación de un área de trabajo de Log Analytics

az monitor log-analytics workspace create \
  --resource-group my-rg \
  --workspace-name my-workspace \
  --location eastus

Creación de una tabla personalizada

Las tablas personalizadas para la API de ingesta de registros deben terminar con _CL.

1. En el área de trabajo de Log Analytics, vaya a Tablas.
2. Seleccione + Crear>nuevo registro personalizado (basado en DCR).
3. Escriba el nombre de la tabla (por ejemplo, DabLogs_CL).
4. Defina el esquema con estas columnas:
   • Time (fecha y hora)
   • LogLevel (cadena)
   • Message (cadena)
   • Component (cadena)
   • Identifier (cadena)
5. Selecciona Crear.

Creación de un punto de conexión de recopilación de datos (DCE)

az monitor data-collection endpoint create \
  --name my-dce \
  --resource-group my-rg \
  --location eastus \
  --public-network-access Enabled

az monitor data-collection endpoint show \
  --name my-dce \
  --resource-group my-rg \
  --query logsIngestion.endpoint -o tsv

Crear una regla de recopilación de datos (DCR)

1. Vaya a Supervisar>Reglas de Recopilación de Datos.
2. Seleccione + Create.
3. Elija suscripción, grupo de recursos, región.
4. Proporcione un nombre (por ejemplo, my-dcr).
5. En Orígenes de datos, seleccione Registros de texto personalizados.
6. Configurar:
   • Punto de conexión de recopilación de datos: seleccione el DCE.
   • Destino: área de trabajo de Log Analytics.
   • Tabla: la tabla personalizada (DabLogs_CL).
7. Seleccione Revisar y crear>Crear.
8. Copie el identificador inmutable (comienza por dcr-).

Configurar la autenticación

DAB usa La identidad administrada de Azure para autenticarse en Log Analytics. No se almacenan credenciales en la configuración.

Habilitación de la identidad administrada

az webapp identity assign \
  --name my-app \
  --resource-group my-rg

az containerapp identity assign \
  --name my-app \
  --resource-group my-rg \
  --system-assigned

Asignación de permisos

Conceda el rol Publicador de métricas de supervisión a la identidad administrada en el DCR.

# Get Managed Identity principal ID
PRINCIPAL_ID=$(az webapp identity show \
  --name my-app \
  --resource-group my-rg \
  --query principalId -o tsv)

# Get DCR resource ID
DCR_ID=$(az monitor data-collection rule show \
  --name my-dcr \
  --resource-group my-rg \
  --query id -o tsv)

# Assign role
az role assignment create \
  --assignee $PRINCIPAL_ID \
  --role "Monitoring Metrics Publisher" \
  --scope $DCR_ID

Configuración de Log Analytics

Agregue una azure-log-analytics sección bajo runtime.telemetry en su archivo de configuración.

{
  "runtime": {
    "telemetry": {
      "azure-log-analytics": {
        "enabled": true,
        "dab-identifier": "my-dab-instance",
        "flush-interval-seconds": 10,
        "auth": {
          "custom-table-name": "DabLogs_CL",
          "dcr-immutable-id": "dcr-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
          "dce-endpoint": "https://my-dce.eastus-1.ingest.monitor.azure.com"
        }
      }
    }
  }
}

Propiedades de configuración

Command-line

Configura Log Analytics mediante dab configure.

Habilitación de Log Analytics

dab configure \
  --runtime.telemetry.azure-log-analytics.enabled true

dab configure ^
  --runtime.telemetry.azure-log-analytics.enabled true

Establecimiento del identificador DAB

dab configure \
  --runtime.telemetry.azure-log-analytics.dab-identifier my-dab-instance

dab configure ^
  --runtime.telemetry.azure-log-analytics.dab-identifier my-dab-instance

Configurar intervalo de vaciado

dab configure \
  --runtime.telemetry.azure-log-analytics.flush-interval-seconds 10

dab configure ^
  --runtime.telemetry.azure-log-analytics.flush-interval-seconds 10

Establecimiento de un nombre de tabla personalizado

dab configure \
  --runtime.telemetry.azure-log-analytics.auth.custom-table-name DabLogs_CL

dab configure ^
  --runtime.telemetry.azure-log-analytics.auth.custom-table-name DabLogs_CL

Establecimiento del identificador inmutable de DCR

dab configure \
  --runtime.telemetry.azure-log-analytics.auth.dcr-immutable-id dcr-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

dab configure ^
  --runtime.telemetry.azure-log-analytics.auth.dcr-immutable-id dcr-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Configurar el punto de conexión DCE

dab configure \
  --runtime.telemetry.azure-log-analytics.auth.dce-endpoint https://my-dce.eastus-1.ingest.monitor.azure.com

dab configure ^
  --runtime.telemetry.azure-log-analytics.auth.dce-endpoint https://my-dce.eastus-1.ingest.monitor.azure.com

Ejecución de DAB

Inicie DAB con el archivo de configuración:

dab start

Verifique los registros de eventos de inicio de DAB para:

Azure Log Analytics is enabled.

Cómo funciona

Cuando Log Analytics está habilitado, DAB:

1. Se autentica en Azure mediante la identidad administrada del host.
2. Batches registra entradas basadas en flush-interval-seconds.
3. Envía registros al punto de conexión de recopilación de datos (DCE).
4. DCE enruta los registros a través de la regla de recopilación de datos (DCR) para la transformación.
5. DCR ingiere registros en la tabla personalizada de Log Analytics.

Flujo de datos

DAB Application
    ↓
ILogger (ASP.NET Core)
    ↓
Log Analytics Logger Provider
    ↓
Managed Identity Authentication
    ↓
Data Collection Endpoint (DCE)
    ↓
Data Collection Rule (DCR)
    ↓
Log Analytics Workspace (Custom Table)

¿Qué se captura?

Estructura de registro

Cada entrada de registro enviada a Log Analytics contiene estos campos:

Consulta de registros en Log Analytics

1. Abra el área de trabajo de Log Analytics en Azure Portal.

2. Vaya a Registros y ejecute una consulta KQL:

   DabLogs_CL
   | where Identifier_s == "my-dab-instance"
   | where LogLevel_s in ("Warning", "Error")
   | where TimeGenerated > ago(1h)
   | project TimeGenerated, LogLevel_s, Message_s, Component_s
   | order by TimeGenerated desc
   

Consultas de ejemplo

Recuento de registros por nivel:

DabLogs_CL
| where TimeGenerated > ago(24h)
| summarize Count=count() by LogLevel_s

Buscar errores en un componente específico:

DabLogs_CL
| where Component_s contains "SqlQueryExecutor"
| where LogLevel_s == "Error"
| project TimeGenerated, Message_s

Consideraciones sobre el rendimiento y los costos

Comportamiento de procesamiento por lotes

DAB agrupa los registros y los envía cada flush-interval-seconds:

• 5 segundos (valor predeterminado): buen equilibrio para la mayoría de los escenarios.
• 1 a 2 segundos: registro casi en tiempo real (llamadas API más altas, mayor costo).
• 10-60 segundos: llamadas API reducidas pero registros retrasados.

Optimización de costos

Los precios de Log Analytics se basan en:

1. Ingesta de datos: por GB ingeridos.
2. Retención de datos: por GB al mes después del nivel gratis.

Reducir los costos:

• Aumente flush-interval-seconds para agrupar más registros.
• Utiliza filtros de nivel de registro para excluir registros detallados. Para obtener más información, consulte Personalizar la verbosidad de los registros.
• Establezca la retención de datos adecuada en el área de trabajo de Log Analytics.

Ejemplo: Filtro para reducir el volumen

{
  "runtime": {
    "telemetry": {
      "log-level": {
        "Default": "Warning",
        "Microsoft": "Error"
      },
      "azure-log-analytics": {
        "enabled": true,
        "flush-interval-seconds": 30,
        "auth": {
          "custom-table-name": "DabLogs_CL",
          "dcr-immutable-id": "dcr-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
          "dce-endpoint": "https://my-dce.eastus-1.ingest.monitor.azure.com"
        }
      }
    }
  }
}

Esto solo envía registros de advertencia y error , lo que reduce significativamente el volumen.

Retención de datos

La retención de datos de Log Analytics se puede configurar por área de trabajo:

Configurar retención: área de trabajo de Log Analytics → Uso y costos estimados → retención de datos.

Solución de problemas

Registros que no aparecen en Log Analytics

Síntoma: DAB se inicia correctamente, pero no aparecen registros en el área de trabajo de Log Analytics.

Causas posibles:

• Configuración incompleta: compruebe si hay errores en los registros de inicio de DAB, como Logs won't be sent to Azure Log Analytics because the Custom Table Name is not available in the config file. Comprobar todas las propiedades de autenticación necesarias: custom-table-name, dcr-immutable-id, dce-endpoint.

• Identidad administrada no asignada: compruebe que la identidad administrada está habilitada con az webapp identity show --name my-app --resource-group my-rg. Compruebe la asignación de roles con az role assignment list --assignee <principal-id> --scope <dcr-id>.

• Punto de conexión de DCE incorrecto o id. de DCR: compruebe que el formato del punto de conexión DCE es https://<dce-name>.<region>-1.ingest.monitor.azure.com. Compruebe que el identificador inmutable de DCR comienza por dcr-.

• La tabla personalizada no existe: las tablas personalizadas deben terminar con _CL. El esquema de tabla debe coincidir con la estructura de registro.

Error: El intervalo de vaciado debe ser positivo

Causa: flush-interval-seconds se establece en 0 o en un valor negativo.

Solución: se establece flush-interval-seconds en un entero positivo (mínimo 1).

Los registros DAB muestran que "Azure Log Analytics está deshabilitado"

Causa: enabled está false o falta en la configuración.

Solución: establezca enabled: true en la configuración.

Log Analytics frente a Application Insights

Use Application Insights cuando necesite características de APM como el seguimiento de solicitudes, la asignación de dependencias y la generación de perfiles de rendimiento. Use Log Analytics cuando necesite el registro centralizado en varios recursos con los requisitos de cumplimiento de la empresa.

Contenido relacionado

• Utilice Application Insights
• Uso de OpenTelemetry
• Personalizar la verbosidad del registro
• Información general de reglas de recopilación de datos
• Identidades administradas para recursos de Azure