Partilhar via

Utilize o Azure Log Analytics no Builder de API de Dados

O Azure Log Analytics é uma plataforma centralizada de registo que agrega logs de aplicações, recursos Azure, VMs, contentores e muito mais. Integrá-lo com o Data API builder (DAB) ajuda as empresas a cumprir os requisitos de conformidade, governação e observabilidade. Ao contrário do Application Insights (que se foca em APM), o Log Analytics oferece uma agregação de logs mais ampla com suporte à Kusto Query Language (KQL).

Diagrama que mostra o fluxo de telemetria do Log Analytics.

Pré-requisitos

  • Ficheiro de configuração DAB existente.
  • Subscrição Azure com permissões para criar recursos de Log Analytics.
  • Azure Log Analytics workspace com:
    • Uma tabela personalizada (terminando em _CL)
    • Uma Regra de Recolha de Dados (DCR)
    • Um Ponto Final de Recolha de Dados (DCE)
  • Identidade gerida ativada no seu host DAB (Azure App Service, Container Apps, VM, etc.).
  • CLI do construtor de API de dados. Instalar a CLI

Configurar recursos Azure Log Analytics

Antes de configurar o DAB, crie os recursos necessários do Azure.

Criar uma área de trabalho do Log Analytics

  1. Navegue até Azure Portal>espaços de trabalho Log Analytics.
  2. Selecione + Criar.
  3. Escolha a sua subscrição, grupo de recursos e região.
  4. Forneça o nome do espaço de trabalho.
  5. Selecione Revisar e criar>Criar.

Criar uma tabela personalizada

Tabelas personalizadas para a API de Ingestão de Logs devem terminar em _CL.

  1. No seu espaço de trabalho de Log Analytics, navegue até Tabelas.
  2. Selecionar + Criar>novo registo personalizado (baseado em DCR).
  3. Introduza o nome da tabela (por exemplo, DabLogs_CL).
  4. Defina o esquema com estas colunas:
    • Time (data e hora)
    • LogLevel (cadeia de caracteres)
    • Message (cadeia de caracteres)
    • Component (cadeia de caracteres)
    • Identifier (cadeia de caracteres)
  5. Selecione Criar.

Criar um Endpoint de Recolha de Dados (DCE)

  1. Navegue até Monitor>Endpoints de Recolha de Dados.
  2. Selecione + Criar.
  3. Escolha a sua subscrição, grupo de recursos e região.
  4. Dê um nome (por exemplo, my-dce).
  5. Selecione Revisar e criar>Criar.
  6. Copie o URL do endpoint de Logs Ingestion (por exemplo, https://my-dce.eastus-1.ingest.monitor.azure.com).

Criar uma Regra de Recolha de Dados (DCR)

  1. Vá para Monitor>Regras de Recolha de Dados.
  2. Selecione + Criar.
  3. Escolha subscrição, grupo de recursos, região.
  4. Dê um nome (por exemplo, my-dcr).
  5. Em Fontes de Dados, selecione Registos de Texto Personalizados.
  6. Configurar:
    • Endpoint de Recolha de Dados: Selecione o seu DCE.
    • Destino: O seu espaço de trabalho de Log Analytics.
    • Tabela: A sua mesa personalizada (DabLogs_CL).
  7. Selecione Revisar e criar>Criar.
  8. Copie o ID Imutável (começa por dcr-).

Configurar a autenticação

O DAB utiliza Azure Managed Identity para autenticar no Log Analytics. Não há credenciais armazenadas na sua configuração.

Habilitar identidade gerenciada

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

Atribuir permissões

Conceda o papel de Editor de Métricas de Monitorização à sua Identidade Gerida no 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

Importante

Sem esta atribuição de funções, o DAB não pode enviar registos para a Log Analytics mesmo com a configuração correta.

Configurar Log Analytics

Adicione uma azure-log-analytics secção no runtime.telemetry seu ficheiro de configuração.

{
  "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"
        }
      }
    }
  }
}

Propriedades de configuração

Propriedade Description Predefinido Constraints
enabled Ative ou desative a integração com Log Analytics. false booleano
dab-identifier Cadeia de caracteres única para identificar entradas de log desta instância DAB. DabLogs Qualquer cadeia de caracteres
flush-interval-seconds Com que frequência (em segundos) os registos são enviados para o Log Analytics. 5 Deve ser > 0
auth.custom-table-name Nome de tabela personalizado para o seu espaço de trabalho do Log Analytics. (obrigatório) Tem de terminar com _CL
auth.dcr-immutable-id ID imutável da sua Regra de Recolha de Dados. (obrigatório) Começa com dcr-
auth.dce-endpoint URL do endpoint de recolha de dados. (obrigatório) HTTPS URL

Command-line

Configure a Análise de Registos via dab configure.

Ativar o Log Analytics

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

Definir identificador DAB

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

Definir intervalo de flush

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

Definir o nome da tabela personalizada

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

Definir o ID imutável do DCR

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

Definir o ponto final DCE

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

Executar DAB

Inicie o DAB com o seu ficheiro de configuração:

dab start

Verifique os registos de arranque do DAB para:

Azure Log Analytics is enabled.

Como funciona

Quando a funcionalidade de Log Analytics está ativada, DAB:

  1. Autentica-se no Azure usando a Identidade Gerida do anfitrião.
  2. Agrupa entradas de registo com base em flush-interval-seconds.
  3. Envia logs para o Data Collection Endpoint (DCE).
  4. O DCE encaminha os registos através da Regra de Recolha de Dados (DCR) para transformação.
  5. O DCR insere os registos na sua tabela personalizada de Análise de Logs.

