Partilhar via

Ingerir dados do Telegraf para o Azure Data Explorer

  • Artigo

Importante

Este conector pode ser utilizado na Análise em Tempo Real no Microsoft Fabric. Utilize as instruções neste artigo com as seguintes exceções:

O Azure Data Explorer suporta a ingestão de dados do Telegraf. O Telegraf é um agente de impressão do pé de memória open source, leve e mínimo para recolher, processar e escrever dados telemétricos, incluindo registos, métricas e dados de IoT. O Telegraf suporta centenas de plug-ins de entrada e saída. É amplamente utilizado e bem apoiado pela comunidade open source. O plug-in de saída do Azure Data Explorer serve como conector do Telegraf e suporta a ingestão de dados de muitos tipos de plug-ins de entrada no Azure Data Explorer.

Pré-requisitos

  • Uma subscrição do Azure. Crie uma conta gratuita do Azure.
  • Um cluster e uma base de dados do Azure Data Explorer. Criar um cluster e uma base de dados.
  • Telegraf. Alojar o Telegraf numa máquina virtual (VM) ou num contentor. O Telegraf pode ser alojado localmente onde a aplicação ou o serviço que está a ser monitorizado é implementado ou remotamente num contentor/computação de monitorização dedicado.

Métodos de autenticação suportados

O plug-in suporta os seguintes métodos de autenticação:

  • Microsoft Entra aplicações com chaves de aplicação ou certificados.

  • Microsoft Entra tokens de utilizador

    • Permite que o plug-in se autentique como um utilizador. Recomendamos apenas a utilização deste método para fins de desenvolvimento.

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

    • Este é o método de autenticação preferencial se estiver a executar o Telegraf num ambiente do Azure de suporte, como o Azure Máquinas Virtuais.

Independentemente do método que utilizar, tem de ser atribuída a função de Utilizador da Base de Dados no Azure Data Explorer. Esta função permite que o plug-in crie as tabelas necessárias para ingerir dados. Se o plug-in estiver configurado com create_tables=false, o principal designado tem de ter, pelo menos, a função Ingestor de Bases de Dados .

Configurar o método de autenticação

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

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

  • Credenciais de cliente (Microsoft Entra tokens de aplicação): Microsoft Entra O ID e o segredo da aplicação.

    • AZURE_TENANT_ID: o ID de inquilino Microsoft Entra utilizado para autenticação.
    • AZURE_CLIENT_ID: o ID de cliente de um Registo de Aplicação no inquilino.
    • AZURE_CLIENT_SECRET: o segredo do cliente que foi gerado para o Registo de Aplicações.

  • Certificado de cliente (Microsoft Entra tokens de aplicação): Microsoft Entra ID da aplicação e um certificado X.509.

    • AZURE_TENANT_ID: o ID de inquilino Microsoft Entra utilizado 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 de Aplicações.
    • AZURE_CERTIFICATE_PASSWORD: a palavra-passe que foi definida para o certificado.

  • Palavra-passe do proprietário do recurso (Microsoft Entra tokens de utilizador): Microsoft Entra utilizador e palavra-passe. Não recomendamos a utilização deste tipo de concessão. Se precisar de um início de sessão interativo, utilize o início de sessão do dispositivo.

    • AZURE_TENANT_ID: o ID de inquilino Microsoft Entra utilizado para autenticação.
    • AZURE_CLIENT_ID: o ID de cliente de um Registo de Aplicação no inquilino.
    • AZURE_USERNAME: o nome de utilizador, também conhecido como upn, de uma conta de utilizador Microsoft Entra.
    • AZURE_PASSWORD: a palavra-passe do Microsoft Entra conta de utilizador. Tenha em atenção que isto não suporta contas com a MFA ativada.

  • Identidade de Serviço Gerida do Azure: delegar a gestão de credenciais à plataforma. Este método requer que o código seja executado no Azure, por exemplo, VM. Toda a configuração é processada pelo Azure. Para obter mais informações, veja Identidade de Serviço Gerida do Azure. Este método só está disponível ao utilizar o Azure Resource Manager.

Configurar o Telegraf

O Telergraf é um agente orientado por configuração. Para começar, tem de instalar o Telegraf e configurar os plug-ins de entrada e saída necessários. A localização predefinida do ficheiro de configuração é a seguinte:

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

Para ativar o plug-in de saída do Azure Data Explorer, tem de anular o comentário da secção seguinte no ficheiro 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 a ingestão gerida (transmissão em fluxo) e em fila (batching). O tipo de ingestão predefinido está em fila.

Importante

Para utilizar a ingestão gerida, tem de ativar a ingestão de transmissão em fluxo no cluster.

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

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

Seguem-se exemplos de dados recolhidos com 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, existe um exemplo de como utilizar transformações e consultas de dados no Azure Data Explorer.

Plug-in de entrada do SQL

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

name etiquetas carimbo de data/hora 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"} 09-09-09T13:51:20Z {"current_size_mb":16,"database_id":2,"file_id":1,"read_bytes":2965504,"read_latency_ms":68,"reads":47,"2965504,"read_latency_ms":68,"reads":47,"read_latency_ms 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":"Thread de Trabalho","wait_type":"THREADPOOL"} 09-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}

Uma vez que o objeto de métricas recolhido é um tipo complexo, as colunas de campos e etiquetas são armazenadas como tipos de dados dinâmicos. Existem várias formas de consultar estes dados, por exemplo:

  • Consultar atributos JSON diretamente: pode consultar dados JSON em formato não processado sem os analisar.

    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)

    Nota

    Esta abordagem pode afetar o desempenho ao utilizar grandes volumes de dados. Nestes casos, utilize a abordagem da política de atualização.

  • Utilizar uma política de atualização: transforme colunas de tipo de dados dinâmicos com uma política de atualização. Recomendamos esta 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 tabela seguinte mostra os dados de métricas de exemplo recolhidos pelo plug-in de entrada do Syslog:

name etiquetas carimbo de data/hora fields
syslog {"appname":"azsecmond","facility":"user","host":"adx-linux-vm","hostname":"adx-linux-vm","severity":"info"} 2021-09-20T14:36:44Z {"facility_code":1,"mensagem":" 2021/09/20 14:36:44.890110 Falha ao ligar ao mdsd: dial unix /var/run/mdsd/default_djson.socket: ligar: não existe tal ficheiro ou diretório", "procid":"2184","severity_code":6,"carimbo de data/hora":"1632148604890477000","versão":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): sessão aberta para a raiz do utilizador por (uid=0)","procid":"26446","severity_code":6,"timestamp":"1632148621120781000","versão":1}

Existem várias formas de aplanar colunas dinâmicas com o operador de extensão ou o plug-in bag_unpack( ). Pode utilizar qualquer um deles na função de política de atualização Transform_TargetTableName( ).

  • Utilize o operador de extensão: recomendamos que utilize esta abordagem, uma vez que é mais rápida e robusta. Mesmo que o esquema seja alterado, não irá interromper consultas ou dashboards.

    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

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

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