Biblioteka klienta dystrybucji opentelemetrii usługi Azure Monitor dla języka Python — wersja 1.1.1
Dystrybucja usługi Azure Monitor dla języka Python opentelemetry udostępnia wiele składników możliwych do zainstalowania dla rozwiązania do monitorowania usługi Azure Monitor opentelemetry. Umożliwia instrumentację aplikacji języka Python w celu przechwytywania i zgłaszania danych telemetrycznych do usługi Azure Monitor za pośrednictwem eksporterów usługi Azure Monitor.
Ta dystrybucja automatycznie instaluje następujące biblioteki:
- Eksporterzy OpenTelemetry usługi Azure Monitor
- Podzestaw instrumentacji OpenTelemetry, które są oficjalnie obsługiwane zgodnie z poniższymi opisami .
Oficjalnie obsługiwane instrumentacje
Instrumentacje OpenTelemetry umożliwiają automatyczne zbieranie żądań wysyłanych z bazowych instrumentowanych bibliotek. Poniżej znajduje się lista instrumentacji OpenTelemetry, które są dołączone do dystrybucji usługi Azure Monitor. Te instrumentacje są domyślnie włączone. Zobacz sekcję Użycie poniżej, aby dowiedzieć się, jak zrezygnować z tych instrumentacji.
Oprzyrządowanie | Nazwa obsługiwanej biblioteki | Obsługiwane wersje |
---|---|---|
Azure Core Tracing OpenTelemetry | azure_sdk |
|
Instrumentacja Django OpenTelemetry | Django | Link |
Instrumentacja FastApi OpenTelemetry | fastapi | Link |
Instrumentacja platformy Flask OpenTelemetry | Kolby | Link |
Instrumentacja OpenTelemetry Psycopg2 | psycopg2 | Link |
Instrumentacja żądań OpenTelemetry | żądania | Link |
Instrumentacja OpenTelemetry UrlLib | urllib | Wszystko |
Instrumentacja OpenTelemetry UrlLib3 | urllib3 | Link |
Jeśli chcesz dodać obsługę innej instrumentacji OpenTelemetry, prześlij żądanie funkcji. W międzyczasie można ręcznie użyć instrumentacji OpenTelemetry za pośrednictwem własnych interfejsów API (tj. instrument()
) w kodzie. Zobacz to , aby zapoznać się z przykładem.
Kluczowe pojęcia
Ten pakiet zawiera serię składników OpenTelemetry i Azure Monitor, aby umożliwić zbieranie i wysyłanie danych telemetrycznych do usługi Azure Monitor. W przypadku instrumentacji RĘCZNEj użyj configure_azure_monitor
funkcji . Instrumentacja automatyczna nie jest jeszcze obsługiwana.
Eksporterzy OpenTelemetry usługi Azure Monitor są głównymi składnikami w tym celu. Będzie można używać eksporterów i ich interfejsów API bezpośrednio za pośrednictwem tego pakietu. Przejdź do dokumentacji eksportera, aby dowiedzieć się, jak działają składniki OpenTelemetry i Azure Monitor w włączaniu zbierania i eksportowania danych telemetrycznych.
Obecnie wszystkie instrumentacje dostępne w rozwiązaniu OpenTelemetry są w stanie beta, co oznacza, że nie są stabilne i mogą mieć zmiany powodujące niezgodność w przyszłości. Wysiłki są podejmowane w dążeniu do bardziej stabilnego stanu.
Wprowadzenie
Wymagania wstępne
Aby użyć tego pakietu, musisz mieć następujące elementy:
- Subskrypcja platformy Azure — można utworzyć bezpłatne konto
- Azure Monitor — jak używać usługi Application Insights
- Zestaw SDK opentelemetry — zestaw Opentelemetry SDK dla języka Python
- Python 3.7 lub nowszy — instalowanie języka Python
Instalowanie pakietu
Zainstaluj dystrybucję opentelemetrii usługi Azure Monitor za pomocą narzędzia pip:
pip install azure-monitor-opentelemetry
Użycie
Możesz użyć configure_azure_monitor
polecenia , aby skonfigurować instrumentację dla aplikacji w usłudze Azure Monitor. configure_azure_monitor
obsługuje następujące argumenty opcjonalne. Wszystkie parametry przekazywania mają pierwszeństwo nad wszystkimi powiązanymi zmiennymi środowiskowymi.
Parametr | Opis | Zmienna środowiskowa |
---|---|---|
connection_string |
Parametry połączenia zasobu usługi Application Insights. Parametry połączenia zostanie automatycznie wypełniona ze zmiennej środowiskowejAPPLICATIONINSIGHTS_CONNECTION_STRING , jeśli nie zostanie jawnie przekazana. |
APPLICATIONINSIGHTS_CONNECTION_STRING |
logger_name |
Nazwa rejestratora języka Python , w ramach którego są zbierane dane telemetryczne. | N/A |
instrumentation_options |
Zagnieżdżony słownik określający, które instrumentacje mają być włączone lub wyłączone. Instrumentacje są określane przez nazwy bibliotek. Na przykład spowoduje wyłączenie śledzenia rdzeni platformy Azure i instrumentacji platformy Flask, {"azure_sdk": {"enabled": False}, "flask": {"enabled": False}, "django": {"enabled": True}} ale pozostaw włączone instrumentację Django i inne domyślne instrumentacje. Zmienna OTEL_PYTHON_DISABLED_INSTRUMENTATIONS środowiskowa wyjaśniona poniżej może również służyć do wyłączania instrumentacji. |
N/A |
Możesz dodatkowo skonfigurować zmienne środowiskowe OpenTelemetry , takie jak: | Zmienna środowiskowa | Opis | |-------------|---------------------- | OTEL_SERVICE_NAME, OTEL_RESOURCE_ATTRIBUTES | Określa zasób OpenTelemetry skojarzony z aplikacją. | | OTEL_LOGS_EXPORTER
| Jeśli ustawiono wartość None
, wyłącza zbieranie i eksportowanie danych telemetrycznych rejestrowania. | | OTEL_METRICS_EXPORTER
| Jeśli jest ustawiona wartość None
, wyłącza zbieranie i eksportowanie danych telemetrycznych metryk. | | OTEL_TRACES_EXPORTER
| Jeśli jest ustawiona wartość None
, wyłącza zbieranie i eksportowanie danych telemetrycznych śledzenia rozproszonego. | | OTEL_BLRP_SCHEDULE_DELAY
| Określa interwał eksportu rejestrowania w milisekundach. Wartość domyślna to 5000. | | OTEL_BSP_SCHEDULE_DELAY
| Określa interwał eksportu śledzenia rozproszonego w milisekundach. Wartość domyślna to 5000. | | OTEL_TRACES_SAMPLER_ARG
| Określa współczynnik danych telemetrycznych śledzenia rozproszonego do próbkowania. Akceptowane wartości znajdują się w zakresie [0,1]. Wartość domyślna to 1.0, co oznacza, że żadne dane telemetryczne nie są próbkowane. | | OTEL_PYTHON_DISABLED_INSTRUMENTATIONS
| Określa, które z obsługiwanych instrumentacji mają być wyłączone. Wyłączone instrumentacje nie będą instrumentowane w ramach elementu configure_azure_monitor
. Jednak nadal można je ręcznie instrumentować instrument()
bezpośrednio. Akceptuje rozdzielaną przecinkami listę małych liter nazw bibliotek. Na przykład ustaw wartość na wartość , aby "psycopg2,fastapi"
wyłączyć instrumentacje Psycopg2 i FastAPI. Domyślnie jest pusta lista, włączając wszystkie obsługiwane instrumentacje. | | OTEL_EXPERIMENTAL_RESOURCE_DETECTORS
| Eksperymentalna zmienna środowiskowa OpenTelemetry używana do określania detektorów zasobów do wygenerowania atrybutów zasobów. Jest to funkcja eksperymentalna, a nazwa tej zmiennej i jej zachowanie może ulec zmianie w sposób niezgodny z poprzednimi wersjami. Wartość domyślna to "azure_app_service,azure_vm", aby włączyć narzędzia Do wykrywania zasobów platformy Azure dla Azure App Service i maszyny wirtualnej platformy Azure. Aby dodać lub usunąć określone detektory zasobów, ustaw odpowiednio zmienną środowiskową. Aby uzyskać więcej informacji, zobacz dokumentację narzędzia do wykrywania zasobów języka Python openTelemetry . |
Konfiguracje eksportera OpenTelemetry usługi Azure Monitor
Parametry konfiguracji eksportera OpenTelemetry usługi Azure Monitor można przekazać bezpośrednio do configure_azure_monitor
elementu . Zobacz dodatkową konfigurację związaną z eksportowaniem tutaj.
...
configure_azure_monitor(
connection_string="<your-connection-string>",
disable_offline_storage=True,
)
...
Przykłady
Przykłady są dostępne tutaj , aby zademonstrować sposób korzystania z powyższych opcji konfiguracji.
Monitorowanie w Azure Functions
Korelacja śledzenia
Śledzone żądania przychodzące przychodzące przychodzące do aplikacji języka Python hostowanej w Azure Functions nie będą automatycznie skorelowane z śledzonym w nim telemetrią. Korelację śledzenia można ręcznie osiągnąć, wyodrębniając element TraceContext
bezpośrednio, jak pokazano poniżej:
import azure.functions as func
from azure.monitor.opentelemetry import configure_azure_monitor
from opentelemetry import trace
from opentelemetry.propagate import extract
# Configure Azure monitor collection telemetry pipeline
configure_azure_monitor()
def main(req: func.HttpRequest, context) -> func.HttpResponse:
...
# Store current TraceContext in dictionary format
carrier = {
"traceparent": context.trace_context.Traceparent,
"tracestate": context.trace_context.Tracestate,
}
tracer = trace.get_tracer(__name__)
# Start a span using the current context
with tracer.start_as_current_span(
"http_trigger_span",
context=extract(carrier),
):
...
Problemy z rejestrowaniem
Sam proces roboczy Azure Functions wysyła dane telemetryczne rejestrowania bez użycia zestawu SDK usługi Azure Monitor (wywołanie metody ).configure_azure_monitor()
Spowoduje to prawdopodobnie wystąpienie zduplikowanych wpisów telemetrii podczas wysyłania danych telemetrycznych rejestrowania. Naszym zaleceniem dla klientów jest użycie wyłącznie zestawu SDK, ponieważ umożliwi znacznie bardziej rozbudowane dane telemetryczne i funkcje niż użycie wbudowanego elementu udostępnionego przez proces roboczy Azure Functions. Rejestrator telemetrii Azure Functions można wyłączyć, usuwając listę procedur obsługi rejestratora.
...
root_logger = logging.getLogger()
for handler in root_logger.handlers[:]:
root_logger.removeHandler(handler)
...
Pamiętaj, aby wywołać powyższy kod PRZED wszelkimi rejestratorami lub wywołaniem do configure_azure_monitor()
polecenia jest konfiguracja.
Rejestrowanie można również wyłączyć za pośrednictwem konfiguracji Azure Functions.
Wersja 2.x+
...
{
"logging": {
...
"logLevel": {
"default": "None",
...
}
}
}
...
wersja 1.x
...
{
"logger": {
"categoryFilter": {
"defaultLevel": "None",
...
}
}
}
...
Rozwiązywanie problemów
Eksporter zgłasza wyjątki zdefiniowane w usłudze Azure Core.
Następne kroki
Zapoznaj się z dokumentacją , aby uzyskać więcej informacji.
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ę https://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. Wystarczy zrobić to raz dla wszystkich repozytoriów, w przypadku których jest używana nasza umowa CLA.
W tym projekcie przyjęto Kodeks postępowania oprogramowania Open Source firmy Microsoft. Aby uzyskać więcej informacji, zobacz Często zadawane pytania dotyczące kodeksu postępowania lub skontaktuj się z opencode@microsoft.com dodatkowymi pytaniami lub komentarzami.
Dodatkowa dokumentacja
Azure SDK for Python