Tutorial: como ingerir eventos dos Hubs de Eventos do Azure nos Logs do Azure Monitor (Visualização Pública)

Artigo
10/03/2024

Os Hubs de Eventos do Azure são uma plataforma de streaming de Big Data que coleta eventos de várias fontes a serem ingeridos pelo Azure e serviços externos. Este artigo explica como ingerir dados diretamente de um hub de eventos em um workspace do Log Analytics.

Neste tutorial, você aprenderá como:

Criar uma tabela de destino para dados do hub de eventos no workspace do Log Analytics
Criar um ponto de extremidade de coleta de dados
Criar uma regra de coleta de dados
Conceder permissões de regra de coleta de dados ao hub de eventos
Associar a regra de coleta de dados ao hub de eventos

Pré-requisitos

Para enviar eventos dos Hubs de Eventos do Azure para os Logs do Azure Monitor, você precisa destes recursos:

Workspace do Log Analytics em que você tem pelo menos direitos de colaborador.
Seu workspace do Log Analytics precisa ser vinculado a um cluster dedicado ou ter uma camada de compromisso.
Namespace dos Hubs de Eventos que permite o acesso à rede pública. Se o acesso à rede pública estiver desabilitado, verifique se "Permitir que serviços confiáveis da Microsoft ignorem esse firewall" está definido como "Sim".
Hub de eventos com eventos. Você pode enviar eventos para o hub de eventos seguindo as etapas em Enviar e receber eventos em tutoriais dos Hubs de Eventos do Azure ou definindo as configurações de diagnóstico dos recursos do Azure.

Regiões com suporte

Atualmente, o Azure Monitor dá suporte à ingestão de Hubs de Eventos nestas regiões:

Américas	Europa	Oriente Médio	África	Pacífico Asiático
Brazil South	França Central	Norte dos EAU	Norte da África do Sul	Austrália Central
Sudeste do Brasil	Norte da Europa			Leste da Austrália
Canadá Central	Leste da Noruega			Sudeste da Austrália
Leste do Canadá	Norte da Suíça			Índia Central
Leste dos EUA	Oeste da Suíça			Leste da Ásia
Leste dos EUA 2	Sul do Reino Unido			Leste do Japão
Centro-Sul dos Estados Unidos	Oeste do Reino Unido			Jio Oeste da Índia
Oeste dos EUA	Europa Ocidental			Coreia Central
Oeste dos EUA 3				Sudeste Asiático

Você precisa criar sua DCRA (Associação da regras de coleta de dados) na mesma região que o hub de eventos. O workspace do Log Analytics pode estar em qualquer região, mas a DCR (Regra de coleta de dados) e o DCE (Ponto de extremidade de coleta de dados) devem estar na mesma região que o workspace do Log Analytics.

Para latência mínima, é recomendável colocar todos os recursos na mesma região.

Coletar as informações necessárias

Você precisa da ID da assinatura, do nome do grupo de recursos, do nome do workspace, da ID do recurso do workspace e da ID do recurso da instância do hub de eventos nas etapas subsequentes:

Navegue até o seu workspace no menu Workspaces do Log Analytics, selecione Propriedades e copie sua ID de assinatura, grupo de recursos e nome do workspace. Você precisará desses detalhes para criar recursos neste tutorial.
Selecione JSON para abrir a tela de JSON do recurso e copie a ID de Recurso do workspace. Você precisará da ID do recurso do workspace para criar uma regra de coleta de dados.
Navegue até a instância do hub de eventos, selecione JSON para abrir a tela JSON do recurso e copie a ID de Recurso da instância do hub de eventos. Você precisará da ID do recurso da instância do hub de eventos para associar a regra de coleta de dados ao hub de eventos.

Criar uma tabela de destino no workspace do Log Analytics

Antes de ingerir dados, você precisa configurar uma tabela de destino. Você pode ingerir dados em tabelas personalizadas e tabelas do Azure com suporte.

Para criar uma tabela personalizada na qual ingerir eventos, no portal do Azure:

Selecione o botão Cloud Shell e verifique se o ambiente está definido como PowerShell.

Execute este comando do PowerShell para criar a tabela, fornecendo o nome da tabela (<table_name>) no JSON (igualmente com o sufixo_CL no caso de tabela personalizada) e definindo os valores <subscription_id>, <resource_group_name>, <workspace_name> e <table_name> no comandoInvoke-AzRestMethod -Path:

