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

  • Artigo

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, todos na mesma região:

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

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:

  1. 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.

    Screenshot showing Log Analytics workspace overview screen with subscription ID, resource group name, and workspace name highlighted.

  2. 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.

    Screenshot showing the Resource JSON screen with the workspace resource ID highlighted.

  3. 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.

    Screenshot showing the Resource JSON screen with the event hub resource ID highlighted.

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:

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

    Screenshot showing how to open Cloud Shell.

  2. 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:

  1. 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.

  2. Na tela Visão geral do ponto de extremidade de coleta de dados, selecione Exibição JSON.

    Screenshot that shows the data collection endpoint Overview screen.

  3. Copie a ID de Recurso da regra de coleta de dados. Você usará estas informações na próxima etapa.

    Screenshot that shows the data collection endpoint JSON view.

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:

  1. Na caixa de pesquisa do portal, digite modelo e selecione Implantar um modelo personalizado.

    Screenshot to deploy custom template.

  2. Selecione Criar seu próprio modelo no editor.

    Screenshot to build template in the editor.

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

    Screenshot to edit Resource Manager template.

    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'))]"
                    }
                ]
            }
        }
    ]
}

  4. 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.

    Screenshot showing the Custom Template Deployment screen with the deployment values for the data collection rule set up in this tutorial.

  5. Clique em Examinar + criar e, em seguida, Criar ao examinar os detalhes.

  6. 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.

    Screenshot that shows the Data Collection Rule Overview screen.

  7. Copie a ID de Recurso da regra de coleta de dados. Você usará estas informações na próxima etapa.

    Screenshot that shows the data collection rule JSON view.

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.

Screenshot showing Resource JSON screen with the managed identity resource ID highlighted.

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

Para ingerir dados em uma tabela do Azure com suporte:

  1. Na regra de coleta de dados, altere outputStream:

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

    Para: "outputStream": "outputStream": "[concat(Microsoft-', parameters('tableName'))]"

  2. 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.

  1. 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.

    Screenshot that shows the Access control screen for the data collection rule.

  2. Selecione Receptor de dados dos Hubs de Eventos do Azure e selecione Avançar.

    Screenshot that shows the Add Role Assignment screen for the event hub with the Azure Event Hubs Data Receiver role highlighted.

  3. 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.

    Screenshot that shows how to assign access to managed identity.

  4. Selecione Revisar + atribuir e verifique os detalhes antes de salvar sua atribuição de função.

    Screenshot that shows the Review and Assign tab of the Add Role Assignment screen.

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:

  1. Na caixa de pesquisa do portal do Azure, digite modelo e selecione Implantar um modelo personalizado.

  2. Selecione Criar seu próprio modelo no editor.

  3. 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')]"
      }
    }
  ]
}

  4. 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:

    Screenshot showing the Custom Template Deployment screen with the deployment values for the data collection rule association set up in this tutorial.

  5. Clique em Examinar + criar e, em seguida, Criar ao examinar os detalhes.

Verifique se há eventos ingeridos na tabela de destino

Agora que você associou a regra de coleta de dados ao hub de eventos, os Logs do Azure Monitor ingerirão todos os eventos existentes cujo período de retenção não expirou e todos os novos eventos.

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

  1. Navigate até o seu workspace e selecione Logs.

  2. Escreva uma consulta simples no editor de consultas e selecione Executar:

    <table_name>

    Você deve ver eventos do hub de eventos.

Screenshot showing the results of a simple query on a custom table. The results consist of events ingested from an event hub.

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

Próximas etapas

Saiba mais sobre para: