Coletar logs e métricas com Azure Log Analytics

Este artigo descreve como usar o destino Azure Log Analytics para diagnóstico do Apache Spark em Azure Synapse Analytics usando a API de Ingestão de Log.

A emissão de diagnósticos do Apache Spark no Azure Synapse fornece um modelo de configuração unificado para coletar diagnósticos do Spark em todos os destinos compatíveis. Para Azure Log Analytics, a API de Ingestão de Log é o mecanismo de ingestão recomendado.

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

Migrar da API do Coletor de Dados

Se você estiver usando a API do Coletor de Dados HTTP no Azure Synapse Analytics, migre para a API de Ingestão de Log para se alinhar com a arquitetura de ingestão Azure Monitor mais recente e as práticas recomendadas.

Principais alterações no novo modelo:

• As definições de esquema são definidas explicitamente por meio de DCRs (Regras de Coleta de Dados), fornecendo validação previsível de esquema e resultados de consulta mais consistentes em comparação com a abordagem de conteúdo de forma livre anterior.
• O fluxo de ingestão é roteado por meio de DCEs (pontos de extremidade de coleta de dados) e mapeamentos de DCR, oferecendo um caminho de ingestão mais controlado e confiável do que postar dados diretamente no ponto de extremidade de API do Coletor de Dados.
• A autenticação suporta tanto service principal com segredo do cliente quanto autenticação baseada em certificado.
• O tipo de emissor muda de AzureLogAnalytics para AzureLogIngestion.
• A migração normalmente envolve criar recursos DCR e DCE, atualizar as configurações do pool do Apache Spark no Azure Synapse (por exemplo, a configuração do Spark ou as configurações de diagnóstico) e validar que os dados sejam ingeridos com êxito em tabelas personalizadas no Azure Log Analytics.

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

Para diagnóstico do Apache Spark em Azure Synapse Analytics, 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 dados 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.

Opcionalmente, os usuários podem criar um ou mais tipos de tabela (logs, events, ), metricsdependendo de seu cenário, e cada tipo de tabela tem sua própria configuração de DCR correspondente e o nome do fluxo. Crie e configure apenas os tipos de tabela de que você realmente precisa.

1. No portal do Azure, vá para 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 no workspace do 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

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

Crie uma tabela personalizada no workspace do Log Analytics com a opção 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 espaço de trabalho da análise de logs, DCE e DCR deve ser a mesma para que a ingestão ocorra corretamente.

1. No portal do Azure, abra o workspace do 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 a entidade de serviço e coletar o identificador de DCR

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 Editor de Métricas de Monitoramento 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.

   

4. Recupere o nome do fluxo e a ID do DCR. Você pode recuperar o ID de DCR e o nome do fluxo de cada tabela que você criou na exibição JSON do recurso Data Collection Rule (DCR) no portal do Azure.

   O formato de nome do fluxo é sempre: Custom-<Log Analytics table name>. Por exemplo, se o nome da tabela for AppLogs_CL, o nome do fluxo será: Custom-AppLogs_CL.

   Na próxima etapa, você configurará os valores correspondentes de logStream, eventStream e metricStream, bem como os valores de logDcr, eventDcr e metricDcr, na configuração do Spark usando os nomes desses fluxos.

   

Etapa 6. Configurar propriedades do Spark

Para configurar o Spark, crie uma Configuração do Apache Spark no Azure Synapse Analytics e escolha uma das opções de autenticação a seguir. Use apenas uma opção para um determinado emissor.

Uma configuração do Apache Spark no Azure Synapse Analytics armazena as configurações e bibliotecas do Spark que os notebooks e as definições de trabalho do Spark usam no runtime. Para obter as etapas para criar uma, consulte Gerenciar a configuração do Apache Spark.

• Escolha a Opção 1 se quiser uma configuração mais simples usando um segredo do cliente.
• Escolha a Opção 2 se sua organização exigir autenticação baseada em certificado e gerenciamento centralizado de certificados no Azure Key Vault.
• Escolha a Opção 3 se você usar autenticação baseada em certificados e quiser recuperar o certificado do Azure Key Vault por um serviço vinculado do Synapse (o MSI do espaço de trabalho acessa o Key Vault).

