Sdílet prostřednictvím

Klientská knihovna Opentelemetry Distro pro Azure Monitor pro Python – verze 1.1.1

  • Článek

Distribuce Azure Monitoru Opentelemetry Pythonu poskytuje několik instalovatelných komponent dostupných pro řešení monitorování opentelemetry služby Azure Monitor. Umožňuje instrumentovat aplikace v Pythonu, aby zaznamenávaly telemetrická data a hlásily je do služby Azure Monitor prostřednictvím exportérů Azure Monitoru.

Tato distribuce automaticky nainstaluje následující knihovny:

Oficiálně podporované instrumentace

Instrumentace OpenTelemetry umožňují automatické shromažďování požadavků odesílaných ze základních instrumentovaných knihoven. Následuje seznam instrumentací OpenTelemetry, které jsou součástí distribuce Azure Monitoru. Tyto instrumentace jsou ve výchozím nastavení povolené. V části Využití níže najdete informace o tom, jak se odhlásit od těchto instrumentací.

Instrumentace Název podporované knihovny Podporované verze
Azure Core Tracing OpenTelemetry azure_sdk
OpenTelemetry Django Instrumentation Django Odkaz
Instrumentace OpenTelemetry FastApi fastapi Odkaz
Instrumentace OpenTelemetry Flask Baňky Odkaz
Instrumentace OpenTelemetry Psycopg2 psycopg2 Odkaz
Instrumentace žádostí OpenTelemetry požadavky Odkaz
Instrumentace knihovny UrlLib OpenTelemetry urllib Vše
Instrumentace OpenTelemetry UrlLib3 urllib3 Odkaz

Pokud chcete přidat podporu pro další instrumentaci OpenTelemetry, odešlete žádost o funkci. Mezitím můžete instrumentaci OpenTelemetry použít ručně prostřednictvím vlastních rozhraní API (tj. instrument()) v kódu. Příklad najdete tady.

Klíčové koncepty

Tento balíček seskupuje řadu komponent OpenTelemetry a Azure Monitor, které umožňují shromažďování a odesílání telemetrických dat do služby Azure Monitor. Pro ruční instrumentaci použijte configure_azure_monitor funkci . AUTOMATICKÁ instrumentace se zatím nepodporuje.

Exportéry OpenTelemetry pro Azure Monitor jsou hlavními součástmi tohoto cíle. Exportéry a jejich rozhraní API budete moct používat přímo prostřednictvím tohoto balíčku. Projděte si dokumentaci k exportu, kde najdete informace o tom, jak komponenty OpenTelemetry a Azure Monitor fungují při povolování shromažďování a exportu telemetrie.

V současné době jsou všechny instrumentace dostupné v OpenTelemetry ve stavu beta, což znamená, že nejsou stabilní a v budoucnu můžou mít zásadní změny. Snažíme se je posunout do stabilnějšího stavu.

Začínáme

Požadavky

Pokud chcete tento balíček použít, musíte mít:

Instalace balíčku

Nainstalujte distribuci Opentelemetry služby Azure Monitor pomocí pip:

pip install azure-monitor-opentelemetry

Využití

Pomocí příkazu configure_azure_monitor můžete pro svou aplikaci nastavit instrumentaci na Azure Monitor. configure_azure_monitor podporuje následující volitelné argumenty. Všechny předávací parametry mají přednost před všemi souvisejícími proměnnými prostředí.

Parametr Popis Proměnná prostředí
connection_string Připojovací řetězec pro váš prostředek Application Insights. Připojovací řetězec se automaticky vyplní z APPLICATIONINSIGHTS_CONNECTION_STRING proměnné prostředí, pokud není explicitně předána. APPLICATIONINSIGHTS_CONNECTION_STRING
logger_name Název protokolovacího nástroje Pythonu , ve kterém se shromažďuje telemetrie. N/A
instrumentation_options Vnořený slovník, který určuje, které instrumentace se mají povolit nebo zakázat. Na instrumentace se odkazují názvy jejich knihoven. Nástroj například {"azure_sdk": {"enabled": False}, "flask": {"enabled": False}, "django": {"enabled": True}} zakáže trasování Azure Core a instrumentaci Flask, ale ponechá povolenou službu Django a další výchozí instrumentace. K OTEL_PYTHON_DISABLED_INSTRUMENTATIONS zakázání instrumentace můžete použít také proměnnou prostředí vysvětlenou níže. N/A

