Ingerir dados do Telegraf no Azure Data Explorer

O Azure Data Explorer (ADX) dá suporte à ingestão de dados da Telegraf. Telegraf é um agente de código aberto, leve e com um consumo mínimo de memória. O Telegraf é usado para coletar, processar e gravar dados de telemetria, incluindo logs, métricas e dados de IoT.

Telegraf suporta centenas de plugins de entrada e saída. É amplamente utilizado e a comunidade de código aberto apoia-o.

O plug-in de saída ADX do Azure Data Explorer serve como o conector da Telegraf e dá suporte à ingestão de dados de muitos tipos de plug-ins de entrada no Azure Data Explorer.

Prerequisites

• Uma assinatura do Azure. Crie uma conta do Azure gratuita.
• Um cluster e um banco de dados do Azure Data Explorer. Crie um cluster e um banco de dados.
• Telegraf. Hospede Telegraf em uma máquina virtual (VM) ou contêiner. O Telegraf pode ser hospedado localmente onde o aplicativo ou serviço que está sendo monitorado é implantado ou remotamente em um contêiner/computação de monitoramento dedicado.

Métodos de autenticação suportados

O plugin suporta os seguintes métodos de autenticação:

• Aplicativos Microsoft Entra com chaves de aplicativo ou certificados.

  • Para obter informações sobre como criar e registrar um aplicativo no Microsoft Entra ID, consulte Registrar um aplicativo.
  • Para obter informações sobre entidades de serviço, consulte Objetos de entidade de aplicativo e serviço no Microsoft Entra ID.

• Tokens de usuário do Microsoft Entra

  • Permite que o plugin se autentique como um usuário. Use este método apenas para desenvolvimento.

• Token de Identidade de Serviço Gerenciado do Azure (MSI)

  • O método de autenticação preferencial se você estiver executando Telegraf em um ambiente do Azure com suporte, como Máquinas Virtuais do Azure.

Seja qual for o método usado, a entidade designada deve receber a função Usuário do Banco de Dados no Azure Data Explorer. Esta função permite que o plugin crie as tabelas necessárias para a ingestão de dados. Se o plug-in estiver configurado com create_tables=false, a entidade designada deverá ter pelo menos a função de Ingestor da Base de Dados.

Configurar método de autenticação

O plug-in verifica configurações específicas de variáveis de ambiente para determinar qual método de autenticação usar. As configurações são avaliadas na ordem especificada e a primeira configuração detetada é usada. Se uma configuração válida não for detetada, o plug-in não será autenticado.

Para configurar a autenticação para o plug-in, defina as variáveis de ambiente apropriadas para o método de autenticação escolhido:

• Credenciais do cliente (tokens de aplicativo Microsoft Entra): ID e segredo do aplicativo Microsoft Entra.

  • AZURE_TENANT_ID: O identificador de locatário do Microsoft Entra usado para autenticação.
  • AZURE_CLIENT_ID: O ID do cliente de um Registro de Aplicativo no locatário.
  • AZURE_CLIENT_SECRET: O segredo do cliente que foi gerado para o Registo da Aplicação.

• Certificado de cliente (tokens de aplicativo Microsoft Entra): ID do aplicativo Microsoft Entra e um certificado X.509.

  • AZURE_TENANT_ID: O identificador de locatário do Microsoft Entra usado para autenticação.
  • AZURE_CERTIFICATE_PATH: Um caminho para o certificado e o par de chaves privadas no formato PEM ou PFX, que pode autenticar o Registo da Aplicação.
  • AZURE_CERTIFICATE_PASSWORD: A senha que foi definida para o certificado.

• Senha do proprietário do recurso (tokens de usuário do Microsoft Entra): usuário e senha do Microsoft Entra. Não recomendamos o uso desse tipo de concessão. Se precisar de um início de sessão interativo, utilize o início de sessão através do dispositivo.

  • AZURE_TENANT_ID: O identificador de locatário do Microsoft Entra usado para autenticação.
  • AZURE_CLIENT_ID: O ID do cliente de um Registro de Aplicativo no locatário.
  • AZURE_USERNAME: O nome de utilizador, também conhecido como UPN, de uma conta de utilizador do Microsoft Entra.
  • AZURE_PASSWORD: A senha da conta de usuário do Microsoft Entra. Nota: Esta funcionalidade não suporta contas com autenticação multifator (MFA) ativada.

• Identidade do Serviço Gerenciado do Azure: delegue o gerenciamento de credenciais à plataforma. Execute código no Azure, como em uma VM. O Azure lida com todas as configurações. Para obter mais informações, consulte Identidade do Serviço Gerenciado do Azure. Esse método só está disponível ao usar o Gerenciador de Recursos do Azure.

Configurar o Telegraf

Telergraf é um agente orientado por configuração. Para começar, você deve instalar o Telegraf e configurar os plug-ins de entrada e saída necessários. O local padrão do arquivo de configuração é o seguinte:

• Para Windows: C:\Program Files\Telegraf\telegraf.conf
• Para Linux: etc/telegraf/telegraf.conf

