Compartilhar via

Ingerir dados do Telegraf no Azure Data Explorer

  • Artigo

Importante

Esse conector pode ser usado na Inteligência em Tempo Real no Microsoft Fabric. Use as instruções incluídas neste artigo com as seguintes exceções:

O Azure Data Explorer dá suporte à ingestão de dados do Telegraf. O Telegraf é um agente leve, de código aberto, com volume de memória mínimo, para coletar, processar e gravar dados de telemetria, incluindo logs, métricas e dados de IoT. O Telegraf dá suporte a centenas de plug-ins de entrada e saída. Ele é amplamente usado pela comunidade de código aberto e conta com seu suporte. O plug-in de saída do Azure Data Explorer funciona como o conector do Telegraf e dá suporte à ingestão de dados de vários tipos de plug-ins de entrada no Azure Data Explorer.

Pré-requisitos

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

Métodos de autenticação permitidos

O plug-in dá suporte aos seguintes métodos de autenticação:

  • Aplicativos do Microsoft Entra com chaves de aplicativo ou certificados.

  • Tokens de usuário do Microsoft Entra

    • Permite que o plug-in se autentique como um usuário. Só recomendamos usar esse método para fins de desenvolvimento.

  • Token da MSI (identidade de serviço gerenciada) do Azure

    • Esse é o método de autenticação preferencial ao executar o Telegraf em um ambiente do Azure com suporte, como as Máquinas Virtuais do Azure.

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

Configurar o método de autenticação

O plug-in verifica se há 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 detectada é usada. Se não for detectada nenhuma configuração válida, o plug-in não será autenticado.

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

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

    • AZURE_TENANT_ID: a ID de locatário do Microsoft Entra usada para autenticação.
    • AZURE_CLIENT_ID: a ID do cliente de um registro de aplicativo no locatário.
    • AZURE_CLIENT_SECRET: o segredo do cliente que foi gerado para o registro do aplicativo.

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

    • AZURE_TENANT_ID: a ID de locatário do Microsoft Entra usada para autenticação.
    • AZURE_CERTIFICATE_PATH: um caminho para o par de certificado e chave privada no formato PEM ou PFX, que pode autenticar o registro de aplicativo.
    • 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 você precisar de uma entrada interativa, use o logon do dispositivo.

    • AZURE_TENANT_ID: a ID de locatário do Microsoft Entra usada para autenticação.
    • AZURE_CLIENT_ID: a ID do cliente de um registro de aplicativo no locatário.
    • AZURE_USERNAME: o nome de usuário, também conhecido como upn, de uma conta de usuário do Microsoft Entra.
    • AZURE_PASSWORD: a senha da conta de usuário do Microsoft Entra. Observe que essa opção não dá suporte a contas com a MFA habilitada.

  • Identidade de Serviço Gerenciada do Azure: delegar o gerenciamento de credenciais à plataforma. Esse método exige que o código seja executado no Azure, por exemplo, na VM. Toda a configuração é processada pelo Azure. Para obter mais informações, consulte Identidade de Serviço Gerenciada do Azure. Esse método só está disponível ao usar o Azure Resource Manager .

Configurar o Telegraf

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

  • No Windows: C:\Arquivos de Programas\Telegraf\telegraf.conf
  • No Linux: etc/telegraf/telegraf.conf

Para habilitar o plug-in de saída do Azure Data Explorer, remova a marca de comentário da 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 com suporte

O plug-in dá suporte à ingestão gerenciada (em fluxo) e enfileirada (em lote). O tipo de ingestão padrão é em fila.

Importante

Para usar a ingestão gerenciada, você deve habilitar a ingestão por fluxo em seu cluster.

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

  ##  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"

Dados ingeridos pela consulta

Veja a seguir exemplos de dados coletados usando os plug-ins de entrada de SQL e do 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.

Plug-in de entrada de SQL

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

name tags timestamp fields
sqlserver_database_io {"database_name":"azure-sql-db2","file_type":"DATA","host":"adx-vm","logical_filename":"tempdev","measurement_db_type":"AzureSQLDB","physical_filename":"tempdb.mdf","replica_updateability":"READ_WRITE","sql_instance":"adx-sql-server"} 2021-09-09T13:51:20Z {"current_size_mb":16,"database_id":2,"file_id":1,"read_bytes":2965504,"read_latency_ms":68,"reads":47,"rg_read_stall_ms":42,"rg_write_stall_ms":0,"space_used_mb":0,"write_bytes":1220608,"write_latency_ms":103,"writes":149}
sqlserver_waitstats {"database_name":"azure-sql-db2","host":"adx-vm","measurement_db_type":"AzureSQLDB","replica_updateability":"READ_WRITE","sql_instance":"adx-sql-server","wait_category":"Worker Thread","wait_type":"THREADPOOL"} 2021-09-09T13:51:20Z {"max_wait_time_ms":15,"resource_wait_ms":4469,"signal_wait_time_ms":0,"wait_time_ms":4469,"waiting_tasks_count":1464}

Como o objeto de métricas coletado é um tipo complexo, as colunas campos e marcas são armazenadas como tipos de dados dinâmicos. Há várias 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)

    Observação

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

  • Use uma política de atualização: transformar 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 do Syslog

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

name tags timestamp fields
syslog {"appname":"azsecmond","facility":"user","host":"adx-linux-vm","hostname":"adx-linux-vm","severity":"info"} 2021-09-20T14:36:44Z {"facility_code":1,"message":" 2021/09/20 14:36:44.890110 Failed to connect to mdsd: dial unix /var/run/mdsd/default_djson.socket: connect: no such file or directory","procid":"2184","severity_code":6,"timestamp":"1632148604890477000","version":1}
syslog {"appname":"CRON","facility":"authpriv","host":"adx-linux-vm","hostname":"adx-linux-vm","severity":"info"} 2021-09-20T14:37:01Z {"facility_code":10,"message":" pam_unix(cron:session): session opened for user root by (uid=0)","procid":"26446","severity_code":6,"timestamp":"1632148621120781000","version":1}

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

  • Usar o operador de extensão: recomendamos o uso dessa abordagem, pois ela é mais rápida e robusta. Mesmo que o esquema seja alterado, isso não interromperá as consultas ou os painéis.

    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

  • Usar o plug-in bag_unpack(): essa abordagem descompacta automaticamente as colunas de tipo dinâmico. A alteração do esquema de origem pode causar problemas durante a expansão dinâmica de colunas.

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