Další konfiguraci můžete provést pomocí proměnných prostředí OpenTelemetry , například: | Proměnná prostředí | Popis | |-------------|----------------------| | OTEL_SERVICE_NAME, OTEL_RESOURCE_ATTRIBUTES | Určuje prostředek OpenTelemetry přidružený k vaší aplikaci. | | OTEL_LOGS_EXPORTER | Pokud je tato možnost nastavená na None, zakáže shromažďování a export telemetrie protokolování. | | OTEL_METRICS_EXPORTER | Pokud je tato možnost nastavená na None, zakáže shromažďování a export telemetrických dat metrik. | | OTEL_TRACES_EXPORTER | Pokud je tato možnost nastavená na None, zakáže shromažďování a export telemetrie distribuovaného trasování. | | OTEL_BLRP_SCHEDULE_DELAY | Určuje interval exportu protokolování v milisekundách. Výchozí hodnota je 5000. | | OTEL_BSP_SCHEDULE_DELAY | Určuje interval exportu distribuovaného trasování v milisekundách. Výchozí hodnota je 5000. | | OTEL_TRACES_SAMPLER_ARG | Určuje poměr telemetrie distribuovaného trasování, která se má vzorkovat. Přípustné hodnoty jsou v rozsahu [0;1]. Výchozí hodnota je 1.0, což znamená, že se nevyubíruje žádná telemetrie. | | OTEL_PYTHON_DISABLED_INSTRUMENTATIONS | Určuje, která z podporovaných instrumentací se má zakázat. Zakázané instrumentace se nebudou instrumentovat jako součást nástroje configure_azure_monitor. Přesto je možné je ručně instrumentovat přímo pomocí instrument() nástroje . Přijímá čárkami oddělený seznam názvů knihoven malými písmeny. Pokud chcete například zakázat instrumentace Psycopg2 a FastAPI, nastavte na "psycopg2,fastapi" hodnotu . Výchozí hodnota je prázdný seznam a povoluje všechny podporované instrumentace. | | OTEL_EXPERIMENTAL_RESOURCE_DETECTORS | Experimentální proměnná prostředí OpenTelemetry používaná k určení detektorů prostředků, které se mají použít ke generování atributů prostředků. Jedná se o experimentální funkci a název této proměnné a její chování se může změnit způsobem, který není zpětně kompatibilní. Výchozí hodnota je "azure_app_service,azure_vm", aby se povolily detektory prostředků Azure pro Azure App Service a virtuální počítač Azure. Pokud chcete přidat nebo odebrat konkrétní detektory prostředků, nastavte odpovídajícím způsobem proměnnou prostředí. Další informace najdete v dokumentaci k Detektoru prostředků Pythonu pro OpenTelemetry . |

Konfigurace nástroje pro export OpenTelemetry pro Azure Monitor

Parametry konfigurace exportéru OpenTelemetry pro Azure Monitor můžete předat přímo do configure_azure_monitornástroje . Další konfiguraci související s exportem najdete tady.

...
configure_azure_monitor(
   connection_string="<your-connection-string>",
   disable_offline_storage=True,
)
...

Příklady

Tady jsou k dispozici ukázky, které ukazují, jak využít výše uvedené možnosti konfigurace.

Monitorování v Azure Functions

Korelace trasování

Sledované příchozí požadavky přicházející do vaší aplikace Python hostované v Azure Functions nebudou automaticky korelovány s telemetrií, která se v ní sleduje. Korelace trasování můžete ručně získat extrakcí přímo, TraceContext jak je znázorněno níže:


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),
   ):
      ...

Problémy s protokolováním

Samotný pracovní proces Azure Functions sám odesílá telemetrii protokolování bez použití sady Azure Monitor SDK (volání ).configure_azure_monitor() To způsobí, že při odesílání telemetrie protokolování pravděpodobně dojde k duplicitním položkám telemetrie. Zákazníkům doporučujeme používat výhradně sadu SDK, protože umožní mnohem bohatší telemetrii a funkce než předdefinovaná telemetrie, kterou poskytuje pracovní proces Azure Functions. Protokolovací Azure Functions telemetrie můžete vypnout tak, že vymažete seznam obslužných rutin tohoto nástroje.

...
root_logger = logging.getLogger()
for handler in root_logger.handlers[:]:
    root_logger.removeHandler(handler)
...

Nezapomeňte volat výše uvedené před tím, než se nastaví protokolovací nástroje nebo volání configure_azure_monitor() .

Protokolování můžete také zakázat prostřednictvím konfigurace Azure Functions.

v2.x+

...
{
  "logging": {
    ...
    "logLevel": {
      "default": "None",
      ...
    }
  }
}
...

v1.x

...
{
  "logger": {
    "categoryFilter": {
      "defaultLevel": "None",
      ...
    }
  }
}
...

Řešení potíží

Vývozce vyvolává výjimky definované v Azure Core.

Další kroky

Další informace najdete v dokumentaci .

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 tady: https://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. Pro všechna úložiště používající naši smlouvu CLA to stačí udělat jenom 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í nebo kontaktujte s opencode@microsoft.com případnými dalšími dotazy nebo připomínkami.

Další dokumentace