Pozyskiwanie danych z programu Telegraf do usługi Azure Data Explorer

Usługa Azure Data Explorer (ADX) obsługuje pozyskiwanie danych z programu Telegraf. Telegraf to agent wydruku typu open source, lekki i minimalny rozmiar stopy pamięci. Telegraf służy do zbierania, przetwarzania i zapisywania danych telemetrycznych, w tym dzienników, metryk i danych IoT.

Program Telegraf obsługuje setki wtyczek wejściowych i wyjściowych. Jest ona powszechnie używana, a społeczność open source ją wspiera.

Wtyczka wyjściowa usługi Azure Data Explorer ADX służy jako łącznik z programu Telegraf i obsługuje pozyskiwanie danych z wielu typów wtyczek wejściowych do usługi Azure Data Explorer.

Prerequisites

• Subskrypcja platformy Azure. Utwórz bezpłatne konto platformy Azure.
• Baza danych i klaster usługi Azure Data Explorer. Utwórz klaster i bazę danych.
• Telegraf. Hostowanie programu Telegraf na maszynie wirtualnej lub w kontenerze. Program Telegraf może być hostowany lokalnie, gdzie monitorowana aplikacja lub usługa jest wdrażana lub zdalnie w dedykowanym środowisku obliczeniowym/kontenerze monitorowania.

Obsługiwane metody uwierzytelniania

Wtyczka obsługuje następujące metody uwierzytelniania:

• Aplikacje firmy Microsoft Entra z kluczami aplikacji lub certyfikatami.

  • Aby uzyskać informacje na temat tworzenia i rejestrowania aplikacji w usłudze Microsoft Entra ID, zobacz Rejestrowanie aplikacji.
  • Aby uzyskać informacje na temat jednostek usługi, zobacz Application and service principal objects in Microsoft Entra ID (Obiekty aplikacji i jednostki usługi w identyfikatorze Entra firmy Microsoft).

• Tokeny użytkowników firmy Microsoft Entra

  • Umożliwia wtyczkom uwierzytelnianie jak użytkownik. Użyj tej metody tylko do programowania.

• Token tożsamości usługi zarządzanej (MSI) platformy Azure

  • Preferowana metoda uwierzytelniania, jeśli używasz programu Telegraf w środowisku pomocniczym platformy Azure, takim jak Azure Virtual Machines.

Niezależnie od używanej metody wyznaczony podmiot zabezpieczeń musi mieć przypisaną rolę Użytkownika bazy danych w usłudze Azure Data Explorer. Ta rola umożliwia wtyczkom tworzenie tabel wymaganych do pozyskiwania danych. Jeśli wtyczka jest skonfigurowana z create_tables=falseprogramem , wyznaczony podmiot zabezpieczeń musi mieć co najmniej rolę Ingestor bazy danych .

Konfigurowanie metody uwierzytelniania

Wtyczka sprawdza określone konfiguracje zmiennych środowiskowych, aby określić, która metoda uwierzytelniania ma być używana. Konfiguracje są oceniane w określonej kolejności, a pierwsza wykryta konfiguracja jest używana. Jeśli nie zostanie wykryta prawidłowa konfiguracja, nie można uwierzytelnić wtyczki.

Aby skonfigurować uwierzytelnianie dla wtyczki, ustaw odpowiednie zmienne środowiskowe dla wybranej metody uwierzytelniania:

• Poświadczenia klienta (tokeny aplikacji Firmy Microsoft Entra): identyfikator aplikacji Entra firmy Microsoft i wpis tajny.

  • AZURE_TENANT_ID: identyfikator dzierżawy entra firmy Microsoft używany do uwierzytelniania.
  • AZURE_CLIENT_ID: identyfikator klienta rejestracji aplikacji w dzierżawie.
  • AZURE_CLIENT_SECRET: klucz tajny klienta wygenerowany dla rejestracji aplikacji.

• Certyfikat klienta (tokeny aplikacji Firmy Microsoft Entra): identyfikator aplikacji Entra firmy Microsoft i certyfikat X.509.

  • AZURE_TENANT_ID: identyfikator dzierżawy entra firmy Microsoft używany do uwierzytelniania.
  • AZURE_CERTIFICATE_PATH: ścieżka do pary certyfikatu i klucza prywatnego w formacie PEM lub PFX, który może uwierzytelnić rejestrację aplikacji.
  • AZURE_CERTIFICATE_PASSWORD: hasło ustawione dla certyfikatu.

