Biblioteka klienta pozyskiwania usługi Azure Monitor dla języka Python — wersja 1.0.3

  • Artykuł

Biblioteka klienta pozyskiwania usługi Azure Monitor służy do wysyłania dzienników niestandardowych do usługi Azure Monitor przy użyciu interfejsu API pozyskiwania dzienników.

Ta biblioteka umożliwia wysyłanie danych z praktycznie dowolnego źródła do obsługiwanych wbudowanych tabel lub tabel niestandardowych tworzonych w obszarze roboczym usługi Log Analytics. Można nawet rozszerzyć schemat wbudowanych tabel za pomocą kolumn niestandardowych.

Zasoby:

Wprowadzenie

Wymagania wstępne

Instalowanie pakietu

Zainstaluj bibliotekę klienta pozyskiwania usługi Azure Monitor dla języka Python przy użyciu narzędzia pip:

pip install azure-monitor-ingestion

Tworzenie klienta

Uwierzytelniony klient jest wymagany do przekazania dzienników do usługi Azure Monitor. Biblioteka zawiera zarówno synchroniczne, jak i asynchroniczne formy klientów. Aby się uwierzytelnić, utwórz wystąpienie poświadczeń tokenu. Użyj tego wystąpienia podczas tworzenia elementu LogsIngestionClient. W poniższych przykładach użyto DefaultAzureCredential pakietu azure-identity .

Klienci synchronicznie

Rozważmy następujący przykład, który tworzy synchronicznych klientów do przekazywania dzienników:

import os
from azure.identity import DefaultAzureCredential
from azure.monitor.ingestion import LogsIngestionClient

endpoint = os.environ['DATA_COLLECTION_ENDPOINT']
credential = DefaultAzureCredential()
logs_client = LogsIngestionClient(endpoint, credential)

Klienci asynchroniczny

Asynchroniczne formularze interfejsów API klienta znajdują się w .aio-sufiksowanej przestrzeni nazw. Na przykład:

import os
from azure.identity.aio import DefaultAzureCredential
from azure.monitor.ingestion.aio import LogsIngestionClient

endpoint = os.environ['DATA_COLLECTION_ENDPOINT']
credential = DefaultAzureCredential()
logs_client = LogsIngestionClient(endpoint, credential)

Konfigurowanie klientów dla chmur platformy Azure niepublizowanych

Domyślnie LogsIngestionClient skonfigurowano połączenie z publiczną chmurą platformy Azure. Aby nawiązać połączenie z chmurami platformy Azure niepublizowanych, wymagana jest dodatkowa konfiguracja. Odpowiedni zakres uwierzytelniania należy podać przy użyciu argumentu słowa kluczowego credential_scopes . W poniższym przykładzie pokazano, jak skonfigurować klienta w celu nawiązania połączenia z usługą Azure US Government:

logs_client = LogsIngestionClient(endpoint, credential_scopes=["https://monitor.azure.us//.default"])

Kluczowe pojęcia

Punkt końcowy zbierania danych

Punkty końcowe zbierania danych (DCE) umożliwiają unikatowe konfigurowanie ustawień pozyskiwania dla usługi Azure Monitor. Ten artykuł zawiera omówienie punktów końcowych zbierania danych, w tym ich zawartości i struktury oraz sposobu ich tworzenia i pracy z nimi.

Reguła zbierania danych

Reguły zbierania danych (DCR) definiują dane zbierane przez usługę Azure Monitor i określają, jak i gdzie mają być wysyłane lub przechowywane te dane. Wywołanie interfejsu API REST musi określać kontroler domeny do użycia. Pojedynczy kontroler domeny może obsługiwać wiele kontrolerów DCR, dzięki czemu można określić różne kontrolery domeny dla różnych źródeł i tabel docelowych.

Kontroler domeny musi zrozumieć strukturę danych wejściowych i strukturę tabeli docelowej. Jeśli te dwa nie są zgodne, może użyć przekształcenia, aby przekonwertować dane źródłowe w celu dopasowania do tabeli docelowej. Możesz również użyć przekształcenia do filtrowania danych źródłowych i wykonywania innych obliczeń lub konwersji.

Aby uzyskać więcej informacji, zobacz Reguły zbierania danych w usłudze Azure Monitor i zobacz ten artykuł , aby uzyskać szczegółowe informacje na temat struktury dcR. Aby uzyskać informacje na temat pobierania identyfikatora DCR, zobacz ten samouczek.

