Azure Monitor Opentelemetry Distro-clientbibliotheek voor Python - versie 1.1.1

Artikel
12/06/2023

De Azure Monitor-distributie van Opentelemetry Python biedt meerdere installeerbare onderdelen die beschikbaar zijn voor een Opentelemetry Azure Monitor-bewakingsoplossing. Hiermee kunt u uw Python-toepassingen instrumentiseren om telemetrie vast te leggen en te rapporteren aan Azure Monitor via de Azure Monitor-exporteurs.

Met deze distributie worden automatisch de volgende bibliotheken geïnstalleerd:

Azure Monitor OpenTelemetry-exporteurs
Een subset van OpenTelemetry-instrumentaties die officieel worden ondersteund, zoals hieronder wordt vermeld.

Officieel ondersteunde instrumentaties

Met OpenTelemetry-instrumentaties kunt u automatisch aanvragen verzamelen die worden verzonden vanuit onderliggende geïnstrueerde bibliotheken. Hier volgt een lijst met OpenTelemetry-instrumentaties die worden meegeleverd met de Azure Monitor-distributie. Deze instrumentaties zijn standaard ingeschakeld. Zie de sectie Gebruik hieronder voor informatie over het afmelden van deze instrumentaties.

Instrumentation	Naam van ondersteunde bibliotheek	Ondersteunde versies
Azure Core Tracing OpenTelemetry	`azure_sdk`
OpenTelemetry Django Instrumentation	Django	Link
OpenTelemetry FastApi Instrumentation	fastapi	Link
OpenTelemetry Flask Instrumentation	Kolf	Link
OpenTelemetry Psycopg2-instrumentatie	psycopg2	Link
Instrumentatie van OpenTelemetry-aanvragen	aanvragen	Link
OpenTelemetry UrlLib Instrumentation	urllib	Alles
OpenTelemetry UrlLib3 Instrumentation	urllib3	Link

Als u ondersteuning wilt toevoegen voor een andere OpenTelemetry-instrumentatie, dient u een functieaanvraag in. In de tussentijd kunt u de OpenTelemetry-instrumentatie handmatig gebruiken via zijn eigen API's (d.w.z. instrument()) in uw code. Zie dit voor een voorbeeld.

Belangrijkste concepten

Dit pakket bundelt een reeks OpenTelemetry- en Azure Monitor-onderdelen om het verzamelen en verzenden van telemetriegegevens naar Azure Monitor mogelijk te maken. Gebruik voor HANDMATIGe instrumentatie de configure_azure_monitor functie . AUTOMATISCHE instrumentatie wordt nog niet ondersteund.

De Azure Monitor OpenTelemetry-exporteurs zijn de belangrijkste onderdelen om dit te bereiken. U kunt de exporteurs en hun API's rechtstreeks via dit pakket gebruiken. Ga naar de exportdocumentatie om te begrijpen hoe OpenTelemetry- en Azure Monitor-onderdelen werken bij het inschakelen van telemetrieverzameling en -export.

Momenteel bevinden alle instrumentaties die beschikbaar zijn in OpenTelemetry zich in een bètastatus, wat betekent dat ze niet stabiel zijn en in de toekomst mogelijk wijzigingen veroorzaken die fouten veroorzaken. Er wordt geprobeerd deze naar een stabielere toestand te pushen.

Aan de slag

Vereisten

Als u dit pakket wilt gebruiken, hebt u het volgende nodig:

Azure-abonnement: maak een gratis account
Azure Monitor - Application Insights gebruiken
Opentelemetry SDK - Opentelemetry SDK voor Python
Python 3.7 of hoger - Python installeren

Het pakket installeren

Installeer de Azure Monitor Opentelemetry-distributie met pip:

pip install azure-monitor-opentelemetry

Gebruik

U kunt gebruiken configure_azure_monitor om instrumentatie voor uw app in te stellen voor Azure Monitor. configure_azure_monitor ondersteunt de volgende optionele argumenten. Alle pass-in-parameters hebben prioriteit boven alle gerelateerde omgevingsvariabelen.

Parameter	Beschrijving	Omgevingsvariabele
`connection_string`	De verbindingsreeks voor uw Application Insights-resource. De verbindingsreeks wordt automatisch ingevuld vanuit de `APPLICATIONINSIGHTS_CONNECTION_STRING` omgevingsvariabele als deze niet expliciet wordt doorgegeven.	`APPLICATIONINSIGHTS_CONNECTION_STRING`
`logger_name`	De naam van de Python-logboekregistratie waaronder telemetrie wordt verzameld.	`N/A`
`instrumentation_options`	Een geneste woordenlijst die bepaalt welke instrumentaties moeten worden in- of uitgeschakeld. Instrumentaties worden aangeduid met hun bibliotheeknamen. Hiermee schakelt u bijvoorbeeld Azure Core Tracing en de Flask-instrumentatie uit, `{"azure_sdk": {"enabled": False}, "flask": {"enabled": False}, "django": {"enabled": True}}` maar blijft Django en de andere standaardinstrumenten ingeschakeld. De `OTEL_PYTHON_DISABLED_INSTRUMENTATIONS` hieronder beschreven omgevingsvariabele kan ook worden gebruikt om instrumentaties uit te schakelen.	`N/A`

