Ingesta de datos de Telegraf en Azure Data Explorer

  • Artículo

Importante

Este conector se puede usar en Análisis en tiempo real en Microsoft Fabric. Use las instrucciones de este artículo con las excepciones siguientes:

Azure Data Explorer admite la ingesta de datos desde Telegraf. Telegraf es un agente con huella de memoria mínima, ligero y de código abierto para recopilar, procesar y escribir datos de telemetría, incluidos registros, métricas y datos de IoT. Telegraf admite cientos de complementos de entrada y salida. Es ampliamente utilizado y cuenta con el soporte técnico de la comunidad de código abierto. El complemento de salida de Azure Data Explorer actúa como conector de Telegraf y admite la ingesta de datos de muchos tipos de complementos de entrada en Azure Data Explorer.

Requisitos previos

  • Suscripción a Azure. Cree una cuenta de Azure gratuita.
  • Un clúster y una base de datos de Azure Data Explorer. Cree un clúster y una base de datos.
  • Telegraf. Hospede Telegraf en una máquina virtual o contenedor. Telegraf se puede hospedar localmente donde se implemente la aplicación o el servicio que se está supervisando, o de forma remota en un contenedor o proceso de supervisión dedicado.

Métodos de autenticación admitidos

El complemento admite los siguientes métodos de autenticación:

  • Microsoft Entra aplicaciones con claves de aplicación o certificados.

  • tokens de usuario de Microsoft Entra

    • Permite que el complemento se autentique como un usuario. Solo se recomienda usar este método con fines de desarrollo.

  • Token de Azure Managed Service Identity (MSI)

    • Este es el método de autenticación preferido si ejecuta Telegraf en un entorno de Azure compatible, como Azure Virtual Machines.

Independientemente del método que use, a la entidad de seguridad designada se le debe asignar el rol Usuario de la base de datos en Azure Data Explorer. Este rol permite al complemento crear las tablas necesarias para la ingesta de datos. Si el complemento está configurado con create_tables=false, la entidad de seguridad designada debe tener al menos el rol Agente de ingesta de base de datos.

Configuración del método de autenticación

El complemento comprueba si hay configuraciones específicas de variables de entorno para determinar qué método de autenticación se va a usar. Las configuraciones se evalúan en el orden especificado y se usa la primera configuración que se detectó. Si no se detecta una configuración válida, el complemento no se autenticará.

Para configurar la autenticación para el complemento, establezca las variables de entorno adecuadas para el método de autenticación elegido:

  • Credenciales de cliente (Microsoft Entra tokens de aplicación): Microsoft Entra id. de aplicación y secreto.

    • AZURE_TENANT_ID: identificador de inquilino de Microsoft Entra usado para la autenticación.
    • AZURE_CLIENT_ID: identificador del cliente de un registro de aplicación del inquilino.
    • AZURE_CLIENT_SECRET: secreto de cliente generado para el registro de la aplicación.

  • Certificado de cliente (Microsoft Entra tokens de aplicación): Microsoft Entra identificador de aplicación y un certificado X.509.

    • AZURE_TENANT_ID: identificador de inquilino de Microsoft Entra usado para la autenticación.
    • AZURE_CERTIFICATE_PATH: ruta al par de certificado y clave privada en formato PEM o PFX, que puede autenticar el registro de aplicación.
    • AZURE_CERTIFICATE_PASSWORD: la contraseña que se estableció para el certificado.

  • Contraseña del propietario del recurso (Microsoft Entra tokens de usuario): Microsoft Entra usuario y contraseña. No recomendamos usar este tipo de concesión. Si necesita un inicio de sesión interactivo, use el inicio de sesión del dispositivo.

    • AZURE_TENANT_ID: identificador de inquilino de Microsoft Entra usado para la autenticación.
    • AZURE_CLIENT_ID: identificador del cliente de un registro de aplicación del inquilino.
    • AZURE_USERNAME: nombre de usuario, también conocido como upn, de una cuenta de usuario de Microsoft Entra.
    • AZURE_PASSWORD: la contraseña de la cuenta de usuario de Microsoft Entra. Tenga en cuenta que no se admiten cuentas con MFA habilitada.

  • Azure Managed Service Identity: delegar la administración de credenciales en la plataforma. Este método requiere que el código se ejecute en Azure, por ejemplo, en una máquina virtual. Azure controla toda la configuración. Para más información, consulte Identidad de servicio administrado de Azure. Este método solo está disponible cuando usa Azure Resource Manager.

Configuración de Telegraf

Telergraf es un agente controlado mediante configuración. Para empezar, debe instalar Telegraf y configurar los complementos de entrada y salida necesarios. La ubicación predeterminada del archivo de configuración es la siguiente:

  • Para Windows: C:\Archivos de programa\Telegraf\telegraf.conf
  • Para Linux: etc/telegraf/telegraf.conf

Para habilitar el complemento de salida de Azure Data Explorer, debe quitar la marca de comentario de la sección siguiente del archivo de configuración generado automáticamente:

[[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 ingesta que se admiten

El complemento admite la ingesta administrada (streaming) y en cola (procesamiento por lotes). El tipo de ingesta predeterminado es en cola.

Importante

Para usar la ingesta administrada, debe habilitar la ingesta mediante streaming en el clúster.

Para configurar el tipo de ingesta del complemento, modifique el archivo de configuración generado automáticamente como se indica a continuación:

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

Datos ingeridos por la consulta

A continuación se muestran ejemplos de datos recopilados mediante los complementos de entrada de SQL y syslog junto con el complemento de salida de Azure Data Explorer. Para cada método de entrada, hay un ejemplo de cómo usar transformaciones de datos y consultas en Azure Data Explorer.

Complemento de entrada de SQL

En la tabla siguiente se muestran los datos de métricas de ejemplo recopilados por el complemento de entrada de SQL:

name etiquetas 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}

Dado que el objeto de métricas recopiladas es de un tipo complejo, los campos y las columnas de etiquetas se almacenan como tipos de datos dinámicos. Hay muchas maneras de consultar estos datos, por ejemplo:

  • Consulta de atributos JSON directamente: puede consultar datos JSON en formato sin procesar sin necesidad de analizarlos.

    Ejemplo 1

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

    Ejemplo 2

    Tablename
| distinct tostring(tags.database_name)

    Nota

    Este enfoque podría afectar al rendimiento cuando se usan grandes volúmenes de datos. En tales casos, use el enfoque de directiva de actualización.

  • Use una directiva de actualización: transforme las columnas de tipos de datos dinámicos mediante una directiva de actualización. Se recomienda este enfoque para consultar grandes volúmenes de datos.

    // 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}]'

Complemento de entrada de Syslog

En la tabla siguiente se muestran los datos de métricas de ejemplo recopilados por el complemento de entrada de Syslog:

name etiquetas 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}

Hay varias maneras de acoplar columnas dinámicas mediante el operador extend o el complemento bag_unpack(). Puede usar cualquiera de ellos en la función Transform_TargetTableName() de la directiva de actualización.

  • Uso del operador extend: se recomienda usar este enfoque, ya que es más rápido y sólido. Incluso si el esquema cambia, no interrumpirá las consultas ni los paneles.

    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

  • Uso del complemento bag_unpack(): este enfoque desempaqueta automáticamente las columnas de tipo dinámico. Cambiar el esquema de origen puede provocar problemas al expandir dinámicamente las columnas.

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