Tabele obszarów roboczych usługi Log Analytics

Dzienniki niestandardowe mogą wysyłać dane do dowolnej utworzonej tabeli niestandardowej i do niektórych wbudowanych tabel w obszarze roboczym usługi Log Analytics. Tabela docelowa musi istnieć przed wysłaniem do niej danych. Obecnie obsługiwane są następujące wbudowane tabele:

Pobieranie dzienników

Dzienniki, które zostały przekazane przy użyciu tej biblioteki, można wykonywać zapytania przy użyciu biblioteki klienta zapytań usługi Azure Monitor .

Przykłady

Przekazywanie dzienników niestandardowych

W tym przykładzie przedstawiono przekazywanie dzienników do usługi Azure Monitor.

import os

from azure.core.exceptions import HttpResponseError
from azure.identity import DefaultAzureCredential
from azure.monitor.ingestion import LogsIngestionClient

endpoint = os.environ['DATA_COLLECTION_ENDPOINT']
credential = DefaultAzureCredential()

client = LogsIngestionClient(endpoint=endpoint, credential=credential, logging_enable=True)

rule_id = os.environ['LOGS_DCR_RULE_ID']
body = [
      {
        "Time": "2021-12-08T23:51:14.1104269Z",
        "Computer": "Computer1",
        "AdditionalContext": "context-2"
      },
      {
        "Time": "2021-12-08T23:51:14.1104269Z",
        "Computer": "Computer2",
        "AdditionalContext": "context"
      }
    ]

try:
    client.upload(rule_id=rule_id, stream_name=os.environ['LOGS_DCR_STREAM_NAME'], logs=body)
except HttpResponseError as e:
    print(f"Upload failed: {e}")

Przekazywanie przy użyciu niestandardowej obsługi błędów

Aby przekazać dzienniki z niestandardową obsługą błędów, można przekazać funkcję wywołania zwrotnego do on_error parametru upload metody . Funkcja wywołania zwrotnego jest wywoływana dla każdego błędu występującego podczas przekazywania i powinna oczekiwać jednego argumentu odpowiadającego LogsUploadError obiektowi. Ten obiekt zawiera napotkany błąd i listę dzienników, które nie udało się przekazać.

# Example 1: Collect all logs that failed to upload.
failed_logs = []
def on_error(error):
    print("Log chunk failed to upload with error: ", error.error)
    failed_logs.extend(error.failed_logs)

# Example 2: Ignore all errors.
def on_error_pass(error):
    pass

client.upload(rule_id=rule_id, stream_name=os.environ['LOGS_DCR_STREAM_NAME'], logs=body, on_error=on_error)

Rozwiązywanie problemów

Aby uzyskać szczegółowe informacje na temat diagnozowania różnych scenariuszy awarii, zobacz nasz przewodnik rozwiązywania problemów.

Następne kroki

Aby dowiedzieć się więcej na temat usługi Azure Monitor, zobacz dokumentację usługi Azure Monitor.

Przykłady

Poniższe przykłady kodu pokazują typowe scenariusze z biblioteką klienta pozyskiwania usługi Azure Monitor.

Przykłady pozyskiwania dzienników

Współtworzenie

W tym projekcie zachęcamy do współtworzenia i zgłaszania sugestii. Współtworzenie w większości przypadków wymaga zgody na umowę licencyjną dotyczącą współautorów (CLA, Contributor License Agreement), zgodnie z którą współautor ma prawo udzielić i faktycznie udziela nam praw do używania wytworzonej przez siebie zawartości. Aby uzyskać szczegółowe informacje, odwiedź stronę cla.microsoft.com.

Po przesłaniu żądania ściągnięcia robot CLA automatycznie określi, czy musisz przekazać umowę CLA, i doda odpowiednie informacje do tego żądania (na przykład etykietę czy komentarz). Po prostu postępuj zgodnie z instrukcjami robota. Musisz to zrobić tylko raz we wszystkich repozytoriach przy użyciu naszego cla.

W tym projekcie przyjęto Kodeks postępowania oprogramowania Open Source firmy Microsoft. Aby uzyskać więcej informacji, zobacz artykuł Code of Conduct FAQ (Często zadawane pytania dotyczące kodeksu postępowania). Jeśli będziesz mieć jeszcze jakieś pytania lub komentarze, wyślij wiadomość e-mail na adres opencode@microsoft.com.