U kunt verder configureren met OpenTelemetry-omgevingsvariabelen, zoals: | Omgevingsvariabele | Beschrijving | |-------------|----------------------| | OTEL_SERVICE_NAME, OTEL_RESOURCE_ATTRIBUTES | Hiermee geeft u de OpenTelemetry-resource op die is gekoppeld aan uw toepassing. | | OTEL_LOGS_EXPORTER | Als dit is ingesteld op None, wordt het verzamelen en exporteren van logboektelemetrie uitgeschakeld. | | OTEL_METRICS_EXPORTER | Als dit is ingesteld op None, wordt het verzamelen en exporteren van metrische telemetrie uitgeschakeld. | | OTEL_TRACES_EXPORTER | Als dit is ingesteld op None, schakelt u het verzamelen en exporteren van telemetrie van gedistribueerde tracering uit. | | OTEL_BLRP_SCHEDULE_DELAY | Hiermee geeft u het exportinterval voor logboekregistratie in milliseconden op. De standaardwaarde is 5000. | | OTEL_BSP_SCHEDULE_DELAY | Hiermee geeft u het exportinterval voor gedistribueerde tracering in milliseconden op. De standaardwaarde is 5000. | | OTEL_TRACES_SAMPLER_ARG | Hiermee geeft u de verhouding op van gedistribueerde traceringstelemetrie die moet worden bemonsterd. Geaccepteerde waarden bevinden zich in het bereik [0,1]. De standaardwaarde is 1.0, wat betekent dat er geen telemetrie wordt genomen. | | OTEL_PYTHON_DISABLED_INSTRUMENTATIONS | Hiermee geeft u op welke van de ondersteunde instrumentaties moet worden uitgeschakeld. Uitgeschakelde instrumentaties worden niet geïnstrueerd als onderdeel van configure_azure_monitor. Ze kunnen echter nog steeds handmatig rechtstreeks worden geïnstrueerd instrument() . Accepteert een door komma's gescheiden lijst met bibliotheeknamen in kleine letters. Stel bijvoorbeeld in op om "psycopg2,fastapi" de instrumentaties Psycopg2 en FastAPI uit te schakelen. Wordt standaard ingesteld op een lege lijst, waardoor alle ondersteunde instrumentaties worden ingeschakeld. | | OTEL_EXPERIMENTAL_RESOURCE_DETECTORS | Een experimentele OpenTelemetry-omgevingsvariabele die wordt gebruikt om resourcedetecties op te geven die moeten worden gebruikt om resourcekenmerken te genereren. Dit is een experimentele functie en de naam van deze variabele en het gedrag kunnen veranderen op een niet-achterwaarts compatibele manier. De standaardinstelling is 'azure_app_service,azure_vm' om de Azure-resourcedetectoren in te schakelen voor Azure App Service en Azure-VM. Als u specifieke resourcedetectoren wilt toevoegen of verwijderen, stelt u de omgevingsvariabele dienovereenkomstig in. Zie de Documentatie voor OpenTelemetry Python Resource Detector voor meer informatie. |

Azure Monitor OpenTelemetry Exporter-configuraties

U kunt configuratieparameters van Azure Monitor OpenTelemetry-exporteurs rechtstreeks doorgeven aan configure_azure_monitor. Zie hier aanvullende configuratie met betrekking tot exporteren.

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

Voorbeelden

Voorbeelden zijn hier beschikbaar om te laten zien hoe u de bovenstaande configuratieopties kunt gebruiken.

Bewaking in Azure Functions

Correlatie traceren

Bijgehouden binnenkomende aanvragen die binnenkomen in uw Python-toepassing die wordt gehost in Azure Functions, worden niet automatisch gecorreleerd met telemetriegegevens die erin worden bijgehouden. U kunt handmatig traceringscorrelatie bereiken door de TraceContext rechtstreeks uit te pakken zoals hieronder wordt weergegeven:


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

Problemen met logboekregistratie

De Azure Functions-werkrol verzendt zelf logboektelemetrie zonder het gebruik van de Azure Monitor-SDK (de aanroep naar configure_azure_monitor()). Dit zorgt ervoor dat u mogelijk dubbele telemetriegegevens ondervindt bij het verzenden van logboektelemetrie. Onze aanbeveling aan klanten is om alleen de SDK te gebruiken, omdat deze veel uitgebreidere telemetrie en functies toestaat dan het gebruik van de ingebouwde telemetrie die wordt geleverd door de Azure Functions worker. U kunt de Azure Functions telemetrielogboekregistratie uitschakelen door de lijst met handlers van uw logboekregistratie te wissen.

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

Zorg ervoor dat u het bovenstaande aanroept VOORDAT er logboekregistraties of de aanroep naar configure_azure_monitor() is ingesteld.

U kunt logboekregistratie ook uitschakelen via Azure Functions configuratie.

v2.x+

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

v1.x

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

Problemen oplossen

De exporteur genereert uitzonderingen die zijn gedefinieerd in Azure Core.

Volgende stappen

Raadpleeg de documentatie voor meer informatie.

Bijdragen

Wij verwelkomen bijdragen en suggesties voor dit project. Voor de meeste bijdragen moet u instemmen met een licentieovereenkomst voor bijdragers (CLA: Contributor License Agreement) waarin u verklaart dat u gerechtigd bent ons het recht te geven uw bijdrage te gebruiken, en dat u dit ook doet. Ga naar https://cla.microsoft.com voor meer informatie.

Wanneer u een pull-aanvraag indient, wordt met een CLA-bot automatisch bepaald of u een CLA moet verschaffen en wordt de pull-aanvraag dienovereenkomstig opgemaakt (bijvoorbeeld met een label of commentaar). Volg gewoon de instructies van de bot. U hoeft dit maar eenmaal te doen voor alle repo's waar gebruik wordt gemaakt van onze CLA.

Op dit project is de Microsoft Open Source Code of Conduct (Microsoft Open Source-gedragscode) van toepassing. Zie voor meer informatie de veelgestelde vragen over de gedragscode of neem contact op opencode@microsoft.com met eventuele aanvullende vragen of opmerkingen.

Delen via