Udostępnij za pośrednictwem

Biblioteka klienta dystrybucji opentelemetrii usługi Azure Monitor dla języka Python — wersja 1.1.1

  • Artykuł

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:

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:

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_monitorelementu . 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