Coletar logs e métricas com Azure Log Analytics

Este artigo descreve o destino Azure Log Analytics para o Emitter de Diagnóstico do Fabric Apache Spark usando a API de Ingestão de Log.

Fabric Apache Spark Diagnostic Emissor fornece um modelo comum de configuração para diagnósticos do Spark em diferentes destinos. Para Azure Log Analytics, a API de Ingestão de Log é o modelo de ingestão recomendado.

Este artigo mostra como configurar propriedades do emissor, rotear logs do Apache Spark, logs de eventos e métricas para Log Analytics e consultar os dados ingeridos para monitoramento e solução de problemas.

Para obter detalhes sobre arquitetura e seleção de destino no Fabric Apache Spark Diagnostic Emitter, consulte a visão geral do Fabric Apache Spark Diagnostic Emitter.

Migrar da API do Coletor de Dados

Se você estiver usando atualmente a API do Coletor de Dados HTTP, migre para a API de Ingestão de Logs para se alinhar aos padrões atuais de ingestão Azure Monitor.

Principais alterações no novo modelo:

• As definições de esquema são explícitas por meio de DCRs (Regras de Coleta de Dados), o que fornece validação de esquema previsível e resultados de consulta mais consistentes do que a abordagem de conteúdo de forma livre mais antiga.
• A ingestão é roteada por meio de DCEs (pontos de extremidade de coleta de dados) e mapeamentos de DCR, fornecendo assim um caminho de ingestão mais controlado do que postar diretamente no endpoint API do Coletor de Dados.
• A autenticação dá suporte ao segredo do cliente da entidade de serviço e às opções baseadas em certificado .
• O tipo de emissor muda de AzureLogAnalytics para AzureLogIngestion.

A migração normalmente inclui a criação de recursos DCR e DCE, atualização das propriedades do Ambiente Spark do Fabric e validação da ingestão de dados em tabelas de Log Analytics personalizadas.

Visão geral da API de Ingestão de Log

Para diagnóstico do Apache Spark em Microsoft Fabric, a API de Ingestão de Log fornece um modelo de ingestão estruturado para autenticação, definição de esquema, roteamento e entrega de tabela em Azure Log Analytics.

Componentes principais

Somente DCRs criadas pelo usuário configuradas para a API de Ingestão de Log podem ser usadas para ingestão programática.

Configuração passo a passo

Etapa 1. Preparar espaço de trabalho do Log Analytics

Um workspace Log Analytics é necessário para receber o diagnóstico do Spark. É a unidade básica de armazenamento e consulta para Azure Monitor Logs.

Se você não tiver um, crie um Log Analytics workspace no portal do Azure.

Etapa 2. Criar um ponto de extremidade de coleta de dados (DCE)

Crie um Endpoint (DCE) de Coleta de Dados no portal do Azure. O DCE fornece a URI do endpoint que você configura nas propriedades do Spark para a API de Ingestão de Logs. A região do DCE deve ser a mesma que a região do Log Analytics workspace.

1. No portal Azure, acesse Monitor no painel de navegação esquerdo.

2. Em Configurações, selecione Pontos de extremidade de coleta de dados e, em seguida, selecione Criar.

   

3. Crie o endpoint e anote o nome DCE (por exemplo, DCEdemo).

Etapa 3. Preparar o esquema JSON de exemplo

Ao criar tabelas de log personalizadas, você deve configurar uma DCR (Regra de Coleta de Dados). Com base nas definições de fluxo de dados especificadas no DCR, o sistema gera automaticamente o esquema de tabela correspondente em seu workspace Log Analytics.

Os exemplos de esquema JSON predefinidos a seguir são mapeados, cada um, para um tipo de dado específico. Baixe o exemplo que se ajusta ao seu cenário e carregue-o quando você criar a tabela personalizada associada e o DCR.

• Logs de eventos do Spark – Exemplo de esquema JSON da tabela de eventos
• Logs de driver e executor do Spark – exemplo de esquema JSON da tabela de log
• Métricas do Spark – Exemplo de esquema JSON da tabela de métricas
• Metadados de plataforma – exemplo de esquema JSON da tabela de metadados da plataforma

Veja um exemplo de esquema JSON para uma tabela de logs dos registros de driver e executor do Spark no Azure Log Analytics. Use esse esquema como referência ao criar suas tabelas personalizadas e DCRs para ingestão de log.

