Gegevens van Telegraf opnemen in Azure Data Explorer

Azure Data Explorer (ADX) ondersteunt gegevensopname van Telegraf. Telegraf is een open source, lichtgewicht en minimale geheugenvoetafdrukagent. Telegraf wordt gebruikt voor het verzamelen, verwerken en schrijven van telemetriegegevens, waaronder logboeken, metrische gegevens en IoT-gegevens.

Telegraf ondersteunt honderden invoegtoepassingen voor invoer en uitvoer. Het wordt veel gebruikt en de opensource-community ondersteunt het.

De Azure Data Explorer ADX-uitvoerinvoegtoepassing fungeert als de connector van Telegraf en biedt ondersteuning voor het opnemen van gegevens uit vele typen invoerinvoegtoepassingen in Azure Data Explorer.

Prerequisites

• Een Azure-abonnement. Maak een gratis Azure-account.
• Een Azure Data Explorer-cluster en -database. Een cluster en database maken.
• Telegraf. Host Telegraf in een virtuele machine (VM) of container. Telegraf kan lokaal worden gehost waar de app of service die wordt gemonitord is geïmplementeerd, of extern op een dedicated monitoring computer/container.

Ondersteunde verificatiemethoden

De invoegtoepassing ondersteunt de volgende verificatiemethoden:

• Microsoft Entra-toepassingen met app-sleutels of -certificaten.

  • Zie Een toepassing registreren voor meer informatie over het maken en registreren van een app in Microsoft Entra ID.
  • Voor informatie over service-principals, zie Toepassings- en service-principalobjecten in Microsoft Entra ID.

• Microsoft Entra-gebruikerstokens

  • Hiermee kan de invoegtoepassing worden geverifieerd met gebruikersidentiteit. Gebruik deze methode alleen voor ontwikkeling.

• Msi-token (Azure Managed Service Identity)

  • De voorkeursmethode voor verificatie als u Telegraf uitvoert in een ondersteunende Azure-omgeving, zoals Azure Virtual Machines.

Welke methode u ook gebruikt, de aangewezen principal moet de rol Databasegebruiker worden toegewezen in Azure Data Explorer. Met deze rol kan de invoegtoepassing de tabellen maken die vereist zijn voor het opnemen van gegevens. Als de invoegtoepassing is geconfigureerd met create_tables=false, moet de aangewezen principal ten minste de rol Database Ingestor hebben.

Verificatiemethode configureren

De invoegtoepassing controleert op specifieke configuraties van omgevingsvariabelen om te bepalen welke verificatiemethode moet worden gebruikt. De configuraties worden beoordeeld in de opgegeven volgorde en de eerste configuratie die is gedetecteerd, wordt gebruikt. Als er geen geldige configuratie wordt gedetecteerd, kan de invoegtoepassing niet worden geverifieerd.

Als u verificatie voor de invoegtoepassing wilt configureren, stelt u de juiste omgevingsvariabelen in voor de gekozen verificatiemethode:

• Clientreferenties (Microsoft Entra-toepassingstokens): Microsoft Entra-toepassings-id en geheim.

  • AZURE_TENANT_ID: de Tenant-id van Microsoft Entra die wordt gebruikt voor verificatie.
  • AZURE_CLIENT_ID: De Client-ID van een appregistratie in de tenant.
  • AZURE_CLIENT_SECRET: het clientgeheim dat is gegenereerd voor de app-registratie.

• Clientcertificaat (Microsoft Entra-toepassingstokens): Microsoft Entra-toepassings-id en een X.509-certificaat.

  • AZURE_TENANT_ID: de Tenant-id van Microsoft Entra die wordt gebruikt voor verificatie.
  • AZURE_CERTIFICATE_PATH: Een pad naar certificaat- en persoonlijke sleutelpaar in PEM- of PFX-indeling, waarmee de app-registratie kan worden geverifieerd.
  • AZURE_CERTIFICATE_PASSWORD: het wachtwoord dat is ingesteld voor het certificaat.