Em qualquer opção, você pode clicar no botão Importar para carregar rapidamente um arquivo YAML de configuração.

Opção 1: configurar com entidade 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 uma configuração do Apache Spark.

2. Adicione as seguintes propriedades do Spark com os valores apropriados no artefato de ambiente ou selecione Importar na faixa de opções para baixar o arquivo YAML de exemplo, que já contém as propriedades necessárias.

   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>.tenantId: <SP_TENANT_ID>
   spark.synapse.diagnostic.emitter.<EMITTER_NAME>.clientId: <SP_CLIENT_ID>
   spark.synapse.diagnostic.emitter.<EMITTER_NAME>.secret: <SP_CLIENT_SECRET>
   

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 a entidade de serviço foi criada com um certificado. Para obter mais informações, consulte Criar uma entidade de serviço que contém um certificado usando a CLI do Azure.

1. Crie uma configuração do Apache Spark.

2. Adicione as seguintes propriedades do Spark com os valores apropriados no artefato de ambiente ou selecione Importar na faixa de opções para baixar o arquivo YAML de exemplo, que já contém as propriedades necessárias.

   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>.tenantId: "<SP_TENANT_ID>"
   spark.synapse.diagnostic.emitter.<EMITTER_NAME>.clientId: "<SP_CLIENT_ID>"
   spark.synapse.diagnostic.emitter.<EMITTER_NAME>.certificate.keyVault: "https://<KEYVAULT_NAME>.vault.azure.net/"
   spark.synapse.diagnostic.emitter.<EMITTER_NAME>.certificate.keyVault.certificateName: "<SP_CERT_NAME>"
   

3. Salve e publique as alterações.

Opção 3: Configurar com um serviço vinculado

Execute as seguintes etapas para configurar um serviço vinculado ao Key Vault no Synapse Studio a fim de armazenar a o certificado da entidade de serviço:

1. Siga todas as etapas na seção anterior, "Opção 2".

2. Crie um serviço vinculado Key Vault no Synapse Studio:

   a. Vá para Synapse Studio>Manage>Linked services e selecione New.

   B. Na caixa de pesquisa, pesquise Azure Key Vault.

   c. Insira um nome para o serviço vinculado.

   d. Escolha seu cofre de chaves e selecione Criar.

3. Adicione um spark.synapse.diagnostic.emitter.<EMITTER_NAME>.certificate.keyVault.linkedService item à configuração do Apache Spark.

4. Adicione as seguintes propriedades do Spark com os valores apropriados à configuração do Spark, ou selecione Importar na faixa de opções para baixar o arquivo YAML de exemplo, que já contém as propriedades necessárias.

   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>.tenantId: <SP_TENANT_ID>
   spark.synapse.diagnostic.emitter.<EMITTER_NAME>.clientId: <SP_CLIENT_ID>
   spark.synapse.diagnostic.emitter.<EMITTER_NAME>.certificate.keyVault: https://<KEYVAULT_NAME>.vault.azure.net/
   spark.synapse.diagnostic.emitter.<EMITTER_NAME>.certificate.keyVault.certificateName: <SP_CERT_NAME>
   spark.synapse.diagnostic.emitter.<EMITTER_NAME>.certificate.keyVault.linkedService: <AZURE_KEY_VAULT_LINKED_SERVICE>

Para obter uma lista das configurações do Apache Spark, consulte as configurações disponíveis do Apache Spark

Etapa 7. Associe a configuração do Apache Spark a notebooks ou definições de tarefas do Spark, ou defina-a como padrão do espaço de trabalho

Use uma das seguintes abordagens com base em seu escopo:

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

Para aplicar a configuração a notebooks ou à definição de trabalho do Spark:

1. Navegue até o bloco de anotações ou a definição de trabalho do Spark no Azure Synapse Analytics Studio.
2. Selecione ou configure o pool do Apache Spark de destino associado ao notebook ou à definição de trabalho do Spark.
3. Verifique se as configurações necessárias do Spark (por exemplo, configurações de Ingestão de Log) são aplicadas ao pool ou sessão do Apache Spark.
4. Inicie ou execute a sessão do Spark para que a configuração entre em vigor.