[
  {
    "applicationId_s": "<APPLICATION_ID>",
    "applicationName_s": "<NOTEBOOK_NAME>",
    "artifactId_g": "<ARTIFACT_GUID>",
    "artifactType_s": "SynapseNotebook",
    "capacityId_g": "<CAPACITY_GUID>",
    "Category": "Log",
    "executorId_s": "driver",
    "executorMax_s": 9,
    "executorMin_s": 1,
    "ExtraFields": {
      "Category": "Log",
      "JobId": "1"
    },
    "fabricEnvId_g": "<FABRIC_ENV_GUID>",
    "fabricLivyId_g": "<FABRIC_LIVY_GUID>",
    "fabricTenantId_g": "<FABRIC_TENANT_GUID>",
    "fabricWorkspaceId_g": "<FABRIC_WORKSPACE_GUID>",
    "isHighConcurrencyEnabled_s": false,
    "Level": "INFO",
    "logger_name_s": "org.apache.spark.scheduler.dynalloc.ExecutorMonitor",
    "Message": "Executor 1 is removed.",
    "thread_name_s": "spark-listener-group-executorManagement",
    "TimeGenerated": "<TIME_GENERATED>",
    "userId_g": "<USER_ID>"
  }
]

Etapa 4. Criar tabela personalizada (Ingestão Direta)

Crie uma tabela personalizada em seu workspace Log Analytics com a opção de API de Ingestão de Log e carregue o exemplo de esquema JSON no DCR associado. Essa etapa é necessária para configurar o destino do diagnóstico do Spark e garantir que os dados ingeridos estejam em conformidade com o esquema esperado. A região do Workspace Log Analytics, do DCE e do DCR deve ser a mesma para uma ingestão bem-sucedida.

1. No Azure portal, abra o workspace Log Analytics (por exemplo, loganalyticsworkspacedemo).

2. Selecione Tabelas>Criar>Novo log personalizado (Ingestão Direta).

   

3. Insira as configurações da tabela:

   • Nome da tabela: por exemplo, SparkLogTest (sufixo "_CL" é adicionado automaticamente).
   • Plano de Tabela: Análise
   • Regra de coleta de dados: criar um novo DCR (por exemplo, SparkLogTestrule).
   • Ponto de Extremidade de Coleta de Dados: selecione o DCE na etapa Criar um Ponto de Extremidade de Coleta de Dados (DCE) (por exemplo, DCEdemo).

   

4. Selecione Próximo.

5. Em Esquema e Transformação, carregue o exemplo de esquema JSON. Você não precisa configurar a transformação DCR porque o esquema está totalmente estabilizado no lado do cliente.

Etapa 5. Preparar o principal do serviço para autenticação

1. Registre um aplicativo em Microsoft Entra ID.

   

2. Registre TenantId, ClientId e ClientSecret (se você usar a autenticação de segredo do cliente). Use esses valores na configuração do Spark na Etapa 6.

3. Conceda ao aplicativo a função Monitoring Metrics Publisher no recurso DCR de cada tabela. Para as etapas de atribuição de funções, consulte Atribuir funções do Azure usando o portal do Azure.

   

Etapa 6. Configurar propriedades do Spark

Para configurar o Spark, crie um ambiente no Fabric e escolha uma das opções de autenticação a seguir. Use apenas uma opção para um determinado emissor.

Um ambiente no Fabric armazena configurações e bibliotecas do Spark que notebooks e definições de tarefas do Spark usam em tempo de execução. Para obter as etapas para criar uma, consulte Criar, configurar e usar um ambiente em Fabric.

• Escolha a Opção 1 se quiser uma configuração mais simples usando um segredo do cliente.
• Escolha Option 2 se sua organização exigir autenticação baseada em certificado e gerenciamento centralizado de certificados no Azure Key Vault.

Em ambas as opções, você pode selecionar Adicionar a partir de .yml no ambiente para importar um .yml arquivo de configuração.

Opção 1: configurar com principal de serviço e segredo do cliente

Use esta opção para configuração rápida com credenciais de principal de serviço e um segredo de cliente.

1. Crie um ambiente no Fabric.

2. Adicione as seguintes propriedades do Spark com os valores apropriados ao ambiente ou selecione Adicionar de .yml na barra de ferramentas para importar um .yml arquivo de configuração.

   spark.synapse.diagnostic.emitters: <EMITTER_NAME>
   spark.synapse.diagnostic.emitter.<EMITTER_NAME>.type: AzureLogIngestion
   spark.synapse.diagnostic.emitter.<EMITTER_NAME>.categories: DriverLog,ExecutorLog,EventLog,Metrics
   spark.synapse.diagnostic.emitter.<EMITTER_NAME>.dceUri: https://<DCE_NAME>.<REGION>.ingest.monitor.azure.com
   spark.synapse.diagnostic.emitter.<EMITTER_NAME>.logDcr: <LOG_DCR_ID>
   spark.synapse.diagnostic.emitter.<EMITTER_NAME>.logStream: <LOG_STREAM_NAME>
   spark.synapse.diagnostic.emitter.<EMITTER_NAME>.eventDcr: <EVENT_DCR_ID>
   spark.synapse.diagnostic.emitter.<EMITTER_NAME>.eventStream: <EVENT_STREAM_NAME>
   spark.synapse.diagnostic.emitter.<EMITTER_NAME>.metricDcr: <METRIC_DCR_ID>
   spark.synapse.diagnostic.emitter.<EMITTER_NAME>.metricStream: <METRIC_STREAM_NAME>
   spark.synapse.diagnostic.emitter.<EMITTER_NAME>.metaDcr: <META_DCR_ID>
   spark.synapse.diagnostic.emitter.<EMITTER_NAME>.metaStream: <META_STREAM_NAME>
   spark.synapse.diagnostic.emitter.<EMITTER_NAME>.secret: <SP_CLIENT_SECRET>
   spark.synapse.diagnostic.emitter.<EMITTER_NAME>.tenantId: <SP_TENANT_ID>
   spark.synapse.diagnostic.emitter.<EMITTER_NAME>.clientId: <SP_CLIENT_ID>
   spark.fabric.pools.skipStarterPools: 'true'
   