• Wachtwoord voor resource-eigenaar (Microsoft Entra-gebruikerstokens): Microsoft Entra-gebruiker en -wachtwoord. We raden u niet aan dit toekenningstype te gebruiken. Als u een interactieve aanmelding nodig hebt, gebruikt u apparaataanmelding.

  • AZURE_TENANT_ID: de Tenant-id van Microsoft Entra die wordt gebruikt voor verificatie.
  • AZURE_CLIENT_ID: De Client-ID van een appregistratie in de tenant.
  • AZURE_USERNAME: De gebruikersnaam, ook wel upn genoemd, van een Microsoft Entra-gebruikersaccount.
  • AZURE_PASSWORD: het wachtwoord van het Microsoft Entra-gebruikersaccount. Opmerking: deze functie biedt geen ondersteuning voor accounts waarvoor meervoudige verificatie (MFA) is ingeschakeld.

• Azure Managed Service Identity: referentiebeheer delegeren aan het platform. Voer code uit in Azure, zoals op een VIRTUELE machine. Azure verwerkt alle configuraties. Zie Azure Managed Service Identity voor meer informatie. Deze methode is alleen beschikbaar wanneer u Azure Resource Manager gebruikt.

Telegraf configureren

Telergraf is een configuratiegestuurde agent. Om aan de slag te gaan, moet u Telegraf installeren en de vereiste invoegtoepassingen voor invoer en uitvoer configureren. De standaardlocatie van het configuratiebestand is als volgt:

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

Als u de Azure Data Explorer-uitvoerinvoegtoepassing wilt inschakelen, moet u de opmerkingen in de volgende sectie in het automatisch gegenereerde configuratiebestand ongedaan maken:

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

Ondersteunde opnametypen

De invoegtoepassing ondersteunt beheerde (streaming) en gewachte (batchverwerking) opname. Het standaardopnametype wordt in de wachtrij geplaatst.

Om het opnametype voor de plugin te configureren, wijzigt u het automatisch gegenereerde configuratiebestand als volgt:

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

Opgenomen gegevens opvragen

Hieronder volgen voorbeelden van gegevens die worden verzameld met behulp van de SQL- en Syslog-invoerinvoegtoepassingen, samen met de Azure Data Explorer-uitvoerinvoegtoepassing. Voor elke invoermethode ziet u een voorbeeld van het gebruik van gegevenstransformaties en query's in Azure Data Explorer.

SQL-invoegtoepassing voor invoer

In de volgende tabel ziet u voorbeeldgegevens voor metrische gegevens die zijn verzameld door de SQL-invoerinvoegtoepassing:

Omdat het verzamelde object voor metrische gegevens een complex type is, worden de velden en tagskolommen opgeslagen als dynamische gegevenstypen. Er zijn veel manieren om query's uit te voeren op deze gegevens, bijvoorbeeld:

• Rechtstreeks query's uitvoeren op JSON-kenmerken: U kunt query's uitvoeren op JSON-gegevens in onbewerkte indeling zonder deze te parseren.

  Voorbeeld 1

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

  Voorbeeld 2

  Tablename
  | distinct tostring(tags.database_name)
  

  Note

  Deze aanpak kan van invloed zijn op de prestaties met grote hoeveelheden gegevens. In dergelijke gevallen gebruikt u de benadering van het updatebeleid.

• Gebruik een updatebeleid: dynamische gegevenstypekolommen transformeren met behulp van een updatebeleid. We raden deze methode aan voor het uitvoeren van query's op grote hoeveelheden gegevens.

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

Syslog-invoegtoepassing

In de volgende tabel ziet u voorbeeldgegevens voor metrische gegevens die zijn verzameld door de Syslog-invoerinvoegtoepassing:

Er zijn meerdere manieren om dynamische kolommen af te vlakken met behulp van de uitgebreide operator of bag_unpack() plugin. U kunt beide gebruiken in de functie updatebeleid Transform_TargetTableName().

• Gebruik de operator "extend": gebruik deze methode omdat deze sneller en robuuster is. Zelfs als het schema wordt gewijzigd, worden query's of dashboards niet aangetast.

  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
  

• Gebruik de invoegtoepassing bag_unpack(): met deze methode worden kolommen van dynamisch type automatisch uitgepakt. Het wijzigen van het bronschema kan problemen veroorzaken bij het dynamisch uitbreiden van kolommen.

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