• Hasło właściciela zasobu (tokeny użytkownika entra firmy Microsoft): użytkownik i hasło firmy Microsoft Entra. Nie zalecamy używania tego typu udzielania. Jeśli potrzebujesz logowania interakcyjnego, użyj nazwy logowania urządzenia.

  • AZURE_TENANT_ID: identyfikator dzierżawy entra firmy Microsoft używany do uwierzytelniania.
  • AZURE_CLIENT_ID: identyfikator klienta rejestracji aplikacji w dzierżawie.
  • AZURE_USERNAME: nazwa użytkownika, znana również jako upn, konta użytkownika Microsoft Entra.
  • AZURE_PASSWORD: hasło konta użytkownika Microsoft Entra. Uwaga: ta funkcja nie obsługuje kont z włączonym uwierzytelnianiem wieloskładnikowymi (MFA).

• Tożsamość usługi zarządzanej platformy Azure: delegowanie zarządzania poświadczeniami do platformy. Uruchamianie kodu na platformie Azure, takiego jak na maszynie wirtualnej. Platforma Azure obsługuje całą konfigurację. Aby uzyskać więcej informacji, zobacz Tożsamość usługi zarządzanej platformy Azure. Ta metoda jest dostępna tylko w przypadku korzystania z usługi Azure Resource Manager.

Konfigurowanie programu Telegraf

Telergraf jest agentem opartym na konfiguracji. Aby rozpocząć, należy zainstalować program Telegraf i skonfigurować wymagane wtyczki wejściowe i wyjściowe. Domyślna lokalizacja pliku konfiguracji jest następująca:

• Dla systemu Windows: C:\Program Files\Telegraf\telegraf.conf
• W przypadku systemu Linux: etc/telegraf/telegraf.conf

Aby włączyć wtyczkę danych wyjściowych usługi Azure Data Explorer, należy usunąć komentarz z następującej sekcji w automatycznie wygenerowanych plikach konfiguracji:

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

Obsługiwane typy pozyskiwania

Wtyczka obsługuje zarządzane (przesyłanie strumieniowe) i pozyskiwanie w kolejce (wsadowe). Domyślny typ pozyskiwania jest kolejkowany.

Aby skonfigurować typ pozyskiwania dla wtyczki, zmodyfikuj automatycznie wygenerowany plik konfiguracji w następujący sposób:

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

Wykonywanie zapytań dotyczących pozyskanych danych

Poniżej przedstawiono przykłady danych zebranych przy użyciu wtyczek wejściowych SQL i syslog wraz z wtyczką wyjściową usługi Azure Data Explorer. Dla każdej metody wejściowej istnieje przykład użycia przekształceń danych i zapytań w usłudze Azure Data Explorer.

Wtyczka danych wejściowych SQL

W poniższej tabeli przedstawiono przykładowe dane metryk zebrane przez wtyczkę danych wejściowych SQL:

Ponieważ zebrany obiekt metryk jest typem złożonym, pola i kolumny tagów są przechowywane jako dynamiczne typy danych. Istnieje wiele sposobów wykonywania zapytań dotyczących tych danych, na przykład:

• Bezpośrednie wykonywanie zapytań względem atrybutów JSON: dane JSON można wykonywać w formacie nieprzetworzonym bez analizowania.

  Przykład 1

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

  Przykład 2

  Tablename
  | distinct tostring(tags.database_name)
  

  Note

  Takie podejście może mieć wpływ na wydajność przy dużych ilościach danych. W takich przypadkach należy użyć podejścia polityki aktualizacji.

• Użyj zasad aktualizacji: Przekształcanie kolumn typu danych dynamicznych przy użyciu zasad aktualizacji. Zalecamy takie podejście do wykonywania zapytań dotyczących dużych ilości danych.

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

Wtyczka danych wejściowych dziennika systemowego

W poniższej tabeli przedstawiono przykładowe dane metryk zebrane przez wtyczkę danych wejściowych usługi Syslog:

Istnieje wiele sposobów spłaszczenia kolumn dynamicznych przy użyciu operatora rozszerzonego lub wtyczki bag_unpack(). Można ich użyć w funkcji Transform_TargetTableName() zasad aktualizacji.

• Użyj operatora rozszerzania: użyj tego podejścia, ponieważ jest szybsze i niezawodne. Nawet jeśli schemat ulegnie zmianie, nie psuje to zapytań ani pulpitów nawigacyjnych.

  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
  

• Użyj wtyczki bag_unpack(): to podejście automatycznie rozpakuje kolumny typu dynamicznego. Zmiana schematu źródłowego może powodować problemy podczas dynamicznego rozszerzania kolumn.

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