Partager via

Ingérer les données de Telegraf dans Azure Data Explorer

  • Article

Important

Ce connecteur peut être utilisé dans Real-Time Intelligence dans Microsoft Fabric. Utilisez les instructions contenues dans cet article, à l’exception des points suivants :

Azure Data Explorer prend en charge l’ingestion de données de Telegraf. Telegraf est un agent open source, léger et à empreinte mémoire minimale pour la collecte, le traitement et l'écriture de données de télémétrie, y compris les journaux, les métriques et les données IoT. Telegraf prend en charge des centaines de plug-ins d'entrée et de sortie. Il est largement utilisé et accepté par la communauté open source. Le plug-in de sortie d'Azure Data Explorer sert de connecteur depuis Telegraf et prend en charge l'ingestion de données provenant de nombreux types de plug-ins d'entrée dans Azure Data Explorer.

Prérequis

  • Un abonnement Azure. Créez un compte Azure gratuit.
  • Un cluster et une base de données Azure Data Explorer. Créez un cluster et une base de données.
  • Telegraf. Hébergez Telegraf sur une machine virtuelle ou un conteneur. Telegraf peut être hébergé localement, là où l'application ou le service à surveiller est déployé, ou à distance sur un ordinateur/conteneur de surveillance dédié.

Méthodes d’authentification prises en charge

Le plug-in prend en charge les méthodes d’authentification suivantes :

  • Applications Microsoft Entra avec des clés d’application ou des certificats.

  • Jetons utilisateur Microsoft Entra

    • Permet au plug-in de s'authentifier comme un utilisateur. Nous recommandons d'utiliser cette méthode uniquement à des fins de développement.

  • Jeton Azure Managed Service Identity (MSI)

    • Il s'agit de la méthode d'authentification privilégiée si vous exécutez Telegraf dans un environnement Azure, par exemple des machines virtuelles Azure.

Quelle que soit la méthode utilisée, le principal désigné doit se voir attribuer le rôle Utilisateur de base de données dans Azure Data Explorer. Ce rôle permet au plug-in de créer les tables nécessaires à l'ingestion des données. Si le plug-in est configuré avec create_tables=false, le principal désigné doit au moins avoir le rôle Ingéreur de base de données.

Configurer la méthode d'authentification

Le plug-in recherche les configurations spécifiques de variables d'environnement pour déterminer la méthode d'authentification à utiliser. Les configurations sont évaluées dans l'ordre spécifié, et la première configuration détectée est utilisée. Si aucune configuration valide n'est détectée, le plug-in échouera à s'authentifier.

Pour configurer l'authentification pour le plug-in, définissez les variables d'environnement appropriées pour la méthode d'authentification choisie :

  • Informations d’identification client (jetons d’application Microsoft Entra) : ID et secret de l’application Microsoft Entra.

    • AZURE_TENANT_ID : ID de locataire Microsoft Entra utilisé pour l’authentification.
    • AZURE_CLIENT_ID : ID client d'une inscription d'application dans le locataire.
    • AZURE_CLIENT_SECRET : le secret client qui a été généré pour l’inscription de l’application.

  • Certificat client (jetons d’application Microsoft Entra) : ID de l’application Microsoft Entra et un certificat X.509.

    • AZURE_TENANT_ID : ID de locataire Microsoft Entra utilisé pour l’authentification.
    • AZURE_CERTIFICATE_PATH : chemin d’accès au certificat et à la paire de clés privées au format PEM ou PFX, qui peut authentifier l’inscription de l’application.
    • AZURE_CERTIFICATE_PASSWORD: mot de passe défini pour le certificat.

  • Mot de passe du propriétaire de la ressource (jetons utilisateur Microsoft Entra) : utilisateur et mot de passe Microsoft Entra. Nous vous déconseillons d’utiliser ce type d'autorisation. Si vous avez besoin d'une connexion interactive, utilisez la connexion d’appareil.

    • AZURE_TENANT_ID : ID de locataire Microsoft Entra utilisé pour l’authentification.
    • AZURE_CLIENT_ID : ID client d'une inscription d'application dans le locataire.
    • AZURE_USERNAME : Nom d’utilisateur, également appelé UPN, d’un compte d’utilisateur Microsoft Entra.
    • AZURE_PASSWORD : Mot de passe du compte d’utilisateur Microsoft Entra. Notez que les comptes avec MFA activé ne sont pas pris en charge.

  • Identité de service managé Azure : déléguer la gestion des informations d’identification à la plateforme. Cette méthode exige que le code soit exécuté dans Azure, par exemple sur une machine virtuelle. Toute la configuration est gérée par Azure. Pour plus d’informations, consultez Identité managée de service Azure. Cette méthode est uniquement disponible dans le cadre de l’utilisation d’Azure Resource Manager.

Configurer Telegraf

Telegraf est un agent piloté par une configuration. Pour commencer, vous devez installer Telegraf et configurer les plug-ins d'entrée et de sortie nécessaires. L'emplacement par défaut du fichier de configuration est le suivant :

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

Pour activer le plug-in de sortie Azure Data Explorer, vous devez supprimer les marques de commentaire de la section suivante dans le fichier de configuration généré automatiquement :

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

Types d’ingestion pris en charge

Le plug-in prend en charge l’ingestion managée (streaming) et mise en file d’attente (traitement par lots). Le type d’ingestion par défaut est mise en file d’attente.

Important

Pour utiliser l’ingestion managée, vous devez activer l’ingestion de streaming sur votre cluster.

Pour configurer le type d’ingestion du plug-in, modifiez le fichier de configuration généré automatiquement comme suit :

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

Interroger les données ingérées

Voici des exemples de données collectées à l'aide des plug-ins d'entrée SQL et syslog et du plug-in de sortie Azure Data Explorer. Pour chaque méthode d’entrée, Azure Data Explorer inclut un exemple d'utilisation des transformations de données et des requêtes.

Plug-in d’entrée SQL

Le tableau suivant présente des exemples de données métriques collectées par le plug-in d'entrée 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}

Comme l'objet de métrique collecté est un type complexe, les champs et les colonnes de balises sont stockés comme des types de données dynamiques. Il existe de nombreuses façons d'interroger ces données, par exemple :

  • Interroger directement des attributs JSON : vous pouvez interroger les données JSON au format brut sans les analyser.

    Exemple 1 :

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

    Exemple 2

    Tablename
| distinct tostring(tags.database_name)

    Remarque

    Cette approche pourrait avoir un impact sur les performances lors de l'utilisation de grands volumes de données. Dans ce cas, utilisez la stratégie de mise à jour.

  • Utiliser une stratégie de mise à jour : transformez les colonnes de type de données dynamiques à l'aide d'une stratégie de mise à jour. Nous recommandons cette approche pour l'interrogation de grands volumes de données.

    // 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 d'entrée syslog

Le tableau suivant présente des exemples de données métriques collectées par le plug-in d'entrée 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}

Il existe plusieurs façons de réduire les colonnes dynamiques en utilisant l'opérateur extend ou le plug-in bag_unpack(). Vous pouvez utiliser l'un ou l'autre dans la fonction Transform_TargetTableName() de la stratégie de mise à jour.

  • Utiliser l’opérateur extend : nous recommandons cette approche car elle est plus rapide et robuste. Même si le schéma change, cela n'affectera pas les requêtes ou les tableaux de bord.

    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

  • Utiliser le plug-in bag_unpack() : cette approche permet de développer automatiquement les colonnes de type dynamique. La modification du schéma source peut causer des problèmes lors de l'expansion dynamique des colonnes.

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