Para definir as configurações no workspace ou no nível do pool do Apache Spark:

1. Acesse Gerenciar no Azure Synapse Studio.
2. Vá para pools do Apache Spark e selecione o pool do Apache Spark de destino.
3. Defina as configurações necessárias do Spark (por exemplo, propriedades relacionadas ao diagnóstico ou à ingestão de log).
4. Salve a configuração. As configurações serão aplicadas a todas as novas sessões do Spark criadas neste pool.

Passo 8. Enviar um aplicativo Apache Spark e exibir os logs e as métricas

Veja como:

1. Envie um aplicativo Apache Spark para o pool do Apache Spark configurado na etapa anterior. É possível usar uma das opções abaixo para executar essa ação:

   • Execute um notebook no Synapse Studio.
   • Em Synapse Studio, envie um trabalho em lote do Apache Spark por meio de uma definição de trabalho do Apache Spark.
   • Execute um pipeline que contém a atividade do Apache Spark.

2. Acesse o workspace do Log Analytics indicado, depois veja as métricas e os logs do aplicativo ao iniciar a execução do aplicativo Apache Spark.

Gravar logs personalizados de aplicativos

Você pode usar a biblioteca do Apache Log4j para gravar logs personalizados.

Exemplo para 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 para 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

Veja a seguir um exemplo de como consultar eventos do Apache Spark:

SparkEventTest_CL
| where workspaceName_s == "{SynapseWorkspace}" and Event_s== "EventName"
| order by TimeGenerated desc
| limit 100

Veja um exemplo de como consultar os logs de driver de aplicativo e executores do Apache Spark:

SparkLogTest_CL
| where workspaceName_s == "{SynapseWorkspace}" and Message contains "SampleMessage"
| order by TimeGenerated desc
| limit 100

E aqui está um exemplo de consulta de métricas do Apache Spark:

SparkMetricsTest_CL 
| where workspaceName_s == "{SynapseWorkspace}" and name_s== "{MetricsName}"
| order by TimeGenerated desc
| limit 100

Criar e gerenciar alertas

Os usuários podem executar uma consulta para avaliar as métricas e os logs em uma frequência definida, bem como disparar um alerta com base nos resultados. Para obter mais informações, confira como Criar, ver e gerenciar alertas de logs usando o Azure Monitor.

Workspace do Synapse com proteção de exfiltração de dados habilitada

Depois que o workspace do Synapse for criado com a proteção contra exfiltração de dados habilitada.

Quando quiser habilitar esse recurso, você precisará criar solicitações de conexão do ponto de extremidade privado gerenciado nos Escopos de link privado do Azure Monitor (AMPLS) nos locatários aprovados do Microsoft Entra no workspace.

Você pode seguir as etapas abaixo para criar uma conexão de ponto de extremidade privado gerenciada para escopos de link privado do Azure Monitor (AMPLS):

1. Se não houver um AMPLS existente, você pode seguir a configuração da conexão do Link Privado do Azure Monitor para criar uma conexão.
2. Navegue até seu AMPLS no portal do Azure e, na página Recursos do Azure Monitor, selecione Adicionar para adicionar uma conexão ao seu espaço de trabalho do Azure Log Analytics.
3. Navegue até Synapse Studio > Gerenciar > Pontos de extremidade privados gerenciados, selecione o botão Novo, selecione Escopos de Link Privado do Azure Monitor e continuar.

   

4. Escolha o escopo do Azure Monitor Link Privado que você criou e selecione o botão Create.

   

5. Aguarde alguns minutos para o provisionamento do endpoint privado.
6. Navegue até seu AMPLS no portal do Azure novamente e, na página Conexões de Ponto de Extremidade Privado, selecione a conexão provisionada e Aprovar.

Configurações disponíveis

Conteúdo relacionado

• Caminho da API do Coletor de Dados HTTP herdado para a análise de logs do Azure
• Execute um aplicativo Spark no notebook.
• Coletar logs e métricas de aplicações do Apache Spark com a conta do Armazenamento do Azure.
• Coletar logs e métricas de aplicativos Apache Spark com o Hubs de Eventos do Azure.