Klientská knihovna pro příjem dat služby Azure Monitor pro Python – verze 1.0.3

Článek
11/09/2023

Klientská knihovna pro příjem dat služby Azure Monitor slouží k odesílání vlastních protokolů do služby Azure Monitor pomocí rozhraní API pro příjem protokolů.

Tato knihovna umožňuje odesílat data z prakticky libovolného zdroje do podporovaných předdefinovaných tabulek nebo do vlastních tabulek, které vytvoříte v pracovním prostoru služby Log Analytics. Schéma předdefinovaných tabulek můžete dokonce rozšířit o vlastní sloupce.

Zdroje a prostředky:

Začínáme

Požadavky

Python 3.7 nebo novější
Předplatné Azure
Pracovní prostor služby Azure Log Analytics
Koncový bod shromažďování dat
Pravidlo shromažďování dat

Instalace balíčku

Nainstalujte klientskou knihovnu pro příjem dat služby Azure Monitor pro Python pomocí nástroje pip:

pip install azure-monitor-ingestion

Vytvoření klienta

K nahrání protokolů do služby Azure Monitor se vyžaduje ověřený klient. Knihovna obsahuje synchronní i asynchronní formy klientů. K ověření vytvořte instanci přihlašovacích údajů tokenu. Tuto instanci použijte při vytváření objektu LogsIngestionClient. Následující příklady používají DefaultAzureCredential balíček azure-identity .

Synchronní klienti

Podívejte se na následující příklad, který vytvoří synchronní klienty pro nahrávání protokolů:

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)

Asynchronní klienti

Asynchronní formy rozhraní API klienta se nacházejí v .aiooboru názvů s příponou . Příklad:

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)

Konfigurace klientů pro neveřejné cloudy Azure

Ve výchozím nastavení LogsIngestionClient se konfiguruje pro připojení k veřejnému cloudu Azure. Pro připojení k neveřejovým cloudům Azure se vyžaduje určitá další konfigurace. Příslušný obor pro ověřování musí být poskytnut pomocí argumentu klíčového credential_scopes slova. Následující příklad ukazuje, jak nakonfigurovat klienta pro připojení ke službě Azure US Government:

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

Klíčové koncepty

Koncový bod shromažďování dat

Koncové body shromažďování dat (DCE) umožňují jedinečnou konfiguraci nastavení příjmu dat pro Azure Monitor. Tento článek obsahuje přehled koncových bodů shromažďování dat, včetně jejich obsahu a struktury a toho, jak je můžete vytvářet a pracovat s nimi.

Pravidlo shromažďování dat

Pravidla shromažďování dat (DCR) definují data shromážděná službou Azure Monitor a určují, jak a kam se mají tato data odesílat nebo ukládat. Volání rozhraní REST API musí určovat DCR, které se má použít. Jeden DCE může podporovat více dcr, takže můžete zadat různé DCR pro různé zdroje a cílové tabulky.

DCR musí rozumět struktuře vstupních dat a struktuře cílové tabulky. Pokud se neshoduje, může použít transformaci a převést zdrojová data tak, aby odpovídala cílové tabulce. Transformaci můžete použít také k filtrování zdrojových dat a provádění dalších výpočtů nebo převodů.

Další informace najdete v tématu Pravidla shromažďování dat ve službě Azure Monitor. Podrobnosti o struktuře DCR najdete v tomto článku . Informace o tom, jak načíst ID DCR, najdete v tomto kurzu.

Tabulky pracovního prostoru služby Log Analytics

Vlastní protokoly můžou odesílat data do libovolné vlastní tabulky, kterou vytvoříte, a do určitých předdefinovaných tabulek v pracovním prostoru služby Log Analytics. Cílová tabulka musí existovat předtím, než do ní budete moct odesílat data. V současné době jsou podporovány následující předdefinované tabulky:

Načítání protokolů

Protokoly nahrané pomocí této knihovny je možné dotazovat pomocí klientské knihovny dotazů služby Azure Monitor .

Nahrání vlastních protokolů

Tento příklad ukazuje nahrávání protokolů do služby 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}")

Nahrávání s vlastním zpracováním chyb

Pokud chcete nahrát protokoly s vlastním zpracováním chyb, můžete do parametru on_error metody předat funkci zpětného upload volání. Funkce zpětného volání je volána pro každou chybu, ke které dojde během nahrávání, a měla by očekávat jeden argument, který odpovídá objektu LogsUploadError . Tento objekt obsahuje zjištěnou chybu a seznam protokolů, které se nepodařilo nahrát.

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

Poradce při potížích

Podrobnosti o diagnostice různých scénářů selhání najdete v našem průvodci odstraňováním potíží.

Další kroky

Další informace o službě Azure Monitor najdete v dokumentaci ke službě Azure Monitor.

Ukázky

Následující ukázky kódu ukazují běžné scénáře s klientskou knihovnou pro příjem dat služby Azure Monitor.

Ukázky příjmu protokolů

Přispívání

Tento projekt vítá příspěvky a návrhy. Většina příspěvků vyžaduje souhlas s licenční smlouvou s přispěvatelem (CLA), která stanoví, že máte právo udělit nám práva k používání vašeho příspěvku a skutečně tak činíte. Podrobnosti najdete v cla.microsoft.com.

Při odesílání žádosti o přijetí změn robot CLA automaticky určí, jestli je potřeba poskytnout smlouvu CLA, a příslušným způsobem žádost o přijetí změn upraví (např. přidáním jmenovky nebo komentáře). Stačí postupovat podle pokynů robota. Pomocí našeho cla to budete muset provést ve všech úložištích pouze jednou.

Tento projekt přijal pravidla chování pro Microsoft Open Source. Další informace najdete v nejčastějších dotazech k pravidlům chování. V případě jakýchkoli dotazů nebo připomínek kontaktujte opencode@microsoft.com.

Sdílet prostřednictvím