3. Salve e publique as alterações.

Opção 2: configurar com a autenticação de certificado da entidade de serviço

Use essa opção quando sua organização exigir autenticação baseada em certificado.

Antes de começar, certifique-se de que o principal de serviço foi criado com um certificado. Para obter mais informações, consulte Criar uma entidade de serviço que contém um certificado usando Azure CLI.

1. Crie um ambiente no Fabric.

2. Adicione as seguintes propriedades do Spark com os valores apropriados ao ambiente ou selecione Adicionar de .yml na barra de ferramentas para importar um .yml arquivo de configuração.

   spark.synapse.diagnostic.emitters: <EMITTER_NAME>
   spark.synapse.diagnostic.emitter.<EMITTER_NAME>.type: AzureLogIngestion
   spark.synapse.diagnostic.emitter.<EMITTER_NAME>.categories: DriverLog,ExecutorLog,EventLog,Metrics
   spark.synapse.diagnostic.emitter.<EMITTER_NAME>.dceUri: https://<DCE_NAME>.<REGION>.ingest.monitor.azure.com
   spark.synapse.diagnostic.emitter.<EMITTER_NAME>.logDcr: <LOG_DCR_ID>
   spark.synapse.diagnostic.emitter.<EMITTER_NAME>.logStream: <LOG_STREAM_NAME>
   spark.synapse.diagnostic.emitter.<EMITTER_NAME>.eventDcr: <EVENT_DCR_ID>
   spark.synapse.diagnostic.emitter.<EMITTER_NAME>.eventStream: <EVENT_STREAM_NAME>
   spark.synapse.diagnostic.emitter.<EMITTER_NAME>.metricDcr: <METRIC_DCR_ID>
   spark.synapse.diagnostic.emitter.<EMITTER_NAME>.metricStream: <METRIC_STREAM_NAME>
   spark.synapse.diagnostic.emitter.<EMITTER_NAME>.metaDcr: <META_DCR_ID>
   spark.synapse.diagnostic.emitter.<EMITTER_NAME>.metaStream: <META_STREAM_NAME>
   spark.synapse.diagnostic.emitter.<EMITTER_NAME>.certificate.keyVault.certificateName: <SP_CERT-NAME>
   spark.synapse.diagnostic.emitter.<EMITTER_NAME>.certificate.keyVault: https://<KEYVAULT_NAME>.vault.azure.net/
   spark.synapse.diagnostic.emitter.<EMITTER_NAME>.tenantId: <SP_TENANT_ID>
   spark.synapse.diagnostic.emitter.<EMITTER_NAME>.clientId: <SP_CLIENT_ID>
   spark.fabric.pools.skipStarterPools: 'true'
   

3. Salve e publique as alterações.

Etapa 7. Anexe o ambiente a notebooks ou definições de trabalho do Spark, ou estabeleça-o como padrão do espaço de trabalho

Use uma das seguintes abordagens com base em seu escopo:

• Anexe o ambiente a notebooks específicos ou definições de tarefas do Spark quando desejar controle direcionado, testes ou controle por item.
• Defina o ambiente como padrão do espaço de trabalho quando desejar que as configurações consistentes de diagnóstico do Spark sejam aplicadas em todo o espaço de trabalho.

Para anexar o ambiente a notebooks ou definições de tarefa do Spark:

1. Navegue até o bloco de anotações ou a definição de trabalho do Spark em Fabric.
2. Selecione o menu Ambiente no guia Página Inicial e selecione o ambiente configurado.
3. A configuração será aplicada após iniciar uma sessão do Spark.

Para definir o ambiente como padrão do espaço de trabalho:

1. Navegue até as configurações do Workspace no Fabric.
2. Localize as configurações do Spark nas configurações do workspace (Configurações do workspace>Data Engineering/Science>configurações do Spark).
3. Selecione a guia Ambiente e escolha o ambiente com as propriedades do Spark de diagnóstico configuradas e selecione Salvar.