Fluxo de dados

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)

O que é capturado

Tipo de telemetria Fonte Examples
Rastreios ILogger chamadas em DAB Registos de arranque, registos de execução de consultas, avisos
Errors Processamento de exceções Erros em tempo de execução, erros de configuração, erros na base de dados
Informação sobre componentes Elementos internos do DAB Qual módulo gerou o registo
ID da instância Configuração dab-identifier valor para filtragem

Estrutura do log

Cada entrada de registo enviada ao Log Analytics contém estes campos:

Campo Tipo Description Example
Time datetime Carimbo temporal (ISO 8601) 2026-01-27T14:30:00Z
LogLevel cadeia (de caracteres) Severidade de log Information, Warning, Error
Message cadeia (de caracteres) Mensagem de registo Request completed successfully
Component cadeia (de caracteres) Componente DAB que gerou o log Azure.DataApiBuilder.Service.Startup
Identifier cadeia (de caracteres) Valor a partir da dab-identifier configuração my-dab-instance

Observação

Colunas de tabelas personalizadas no Log Analytics acrescentam sufixos: _s para strings, _d para doubles, _t para datas, etc.

Consultar registos no Log Analytics

  1. Abra o seu espaço de trabalho Log Analytics no portal Azure.

  2. Navegue até aos Registos e execute uma 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

Exemplos de consultas

Contar os registos por nível:

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

Encontre erros em componentes específicos:

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

Considerações de desempenho e custos

Comportamento de agrupamento

O DAB agrupa os registos e envia-os a cada flush-interval-seconds:

  • 5 segundos (padrão): Bom equilíbrio para a maioria dos cenários.
  • 1-2 segundos: Registo quase em tempo real (chamadas API mais altas, custo mais elevado).
  • 10-60 segundos: Chamadas API reduzidas mas registos atrasados.

Otimização de custos

Os preços da Log Analytics baseiam-se em:

  1. Ingestão de dados: Por GB ingerido.
  2. Retenção de dados: Por GB por mês após o nível gratuito.

Reduza custos:

  • Aumenta flush-interval-seconds para agrupar mais logs.
  • Use filtros de nível de log para excluir logs detalhados. Para mais informação, consulte Personalizar a verbosidade dos logs.
  • Defina a retenção de dados adequada no seu espaço de trabalho de Log Analytics.

Exemplo: Filtro para reduzir o volume

{
  "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"
        }
      }
    }
  }
}

Isto envia apenas registos de Aviso e Erro , reduzindo significativamente o volume.

Retenção de dados

A retenção de dados do Log Analytics é configurável por cada espaço de trabalho:

Escalão de serviço Retenção padrão Retenção máxima
Escalão gratuito 7 dias 7 dias
Pay-as-you-go 30 dias 730 dias (2 anos)

Configurar retenção: Espaço de trabalho de Log Analytics → Utilização e custos estimados → Retenção de Dados.

Sugestão

Para requisitos de conformidade, considere arquivar logs mais antigos no Azure Storage para retenção a longo prazo.

Solução de problemas

Registos que não aparecem no Log Analytics

Sintoma: O DAB arranca com sucesso, mas não aparecem registos no seu espaço de trabalho de Análise de Logs.

Causas possíveis:

  • Configuração incompleta: Verifique os registos de arranque do DAB para erros como Logs won't be sent to Azure Log Analytics because the Custom Table Name is not available in the config file. Verificar todas as propriedades de autenticação necessárias: custom-table-name, dcr-immutable-id, dce-endpoint.

  • Identidade gerida não atribuída: Verificar se a Identidade Gerida está ativada com az webapp identity show --name my-app --resource-group my-rg. Verifique a atribuição de funções com az role assignment list --assignee <principal-id> --scope <dcr-id>.

  • Endpoint DCE ou ID DCR incorreto: Verifique se o formato do endpoint DCE está correto https://<dce-name>.<region>-1.ingest.monitor.azure.com. Verificar se o ID imutável do DCR começa com dcr-.

  • A tabela personalizada não existe: as tabelas personalizadas devem terminar com _CL. O esquema da tabela deve corresponder à estrutura logarítmica.

Erro: O intervalo de descarga deve ser positivo

Causa: flush-interval-seconds está definido para 0 ou valor negativo.

Solução: Definir flush-interval-seconds para um inteiro positivo (mínimo 1).

Os registos DAB mostram "Azure Log Analytics está desativado"

Causa: enabled está false ou está em falta na configuração.

Solução: Configura enabled: true na tua configuração.

Análise de Logs vs. Informações sobre Aplicações

Capacidade Application Insights Análise de Registos
Foco Monitorização do desempenho da aplicação (APM) Agregação centralizada de registos
Linguagem da consulta KQL KQL
Scope Aplicação única Apps, VMs, containers, Azure resources
Caso de uso Desempenho, exceções, traços Conformidade, governação, correlação entre recursos
Authentication Cadeia de ligação Identidade Gerida (via DCR/DCE)

Use o Application Insights quando precisar de funcionalidades de APM como rastreamento de pedidos, mapeamento de dependências e perfil de desempenho. Use o Log Analytics quando precisar de registos centralizados em múltiplos recursos com requisitos de conformidade empresarial.

Conteúdo relacionado

  • Last updated on