$tableParams = @'
{
    "properties": {
        "schema": {
            "name": "<table_name>",
            "columns": [
                {
                    "name": "TimeGenerated",
                    "type": "datetime",
                    "description": "The time at which the data was ingested."
                },
                {
                    "name": "RawData",
                    "type": "string",
                    "description": "Body of the event."
                },
                {
                    "name": "Properties",
                    "type": "dynamic",
                    "description": "Additional message properties."
                }
            ]
        }
    }
}
'@

Invoke-AzRestMethod -Path "/subscriptions/<subscription_id>/resourcegroups/<resource_group_name>/providers/microsoft.operationalinsights/workspaces/<workspace_name>/tables/<table_name>?api-version=2021-12-01-preview" -Method PUT -payload $tableParams

Importante

Os nomes de coluna devem começar com uma letra e podem consistir de até 45 caracteres alfanuméricos e sublinhados (_).
_ResourceId, id, _ResourceId, _SubscriptionId, TenantId, Type, UniqueId e Title são nomes de coluna reservados.
Os nomes de coluna diferenciam maiúsculas de minúsculas. Use maiúsculas e minúsculas corretamente na regra de coleta de dados.

Criar um ponto de extremidade de coleta de dados

Para coletar dados com uma regra de coleta de dados, você precisa de um ponto de extremidade de coleta de dados:

Crie ponto de extremidade da coleta de dados.

Importante

Criar o ponto de extremidade de coleta de dados na mesma região do workspace do Log Analytics.
Na tela Visão geral do ponto de extremidade de coleta de dados, selecione Exibição JSON.
Copie a ID de Recurso da regra de coleta de dados. Você precisará destas informações na próxima etapa.

Criar uma regra de coleta de dados

O Azure Monitor usa regras de coleta de dados para definir quais dados coletar, como transformar esses dados e para onde enviar os dados.

Para criar uma regra de coleta de dados no portal do Azure:

Na caixa de pesquisa do portal, digite modelo e selecione Implantar um modelo personalizado.
Selecione Criar seu próprio modelo no editor.

Cole o modelo do Resource Manager abaixo no editor e, em seguida, selecione Salvar.

Observe os seguintes detalhes na regra de coleta de dados abaixo:

identity – Define qual tipo de identidade gerenciada usar. Em nosso exemplo, usamos a identidade atribuída pelo sistema. Você também pode configurar a identidade gerenciada atribuída pelo usuário.
dataCollectionEndpointId – ID de recurso do ponto de extremidade da coleta de dados.
streamDeclarations – Define quais dados ingerir do hub de eventos (dados de entrada). A declaração de fluxo não pode ser modificada.
- TimeGenerated – A hora em que os dados foram ingeridos do hub de eventos para os Logs do Azure Monitor.
- RawData – Corpo do evento. Para obter mais informações, confira Ler eventos.
- Properties – Propriedades de usuário do evento. Para obter mais informações, confira Ler eventos.
datasources – Especifica o grupo de consumidores do hub de eventos e o fluxo para o qual você ingere os dados.
destinations – Especifica todos os destinos para os quais os dados serão enviados. Você pode ingerir dados em um ou mais workspaces do Log Analytics.
dataFlows – corresponde o fluxo ao workspace de destino e especifica a consulta de transformação e a tabela de destino. Em nosso exemplo, ingerimos dados para a tabela personalizada que criamos anteriormente. Você também pode ingerir em uma tabela do Azure com suporte.
transformKql – especifica uma transformação a ser aplicada aos dados de entrada (declaração de fluxo) antes de serem enviados para o workspace. Em nosso exemplo, definimos transformKql como source, que não modifica os dados da origem de forma alguma, porque estamos mapeando dados de entrada para uma tabela personalizada que criamos especificamente com o esquema correspondente. Se você estiver ingerindo dados em uma tabela com um esquema diferente ou para filtrar dados antes da ingestão, defina uma transformação de coleta de dados.