Passo 8. Executar cargas de trabalho do Spark e verificar logs e métricas

Use o ambiente que você criou e anexou na seção anterior e, em seguida, execute cargas de trabalho do Spark e verifique a ingestão em Log Analytics.

1. Execute cargas de trabalho do Spark usando o ambiente configurado na seção anterior. Você pode usar um dos seguintes métodos:
   • Execute um bloco de anotações em Fabric.
   • Envie um trabalho em lote do Spark por meio de uma definição de trabalho do Spark.
   • Execute atividades do Spark em um pipeline.
2. Abra o espaço de trabalho Log Analytics de destino e verifique se os logs e as métricas estão sendo ingeridos para a carga de trabalho em execução.
3. Para validar a ingestão e inspecionar registros, use os exemplos do Kusto nos dados de consulta com o Kusto.

Gravar logs personalizados de aplicativos

Use logs de aplicativos personalizados quando desejar eventos específicos do aplicativo ou de nível comercial, além do diagnóstico de plataforma. Esses logs são emitidos por meio do mesmo pipeline de diagnóstico e aparecem em Log Analytics junto com logs do Spark, logs de eventos e métricas.

Use o Apache Log4j em seu código Spark para emitir mensagens de log personalizadas. Os exemplos a seguir mostram um padrão mínimo para Scala e PySpark.

Exemplo de Scala:

%%spark
val logger = org.apache.log4j.LogManager.getLogger("com.contoso.LoggerExample")
logger.info("info message")
logger.warn("warn message")
logger.error("error message")
//log exception
try {
      1/0
 } catch {
      case e:Exception =>logger.warn("Exception", e)
}
// run job for task level metrics
val data = sc.parallelize(Seq(1,2,3,4)).toDF().count()

Exemplo do PySpark:

%%pyspark
logger = sc._jvm.org.apache.log4j.LogManager.getLogger("com.contoso.PythonLoggerExample")
logger.info("info message")
logger.warn("warn message")
logger.error("error message")

Consultar dados com o Kusto

Use consultas Kusto para validar se a ingestão está funcionando e investigar o comportamento de execução do Spark. Substitua valores de espaço reservado, como {FabricWorkspaceId}, {ArtifactId}e {LivyId} por valores de sua própria execução.

Comece com consultas de eventos e logs para confirmar a chegada dos dados e, em seguida, use consultas de métrica para análise de desempenho.

Para consultar eventos do Apache Spark:

SparkEventTest_CL
| where fabricWorkspaceId_g == "{FabricWorkspaceId}" and artifactId_g == "{ArtifactId}" and fabricLivyId_g == "{LivyId}"
| order by TimeGenerated desc
| limit 100 

Para consultar os logs do driver e do executor do aplicativo Spark:

SparkLogTest_CL
| where fabricWorkspaceId_g == "{FabricWorkspaceId}" and artifactId_g == "{ArtifactId}" and fabricLivyId_g == "{LivyId}"
| order by TimeGenerated desc
| limit 100 

Para consultar as métricas do Apache Spark:

SparkMetricsTest_CL
| where fabricWorkspaceId_g == "{FabricWorkspaceId}" and artifactId_g == "{ArtifactId}" and fabricLivyId_g == "{LivyId}"
| where name_s endswith "jvm.total.used"
| summarize max(value_d) by bin(TimeGenerated, 30s), executorId_s
| order by TimeGenerated asc

Para consultar metadados da plataforma:

SparkMetadataTest_CL 
| where fabricWorkspaceId_g == "{FabricWorkspaceId}" and artifactId_g == "{ArtifactId}" and fabricLivyId_g == "{LivyId}"
| order by TimeGenerated desc
| limit 100

Espaços de trabalho do Fabric com rede virtual gerenciada

Suporte de Fabric para habilitação da proteção contra exfiltração de dados para workspaces. Com a proteção contra exfiltração, os logs e as métricas não podem ser enviados diretamente para os endpoints de destino. Você pode criar pontos de extremidade privados gerenciados correspondentes para diferentes pontos de extremidade de destino nesse cenário.

Configurações disponíveis do Apache Spark

A tabela a seguir lista as configurações do Spark para enviar logs e métricas para Azure Log Analytics usando a API de Ingestão de Log.

Conteúdo relacionado

• Criar uma definição de trabalho do Apache Spark
• Criar, configurar e usar um ambiente no Microsoft Fabric
• Desenvolva, execute e gerencie notebooks do Microsoft Fabric
• Monitorar aplicativos Spark
• Coletar diagnósticos do Apache Spark usando Azure Event Hubs
• Colete diagnósticos do Apache Spark usando a Conta de Armazenamento do Azure