Para habilitar o plug-in de saída do Azure Data Explorer, você deve descomentar a seguinte seção no arquivo de configuração gerado automaticamente:

[[outputs.azure_data_explorer]]
  ## The URI property of the Azure Data Explorer resource on Azure
  ## ex: https://myadxresource.australiasoutheast.kusto.windows.net
  # endpoint_url = ""

  ## The Azure Data Explorer database that the metrics will be ingested into.
  ## The plugin will NOT generate this database automatically, it's expected that this database already exists before ingestion.
  ## ex: "exampledatabase"
  # database = ""

  ## Timeout for Azure Data Explorer operations, default value is 20 seconds
  # timeout = "20s"

  ## Type of metrics grouping used when ingesting to Azure Data Explorer
  ## Default value is "TablePerMetric" which means there will be one table for each metric
  # metrics_grouping_type = "TablePerMetric"

  ## Name of the single table to store all the metrics (Only needed if metrics_grouping_type is "SingleTable").
  # table_name = ""

  ## Creates tables and relevant mapping if set to true(default).
  ## Skips table and mapping creation if set to false, this is useful for running telegraf with the least possible access permissions i.e. table ingestor role.
  # create_tables = true

Tipos de ingestão suportados

O plug-in suporta ingestão gerida (streaming) e em fila (batching). O tipo de ingestão padrão é enfileirado.

Para configurar o tipo de ingestão para o plugin, modifique o arquivo de configuração gerado automaticamente, da seguinte maneira:

  ##  Ingestion method to use.
  ##  Available options are
  ##    - managed  --  streaming ingestion with fallback to batched ingestion or the "queued" method below
  ##    - queued   --  queue up metrics data and process sequentially
  # ingestion_type = "queued"

Consultar dados ingeridos

A seguir estão exemplos de dados coletados usando os plug-ins de entrada SQL e syslog, juntamente com o plug-in de saída do Azure Data Explorer. Para cada método de entrada, há um exemplo de como usar transformações de dados e consultas no Azure Data Explorer.

Plugin de entrada para SQL

A tabela a seguir mostra dados de métricas de exemplo coletados pelo plug-in de entrada SQL:

Como o objeto de métricas coletadas é um tipo complexo, os campos e as colunas de tags são armazenados como tipos de dados dinâmicos. Há muitas maneiras de consultar esses dados, por exemplo:

• Consultar atributos JSON diretamente: você pode consultar dados JSON em formato bruto sem analisá-los.

  Exemplo 1

  Tablename
  | where name == "sqlserver_azure_db_resource_stats" and todouble(fields.avg_cpu_percent) > 7
  

  Exemplo 2

  Tablename
  | distinct tostring(tags.database_name)
  

  Note

  Essa abordagem pode afetar o desempenho com grandes volumes de dados. Nesses casos, use a abordagem de política de atualização.

• Usar uma política de atualização: transforme colunas de tipo de dados dinâmicos usando uma política de atualização. Recomendamos essa abordagem para consultar grandes volumes de dados.

  // Function to transform data
  .create-or-alter function Transform_TargetTableName() {
    SourceTableName
    | mv-apply fields on (extend key = tostring(bag_keys(fields)[0]))
    | project fieldname=key, value=todouble(fields[key]), name, tags, timestamp
  }
  
  // Create destination table with above query's results schema (if it doesn't exist already)
  .set-or-append TargetTableName <| Transform_TargetTableName() | take 0
  
  // Apply update policy on destination table
  .alter table TargetTableName policy update
  @'[{"IsEnabled": true, "Source": "SourceTableName", "Query": "Transform_TargetTableName()", "IsTransactional": true, "PropagateIngestionProperties": false}]'
  

Plug-in de entrada Syslog

A tabela a seguir mostra dados de métricas de exemplo coletados pelo plug-in de entrada Syslog:

Há várias maneiras de achatar colunas dinâmicas usando o operador estendido ou bag_unpack() plugin. Você pode usar qualquer um deles na função Transform_TargetTableName() da política de atualização.

• Use o operador extend: use essa abordagem porque ela é mais rápida e robusta. Mesmo que o esquema mude, isso não compromete consultas ou painéis de controlo.

  Tablename
  
  | extend facility_code=toint(fields.facility_code), message=tostring(fields.message), procid= tolong(fields.procid), severity_code=toint(fields.severity_code),
  SysLogTimestamp=unixtime_nanoseconds_todatetime(tolong(fields.timestamp)), version= todouble(fields.version),
  appname= tostring(tags.appname), facility= tostring(tags.facility),host= tostring(tags.host), hostname=tostring(tags.hostname), severity=tostring(tags.severity)
  | project-away fields, tags
  

• Use o plug-in bag_unpack(): essa abordagem descompacta automaticamente colunas de tipo dinâmico. Alterar o esquema de origem pode causar problemas ao expandir colunas dinamicamente.

  Tablename
  | evaluate bag_unpack(tags, columnsConflict='replace_source')
  | evaluate bag_unpack(fields, columnsConflict='replace_source')