Recolha logs e métricas com o Azure Log Analytics

Este artigo descreve como usar o destino Azure Log Analytics para diagnósticos Apache Spark no Azure Synapse Analytics utilizando a API de Ingestão de Logs.

A emissão de diagnósticos do Azure Synapse Apache Spark fornece um modelo de configuração unificado para recolher diagnósticos do Spark nos destinos suportados. Para o Azure Log Analytics, a API de Ingestão de Logs é o mecanismo de ingestão recomendado.

Este artigo explica como configurar propriedades dos emissores, encaminhar logs do Apache Spark, registos de eventos e métricas para o Log Analytics, e consultar os dados ingeridos para fins de monitorização e resolução de problemas.

Migrar a partir da API do Data Collector

Se estiver atualmente a utilizar a API do Coletor de Dados HTTP no Azure Synapse Analytics, migre para a API de Ingestão de Registos para ficar em conformidade com a arquitetura de ingestão mais recente do Azure Monitor e com as recomendações mais recentes.

Principais alterações no novo modelo:

• As definições de esquemas são explicitamente definidas através de Regras de Recolha de Dados (DCRs), proporcionando uma validação de esquemas previsível e resultados de consulta mais consistentes em comparação com a abordagem anterior de carga útil livre.
• O fluxo de ingestão é encaminhado através dos Endpoints de Recolha de Dados (DCEs) e mapeamentos DCR, oferecendo um caminho de ingestão mais controlado e fiável do que o envio de dados diretamente para o endpoint da API do Data Collector.
• A autenticação suporta tanto o principal do serviço com autenticação secreta do cliente como a autenticação baseada em certificados.
• O tipo emissor muda de AzureLogAnalytics para AzureLogIngestion.
• A migração normalmente envolve a criação de recursos DCR e DCE, atualização das configurações do pool Azure Synapse Apache Spark (por exemplo, configurações de configuração ou diagnósticos do Spark) e validação de que os dados são ingeridos com sucesso em tabelas personalizadas em Azure Log Analytics.

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

Para diagnósticos Apache Spark em Azure Synapse Analytics, a API de Ingestão de Registos fornece um modelo estruturado de ingestão para autenticação, definição de esquemas, encaminhamento e entrega de dados em Azure Log Analytics.

Componentes principais

Apenas DCRs criados pelo utilizador configurados para a API de Ingestão de Logs podem ser usados para ingestão programática.

Configuração passo a passo

Passo 1. Preparar o espaço de trabalho de Log Analytics

É necessário um espaço de trabalho de Log Analytics para receber diagnósticos do Spark. É a unidade básica de armazenamento e consulta para Azure Monitor Logs.

Se não tiveres um, cria um espaço de trabalho de Log Analytics no portal Azure.

Passo 2. Criar um Endpoint de Recolha de Dados (DCE)

Crie um Endpoint de Recolha de Dados (DCE) no Portal do Azure. O DCE fornece o 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 seu espaço de trabalho de Log Analytics.

Os utilizadores podem opcionalmente criar um ou mais tipos de tabela (logs, events, metrics), dependendo do seu cenário, e cada tipo de tabela tem a sua própria configuração DCR e nome de fluxo correspondentes. Só cria e configura os tipos de tabelas de que realmente precisas.

1. No portal do Azure, vá para Monitor no painel de navegação esquerdo.

2. Em Definições, selecione endpoints de recolha de dados e depois selecione Criar.

   

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

Passo 3. Preparar um esquema JSON de exemplo

Ao criar tabelas de registo personalizadas, deve configurar uma Regra de Recolha de Dados (DCR). Com base nas definições de fluxo de dados especificadas no DCR, o sistema gera automaticamente o esquema de tabela correspondente no seu espaço de trabalho Log Analytics.

As seguintes amostras de esquemas JSON pré-definidas correspondem a um tipo de dado específico. Descarrega o exemplo que se adequa ao teu cenário e carrega-o quando criares a tabela personalizada associada e o DCR.

• Registos de eventos Spark - Exemplo de esquema JSON para tabela de eventos
• Registos de driver e executor Spark - Exemplo de esquema JSON em tabela de logs
• Métricas Spark - Exemplo de esquema JSON de tabela métrica

Passo 4: Criar tabela personalizada (Ingesta Direta)

