Migrar da API do Coletor de Dados HTTP para a API de Ingestão de Logs para enviar dados aos Logs do Azure Monitor
A API de Ingestão de Logs do Azure Monitor fornece mais poder de processamento e maior flexibilidade na ingestão de log e no gerenciamento de tabelas do que a API herdada do Coletor de Dados HTTP. Este artigo descreve as diferenças entre a API do Coletor de Dados e a API de Ingestão de Logs e fornece diretrizes e práticas recomendadas para migrar para a nova API de Ingestão de Logs.
Observação
Como MVP da Microsoft, Morten Waltorp Knudsen contribuiu e forneceu comentários materiais para este artigo. Para obter um exemplo de como você pode automatizar a instalação e o uso contínuo da API de Ingestão de Logs, consulte o módulo do PowerShell AzLogDcrIngestPS, que Morten disponibilizou ao público.
Vantagens da API de Ingestão de Logs
A API de Ingestão de Logs fornece as seguintes vantagens sobre a API do Coletor de Dados:
- É compatível com transformações, que permitem modificar os dados antes que eles sejam ingeridos na tabela de destino, incluindo filtragem e manipulação de dados.
- Permite que você envie dados para vários destinos.
- Permite que você gerencie o esquema de tabela de destino, incluindo nomes de coluna, e se deseja adicionar novas colunas à tabela de destino quando o esquema de dados de origem for alterado.
Pré-requisitos
O procedimento de migração descrito neste artigo pressupõe que você tenha:
- Um workspace do Log Analytics em que você tenha, no mínimo, direitos de colaborador.
- Permissões para criar regras de coleta de dados no workspace do Log Analytics.
- Um aplicativo Microsoft Entra para autenticar chamadas de API ou qualquer outro esquema de autenticação do Gerenciador de Recursos.
Permissões necessárias
| Ação | Permissões necessárias |
|---|---|
| Crie ponto de extremidade da coleta de dados. | As permissões Microsoft.Insights/dataCollectionEndpoints/write, conforme fornecidas pela função interna do Colaborador de Monitoramento, por exemplo. |
| Criar ou modificar uma regra de coleta de dados. | As permissões Microsoft.Insights/DataCollectionRules/Write, conforme fornecidas pela função interna do Colaborador de Monitoramento, por exemplo. |
| Converta uma tabela que usa a API do Coletor de Dados em regras de coleta de dados e a API de Ingestão de Logs. | As permissões Microsoft.OperationalInsights/workspaces/tables/migrate/action, conforme fornecidas pela função interna do Colaborador do Log Analytics, por exemplo. |
| Criar tabelas ou modifique esquemas de tabela. | As permissões microsoft.operationalinsights/workspaces/tables/write, conforme fornecidas pela função interna do Colaborador do Log Analytics, por exemplo. |
| Chamar a API de Ingestão de Logs. | Confira Atribuir permissões a uma DCR. |
Criar novos recursos necessários para a API de ingestão de logs
A API de Ingestão de Logs exige que você crie dois novos tipos de recursos, o que a API do Coletor de Dados HTTP não exige:
- Pontos de extremidade de coleta de dados, dos quais os dados coletados são ingeridos no pipeline para processamento.
- Regras de coleta de dados, que definem transformações de dados e a tabela de destino para a qual os dados são ingeridos.
Migrar tabelas personalizadas existentes ou criar novas tabelas
Se você tiver uma tabela personalizada existente para a qual atualmente envia dados por meio da API do Coletor de Dados, poderá:
Migrar a tabela para continuar ingerindo dados na mesma tabela por meio da API de Ingestão de Logs.
Manter a tabela e os dados existentes e configurar uma nova tabela na qual você ingerir dados por meio da API de Ingestão de Logs. Em seguida, você pode excluir a tabela antiga quando estiver pronto.
Essa é a opção preferencial, especialmente se você precisar fazer alterações na tabela existente. Alterações em tipos de dados existentes e várias alterações de esquema em tabelas personalizadas da API do Coletor de Dados existentes podem levar a erros.
Dica
Para identificar quais tabelas usam a API do Coletor de Dados, veja as propriedades da tabela. A propriedade Type das tabelas que usam a API do Data Collector é definida como Tabela personalizada (clássica). Observe que as tabelas que ingerem dados usando o agente herdado do Log Analytics (MMA) também têm a propriedade Type definida como Tabela personalizada (clássica). Certifique-se de migrar do agente do Log Analytics para o Agente do Azure Monitor antes de converter as tabelas MMA. Caso contrário, você deixará de ingerir dados em campos personalizados nessas tabelas após a conversão da tabela.
Esta tabela resume as considerações a serem lembradas para cada opção:
| Migração da Tabela | Implementação lado a lado | |
|---|---|---|
| Nomes de coluna e tabela | Reutilizar o nome da tabela existente. Opções de nomenclatura de coluna: - Use novos nomes de coluna e defina uma transformação para direcionar dados de entrada para a coluna recém-nomeada. - Continue usando nomes antigos. |
Defina o nome da nova tabela livremente. É necessário ajustar integrações, painéis e alertas antes de alternar para a nova tabela. |
| Procedimento de migração | Migração de tabela única. Não é possível reverter uma tabela migrada. | A migração pode ser feita gradualmente, por tabela. |
| Após a migração | Você pode continuar a ingerir dados por meio da API do Coletor de Dados HTTP com colunas existentes, exceto colunas personalizadas. Ingerir dados em novas colunas apenas por meio da API de Ingestão de Logs. |
Os dados na tabela antiga estão disponíveis até o final do período de retenção. Quando você configura uma nova tabela pela primeira vez ou faz alterações de esquema, pode levar de 10 a 15 minutos para que as alterações de dados comecem a aparecer na tabela de destino. |
Para converter uma tabela que usa a API do Coletor de Dados em regras de coleta de dados e a API de Ingestão de Logs, emita essa chamada à API na tabela:
POST https://management.azure.com/subscriptions/{subscriptionId}/resourcegroups/{resourceGroupName}/providers/Microsoft.OperationalInsights/workspaces/{workspaceName}/tables/{tableName}/migrate?api-version=2021-12-01-preview
Essa chamada é idempotente, portanto, não haverá efeito se a tabela já tiver sido migrada.
A chamada à API habilita todos os recursos de logs personalizados baseados em DCR na tabela. A API do coletor de dados continuará a ingerir dados para as colunas existentes, mas não criará novas colunas. Os campos personalizados definidos anteriormente não continuarão a ser preenchidos. Outra maneira de migrar uma tabela existente para usar regras de coleta de dados, mas não necessariamente a API de Ingestão de Logs é aplicar uma transformação de workspace à tabela.
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,UniqueIdeTitlesão nomes de coluna reservados.- As colunas personalizadas que você adiciona a uma tabela do Azure devem ter o sufixo
_CF. - Se você atualizar o esquema de tabela no workspace do Log Analytics, também deverá atualizar a definição de fluxo de entrada na regra de coleta de dados para ingerir dados em colunas novas ou modificadas.
Chamar a API de Ingestão de Logs
A API de Ingestão de Logs permite enviar até 1 MB de dados compactados ou descompactados por chamada. Se você precisar enviar mais de 1 MB de dados, poderá enviar várias chamadas em paralelo. Essa é uma alteração da API do Coletor de Dados, que permite enviar até 32 MB de dados por chamada.
Para obter informações sobre como chamar a API de Ingestão de Logs, consulte Chamada à API REST de Ingestão de Logs.
Modificar esquemas de tabela e regras de coleta de dados com base em alterações no objeto de dados de origem
Embora a API do Coletor de Dados ajuste automaticamente o esquema da tabela de destino quando o esquema do objeto de dados de origem é alterado, a API de Ingestão de Logs não o faz. Isso garante que você não colete novos dados em colunas que não pretendia criar.
Quando o esquema de dados de origem for alterado, você poderá:
- Modificar os esquemas de tabela de destino e asregras de coleta de dados para se alinharem às alterações de esquema de dados de origem.
- Definir uma transformação na regra de coleta de dados para enviar os novos dados para colunas existentes na tabela de destino.
- Deixe a tabela de destino e a regra de coleta de dados inalteradas. Nesse caso, você não ingerirá os novos dados.
Observação
Não é possível reutilizar um nome de coluna com um tipo de dados diferente do tipo de dados original definido para a coluna.