{
    "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "dataCollectionRuleName": {
            "type": "string",
            "metadata": {
                "description": "Specifies the name of the data collection Rule to create."
            }
        },
        "workspaceResourceId": {
            "type": "string",
            "metadata": {
                "description": "Specifies the Azure resource ID of the Log Analytics workspace to use."
            }
        },
        "endpointResourceId": {
            "type": "string",
            "metadata": {
                "description": "Specifies the Azure resource ID of the data collection endpoint to use."
            }
        },
        "tableName": {
            "type": "string",
            "metadata": {
                "description": "Specifies the name of the table in the workspace."
            }
        },
        "consumerGroup": {
            "type": "string",
            "metadata": {
                "description": "Specifies the consumer group of event hub."
            },
            "defaultValue": "$Default"
        }
    },
    "resources": [
        {
            "type": "Microsoft.Insights/dataCollectionRules",
            "name": "[parameters('dataCollectionRuleName')]",
            "location": "[resourceGroup().location]", 
            "apiVersion": "2022-06-01",
            "identity": {
                             "type": "systemAssigned"
              },
            "properties": {
                "dataCollectionEndpointId": "[parameters('endpointResourceId')]",
                "streamDeclarations": {
                    "Custom-MyEventHubStream": {
                        "columns": [
                {
                    "name": "TimeGenerated",
                    "type": "datetime"
                },
                {
                    "name": "RawData",
                    "type": "string"
                },
                {
                    "name": "Properties",
                    "type": "dynamic"
                }
            ]
                    }
                },
                "dataSources": {
                    "dataImports": {
                         "eventHub": {
                                    "consumerGroup": "[parameters('consumerGroup')]",
                                    "stream": "Custom-MyEventHubStream",
                                    "name": "myEventHubDataSource1"
                                                          }
                                           }
               },
                "destinations": {
                    "logAnalytics": [
                        {
                            "workspaceResourceId": "[parameters('workspaceResourceId')]",
                            "name": "MyDestination"
                        }
                    ]
                },
                "dataFlows": [
                    {
                        "streams": [
                            "Custom-MyEventHubStream"
                        ],
                        "destinations": [
                            "MyDestination"
                        ],
                        "transformKql": "source",
                        "outputStream": "[concat('Custom-', parameters('tableName'))]"
                    }
                ]
            }
        }
    ]
}

Na tela Implantação personalizada, especifique uma Assinatura e um Grupo de recursos para armazenar a regra de coleta de dados e, em seguida, forneça os valores para os parâmetros definidos no modelo, incluindo:
- Região – região para a regra de coleta de dados. Preenchido automaticamente com base no grupo de recursos selecionado.
- Nome da regra de coleta de dados – dê um nome à regra.
- ID do recurso do workspace – confira Coletar as informações necessárias.
- ID do recurso do ponto de extremidade – gerada quando você cria o ponto de extremidade de coleta de dados.
- Nome da tabela – o nome da tabela de destino. Em nosso exemplo e sempre que você usa uma tabela personalizada, o nome da tabela deve terminar com o sufixo _CL. Se você estiver ingerindo dados em uma tabela do Azure, insira o nome da tabela – por exemplo, Syslog – sem o sufixo.
- Grupo de Consumidores – por padrão, o grupo de consumidores é definido como $Default. Se necessário, altere o valor para um grupo de consumidores de hub de eventos diferente.
Clique em Examinar + criar e, em seguida, Criar ao examinar os detalhes.
Quando a implantação for concluída, expanda a caixa Detalhes da implantação e selecione a regra de coleta de dados para exibir os detalhes. Selecione Exibição JSON.
Copie a ID de Recurso da regra de coleta de dados. Você usará estas informações na próxima etapa.

Configurar identidade gerenciada atribuída pelo usuário (opcional)

Para configurar sua regra de coleta de dados para dar suporte à identidade atribuída pelo usuário, no exemplo acima, substitua:

    "identity": {
                        "type": "systemAssigned"
        },

por:

    "identity": {
            "type": "userAssigned",
            "userAssignedIdentities": {
                "<identity_resource_Id>": {
                }
            }
        },

Para localizar o valor <identity_resource_Id>, navegue até o recurso de identidade gerenciada atribuída pelo usuário no portal do Azure, selecione JSON para abrir a tela JSON do recurso e copie a ID de recurso da identidade gerenciada.

Ingerir dados de log em uma tabela do Azure (opcional)

Para ingerir dados em uma tabela do Azure com suporte:

Na regra de coleta de dados, altere outputStream:

De: "outputStream": "[concat('Custom-', parameters('tableName'))]"

Para: "outputStream": "outputStream": "[concat(Microsoft-', parameters('tableName'))]"
Em transformKql, defina uma transformação que envia os dados ingeridos para as colunas de destino na tabela do Azure de destino.

Conceder a permissão do hub de eventos à regra de coleta de dados

Com a identidade gerenciada, você pode conceder, a qualquer hub de eventos ou namespace dos Hubs de Eventos, permissão para enviar eventos para a regra de coleta de dados e o ponto de extremidade de coleta de dados que você criou. Quando você concede as permissões para o namespace dos Hubs de Eventos, todos os hubs de eventos dentro do namespace herdam as permissões.

No hub de eventos ou no namespace dos Hubs de Eventos no portal do Azure, selecione Controle de Acesso (IAM)>Adicionar atribuição de função.
Selecione Receptor de dados dos Hubs de Eventos do Azure e selecione Avançar.
Selecione Identidade gerenciada para Atribuir acesso a e clique em Selecionar membros. Selecione Regra de coleta de dados, pesquise sua regra de coleta de dados pelo nome e clique em Selecionar.
Selecione Revisar + atribuir e verifique os detalhes antes de salvar sua atribuição de função.

Associar a regra de coleta de dados ao hub de eventos

A etapa final é associar a regra de coleta de dados ao hub de eventos do qual você deseja coletar eventos.

Você pode associar uma única regra de coleta de dados a vários hubs de eventos que compartilham o mesmo grupo de consumidores e ingerem dados para o mesmo fluxo. Como alternativa, você pode associar uma regra de coleta de dados exclusiva a cada hub de eventos.

Importante

Você deve associar pelo menos uma regra de coleta de dados ao hub de eventos para ingerir dados de um hub de eventos. Ao excluir todas as associações de regra de coleta de dados relacionadas ao hub de eventos, você interromperá a ingestão de dados do hub de eventos.

Para criar uma associação de regra de coleta de dados no portal do Azure:

Na caixa de pesquisa do portal do Azure, digite modelo e selecione Implantar um modelo personalizado.
Selecione Criar seu próprio modelo no editor.

Cole o modelo do Resource Manager abaixo no editor e, em seguida, selecione Salvar.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "eventHubResourceID": {
      "type": "string",
      "metadata": {
        "description": "Specifies the Azure resource ID of the event hub to use."
      }
    },
    "associationName": {
      "type": "string",
      "metadata": {
        "description": "The name of the association."
      }
    },
    "dataCollectionRuleID": {
      "type": "string",
      "metadata": {
        "description": "The resource ID of the data collection rule."
      }
    }
  },
  "resources": [
    {
      "type": "Microsoft.Insights/dataCollectionRuleAssociations",
      "apiVersion": "2021-09-01-preview",
      "scope": "[parameters('eventHubResourceId')]",
      "name": "[parameters('associationName')]",
      "properties": {
        "description": "Association of data collection rule. Deleting this association will break the data collection for this event hub.",
        "dataCollectionRuleId": "[parameters('dataCollectionRuleId')]"
      }
    }
  ]
}

Na tela Implantação personalizada, especifique uma Assinatura e um Grupo de recursos para armazenar a associação da regra de coleta de dados e, em seguida, forneça os valores para os parâmetros definidos no modelo, incluindo:
- Região – populado automaticamente com base no grupo de recursos selecionado.
- ID do recurso da instância do hub de eventos – confira Coletar informações necessárias.
- Nome da associação – dê um nome à associação.
- ID da regra de coleta de dados – gerada quando você cria a regra de coleta de dados.
Clique em Examinar + criar e, em seguida, Criar ao examinar os detalhes.

Verifique se há eventos ingeridos na tabela de destino

Os Logs do Azure Monitor ingerem todos os eventos que existem no hub de eventos no momento da criação do DCRA, desde que o período de retenção não tenha expirado e todos os novos eventos.

Para verificar se há eventos ingeridos na sua tabela de destino:

Navigate até o seu workspace e selecione Logs.
Escreva uma consulta simples no editor de consultas e selecione Executar:
```
<table_name>
```
Você deve ver eventos do hub de eventos.

Limpar os recursos

Neste tutorial, você criou os seguintes recursos:

Tabela personalizada
Ponto de extremidade da coleta de dados
Regra de coleta de dados
Associação da regra de coleta de dados

Avalie se você ainda precisa desses recursos. Exclua os recursos de que você não precisa individualmente ou exclua todos esses recursos de uma só vez excluindo o grupo de recursos. Os recursos que você deixa em execução podem lhe custar dinheiro.

Para interromper a ingestão de dados do hub de eventos, exclua todas as associações de regra de coleta de dados relacionadas ao hub de eventos ou exclua as próprias regras de coleta de dados. Essas ações também redefinem o ponto de verificação do hub de eventos.

Limitações e problemas conhecidos

Se você transferir uma assinatura entre diretórios do Microsoft Entra, precisará seguir as etapas descritas em Problemas conhecidos com identidades gerenciadas para recursos do Azure para continuar ingerindo dados.
Você pode ingerir mensagens de até 64 KB dos Hubs de Eventos para os Logs do Azure Monitor.

Próximas etapas

Saiba mais sobre para:

Compartilhar via