Crie uma tabela personalizada no seu espaço de trabalho de Log Analytics com a opção Log Ingestion API e carregue o exemplo do esquema JSON para o DCR associado. Este passo é necessário para configurar o destino para o diagnóstico do Spark e garantir que os dados ingeridos cumprem o esquema esperado. A região do espaço de trabalho Log Analytics, DCE e DCR deve ser a mesma para garantir uma ingestão de dados bem-sucedida.

1. No portal Azure, abra o seu espaço de trabalho Log Analytics (por exemplo, loganalyticsworkspacedemo).

2. Selecionar Tabelas>Criar>novo registo personalizado (Ingesta Direta).

   

3. Introduza as definições da tabela:

   • Nome da tabela: Por exemplo, SparkLogTest (o sufixo "_CL" é adicionado automaticamente).
   • Esquema de Tabela: Análise
   • Regra de Recolha de Dados: Crie um novo DCR (por exemplo, SparkLogTestrule).
   • Endpoint de Recolha de Dados: Selecione o DCE no passo Criar um Endpoint de Recolha de Dados (DCE) (por exemplo, DCEdemo).

   

4. Selecione Avançar.

5. Em Esquema e Transformação, carregue o exemplo de esquema JSON. Não precisas de configurar a transformação DCR porque o esquema está totalmente estabilizado do lado do cliente.

Passo 5. Preparar o principal do serviço e recolher o identificador DCR

1. Registe uma aplicação em Microsoft Entra ID.

   

2. Regista o TenantId, ClientId, e ClientSecret (se usares autenticação de secreto do cliente). Usas estes valores na configuração do Spark no Passo 6.

3. Conceda à aplicação o papel de Editor de Métricas de Monitorização no recurso DCR de cada tabela. Para os passos de atribuição de funções, consulte Atribuir funções Azure usando o portal Azure.

   

4. Recupera o nome do stream e o ID do DCR. Pode obter o ID da DCR e o nome do fluxo de dados de cada tabela que criou na vista do recurso Regra de Recolha de Dados (DCR) em JSON no portal do Azure.

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

   No passo seguinte, irá configurar, na configuração do Spark, os valores correspondentes de logStream, eventStream e metricStream, bem como os valores logDcr, eventDcr e metricDcr, com estes nomes de fluxo.

   

Passo 6. Configurar propriedades do Spark

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

Uma configuração do Apache Spark no Azure Synapse Analytics armazena as definições e bibliotecas do Spark que os notebooks e as definições de trabalhos do Spark utilizam em tempo de execução. Para os passos para criar um, veja Gerir configuração do Apache Spark.

• Escolhe a Opção 1 se quiseres uma configuração mais simples usando um cliente secreto.
• Escolha a Opção 2 se a sua organização exigir autenticação baseada em certificados e gestão centralizada de certificados no Azure Key Vault.
• Escolha a Opção 3 se usar autenticação baseada em certificado e quiser recuperar o certificado do Azure Key Vault através de um serviço ligado ao Synapse (workspace MSI acede ao Key Vault).

Em qualquer uma das opções, pode clicar no botão Importar para carregar rapidamente um ficheiro YAML de configuração.

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

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

1. Crie uma configuração Apache Spark.

2. Adicione as seguintes propriedades do Spark com os valores adequados ao artefacto de ambiente, ou selecione Importar no friso para transferir o ficheiro 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. Guardar e publicar as alterações.

Opção 2: Configurar com autenticação do certificado da entidade de serviço

Use esta opção quando a sua organização exigir autenticação baseada em certificados.

Antes de começar, certifique-se de que o seu principal de serviço seja criado com um certificado. Para mais informações, consulte Criar um principal de serviço contendo um certificado usando CLI do Azure.

1. Crie uma configuração Apache Spark.

2. Adicione as seguintes propriedades do Spark com os valores adequados ao artefacto de ambiente, ou selecione Importar no friso para transferir o ficheiro 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 ligado

Para configurar um serviço ligado ao Key Vault no Synapse Studio para armazenar o certificado do principal de serviço, siga estes passos:

1. Siga todos os passos da secção anterior, "Opção 2."

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

   a. Vá a Synapse Studio>Gerir>Serviços ligados, e depois selecione Novo.

   b. Na caixa de pesquisa, procure por Azure Key Vault.

   c. Introduza um nome para o serviço ligado.

   d. Escolha o seu cofre de chaves e selecione Criar.

