Migrar da API do Coletor de Dados HTTP para a API de Ingestão de Logs para enviar dados para os 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 logs e no gerenciamento de tabelas do que a API do Coletor de Dados HTTP herdada. Este artigo descreve as diferenças entre a API do coletor de dados e a API de ingestão de logs e fornece orientação e práticas recomendadas para migrar para a nova API de ingestão de logs.
Nota
Como MVP da Microsoft, Morten Waltorp Knudsen contribuiu e forneceu feedback material 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 AzLogDcrIngestPS PowerShell do Morten, disponível publicamente.
Vantagens da API de ingestão de log
A API de ingestão de log fornece as seguintes vantagens em relação à API do coletor de dados:
- Suporta transformações, que permitem modificar os dados antes de serem ingeridos na tabela de destino, incluindo filtragem e manipulação de dados.
- Permite enviar dados para vários destinos.
- Permite gerenciar o esquema da tabela de destino, incluindo nomes de colunas, e se novas colunas devem ser adicionadas à 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 espaço de trabalho do Log Analytics onde você tem pelo menos direitos de colaborador.
- Permissões para criar regras de coleta de dados no espaço de trabalho do Log Analytics.
- Um aplicativo Microsoft Entra para autenticar chamadas de API ou qualquer outro esquema de autenticação do Resource Manager.
Permissões necessárias
| Ação | Permissões necessárias |
|---|---|
| Crie um ponto de extremidade de coleta de dados. | Microsoft.Insights/dataCollectionEndpoints/writepermissões fornecidas pela função interna Colaborador de Monitoramento, por exemplo. |
| Crie ou modifique uma regra de coleta de dados. | Microsoft.Insights/DataCollectionRules/Writepermissões fornecidas pela função interna Colaborador de Monitoramento, por exemplo. |
| Converta uma tabela que usa a API do coletor de dados em regras de coleta de dados e na API de ingestão de log. | Microsoft.OperationalInsights/workspaces/tables/migrate/actionpermissões fornecidas pela função interna Colaborador do Log Analytics, por exemplo. |
| Crie novas tabelas ou modifique esquemas de tabela. | microsoft.operationalinsights/workspaces/tables/writepermissões fornecidas pela função interna Colaborador do Log Analytics, por exemplo. |
| Chame a API de ingestão de log. | Consulte Atribuir permissões a um DCR. |
Criar novos recursos necessários para a API de ingestão de log
A API de ingestão de log requer que você crie dois novos tipos de recursos, que a API do coletor de dados HTTP não exige:
- Pontos de extremidade de coleta de dados, a partir 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 à 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 usando a API do Coletor de Dados, poderá:
Migre a tabela para continuar ingerindo dados para a mesma tabela usando a API de ingestão de log.
Mantenha a tabela e os dados existentes e configure uma nova tabela na qual você ingere dados usando a API de ingestão de log. Em seguida, você pode excluir a tabela antiga quando estiver pronto.
Esta é a opção preferida, 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 existentes da API do Coletor de Dados podem levar a erros.
Gorjeta
Para identificar quais tabelas usam a API do Coletor de Dados, exiba as propriedades da tabela. A propriedade Type de tabelas que usam a API do Coletor de Dados é 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 Azure Monitor Agent antes de converter tabelas MMA. Caso contrário, você interromperá a ingestão de dados em campos personalizados nessas tabelas após a conversão da tabela.
Esta tabela resume as considerações a ter em mente para cada opção:
| Migração de tabela | Implementação lado a lado | |
|---|---|---|
| Nomenclatura de tabelas e colunas | Reutilize o nome da tabela existente. Opções de nomenclatura de colunas: - Use novos nomes de coluna e defina uma transformação para direcionar os dados de entrada para a coluna recém-nomeada. - Continue usando nomes antigos. |
Defina o nome da nova tabela livremente. Precisa ajustar integrações, painéis e alertas antes de mudar 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. |
| Pós-migração | Você pode continuar a ingerir dados usando a API do Coletor de Dados HTTP com colunas existentes, exceto colunas personalizadas. Ingerir dados em novas colunas usando somente a 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 Log, emita esta chamada de 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
Esta chamada é idempotente, portanto, não tem efeito se a tabela já tiver sido convertida.
A chamada de API habilita todos os recursos de logs personalizados baseados em DCR na tabela. A API do Coletor de Dados continuará a ingerir dados em 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 Log, é aplicar uma transformação de espaço de trabalho à tabela.
Importante
- Os nomes das colunas devem começar com uma letra e podem consistir em até 45 caracteres alfanuméricos e sublinhados (
_). _ResourceId,id, ,_ResourceId,_SubscriptionId,TypeTenantId, ,UniqueIdeTitlesão nomes de colunas reservados.- As colunas personalizadas adicionadas a uma tabela do Azure devem ter o sufixo
_CF. - Se você atualizar o esquema de tabela no espaço de trabalho 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 log
A API de ingestão de logs permite enviar até 1 MB de dados compactados ou não compactados por chamada. Se precisar de enviar mais de 1 MB de dados, pode enviar várias chamadas em paralelo. Esta é 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 log, consulte Chamada de API REST de ingestão de log.
Modificar esquemas de tabela e regras de coleta de dados com base em alterações no objeto de dados de origem
Enquanto a API do Coletor de Dados ajusta automaticamente o esquema da tabela de destino quando o esquema do objeto de dados de origem é alterado, a API de Ingestão de Log não. Isso garante que você não colete novos dados em colunas que não pretendia criar.
Quando o esquema de dados de origem é alterado, você pode:
- Modifique os esquemas da tabela de destino e as regras de coleta de dados para alinhá-los com as alterações do esquema de dados de origem.
- Defina 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.
Nota
Não é possível reutilizar um nome de coluna com um tipo de dados diferente do tipo de dados original definido para a coluna.