3. Adiciona 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 no friso para descarregar o ficheiro 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 uma lista de configurações do Apache Spark, veja Configurações Disponíveis do Apache Spark

Passo 7. Associe a configuração do Apache Spark a notebooks ou definições de tarefas do Spark, ou defina-a como predefinição da área de trabalho

Use uma das seguintes abordagens, consoante o seu âmbito:

• Anexe a configuração do Apache Spark a cadernos específicos ou definições de tarefas do Spark quando quiser um lançamento direcionado, testes ou controlo por item.
• Define a configuração do Apache Spark como padrão do workspace quando quiseres que as definições de diagnóstico do Spark sejam aplicadas consistentes em todo o workspace.

Para aplicar a configuração a notebooks ou a uma definição de tarefa do Spark:

1. Navegue até ao seu bloco de notas ou à definição de tarefa 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 tarefa do Spark.
3. Assegure que as configurações necessárias do Spark (por exemplo, definições de Log Ingestion) são aplicadas ao pool ou sessão do Apache Spark.
4. Inicie ou execute a sessão Spark para que a configuração entre em vigor.

Para configurar as definições ao nível do workspace ou do pool Apache Spark:

1. Navegar para Gerir no Azure Synapse Studio.
2. Vá para os pools do Apache Spark e selecione o pool do Apache Spark de destino.
3. Configure as definições necessárias do Spark (por exemplo, diagnósticos ou propriedades relacionadas com a ingestão de logs).
4. Salve a configuração. As definições aplicar-se-ão a todas as novas sessões Spark criadas neste pool.

Passo 8. Envie um aplicativo Apache Spark e visualize os logs e métricas

Saiba como:

1. Submeta uma aplicação Apache Spark para o pool Apache Spark configurado na etapa anterior. Você pode usar qualquer uma das seguintes maneiras de fazer isso:

   • Executa um caderno no Synapse Studio.
   • No Synapse Studio, submeta uma tarefa em lote do Apache Spark através de uma definição de tarefa do Apache Spark.
   • Executa um pipeline que contenha atividade do Apache Spark.

2. Vá para o espaço de trabalho especificado do Log Analytics e visualize as métricas e os logs do aplicativo quando o aplicativo Apache Spark começar a ser executado.

Escrever registos personalizados de aplicações

Você pode usar a biblioteca Apache Log4j para escrever 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 de 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 Kusto

Segue-se um exemplo de consulta a eventos do Apache Spark:

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

Aqui está um exemplo de consulta aos registos do driver e executor da aplicação 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 a 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 consultar para avaliar métricas e logs em uma frequência definida e disparar um alerta com base nos resultados. Para obter mais informações, consulte Criar, exibir e gerenciar alertas de log usando o Azure Monitor.

Espaço de trabalho Synapse com proteção contra exfiltração de dados ativada

Após a criação do espaço de trabalho Synapse com a proteção de exfiltração de dados ativada.

Quando quiser ativar esta funcionalidade, precisa de criar pedidos de ligação a endpoints privados geridos para Azure Monitor private link scopes (AMPLS) nos inquilinos aprovados Microsoft Entra do workspace.

Pode seguir os passos abaixo para criar uma ligação de endpoint privado gerido para os escopos de ligação privada do Azure Monitor (AMPLS):

1. Se não houver um AMPLS existente, pode seguir a configuração da ligação do Azure Monitor Private Link para criar um.
2. Navegue até ao seu AMPLS no portal do Azure, na página Recursos do Azure Monitor, selecione Adicionar para adicionar uma ligação ao seu espaço de trabalho do Azure Log Analytics.
3. Navegue até Synapse Studio > Gerir > Pontos finais privados geridos, selecione Novo, selecione Azure Monitor Private Link Scopes e continuar.

   

4. Escolhe o teu Azure Monitor Private Link Scope que criaste e seleciona o botão Criar.

   

5. Aguarde alguns minutos até que o ponto final privado seja provisionado.
6. Volte a aceder ao seu AMPLS no portal do Azure e, na página Ligações de ponto final privado, selecione a ligação aprovisionada e Aprovar.

Configurações disponíveis

Conteúdo relacionado

• Caminho da API legada de Recolha de Dados HTTP para o Azure Log Analytics
• Executa uma aplicação Spark no caderno.
• Recolha registos e métricas de aplicações Apache Spark com Armazenamento do Azure conta.
• Recolha registos e métricas de aplicações Apache Spark com Hubs de Eventos do Azure.