Partager via

Bibliothèque cliente de distribution Opentelemetry Azure Monitor pour Python - version 1.1.1

  • Article

La distribution Azure Monitor d’Opentelemetry Python fournit plusieurs composants installables disponibles pour une solution de supervision Azure Monitor Opentelemetry. Il vous permet d’instrumenter vos applications Python pour capturer et signaler des données de télémétrie à Azure Monitor via les exportateurs Azure Monitor.

Cette distribution installe automatiquement les bibliothèques suivantes :

Instrumentations officiellement prises en charge

Les instrumentations OpenTelemetry permettent la collecte automatique des requêtes envoyées à partir de bibliothèques instrumentées sous-jacentes. Voici une liste d’instrumentations OpenTelemetry fournies avec la distribution Azure Monitor. Ces instrumentations sont activées par défaut. Consultez la section Utilisation ci-dessous pour savoir comment refuser ces instrumentations.

Instrumentation Nom de la bibliothèque prise en charge Versions prises en charge
OpenTelemetry de traçage Azure Core azure_sdk
OpenTelemetry Django Instrumentation Django ici.
OpenTelemetry FastApi Instrumentation fastapi ici.
OpenTelemetry Flask Instrumentation flask ici.
OpenTelemetry Psycopg2 Instrumentation psycopg2 ici.
OpenTelemetry Requests Instrumentation requests ici.
OpenTelemetry UrlLib Instrumentation urllib Tous
OpenTelemetry UrlLib3 Instrumentation urllib3 ici.

Si vous souhaitez ajouter la prise en charge d’une autre instrumentation OpenTelemetry, envoyez une demande de fonctionnalité. En attendant, vous pouvez utiliser manuellement l’instrumentation OpenTelemetry via ses propres API (c’est-à-dire instrument()) dans votre code. Pour obtenir un exemple, consultez cette page.

Concepts clés

Ce package regroupe une série de composants OpenTelemetry et Azure Monitor pour permettre la collecte et l’envoi de données de télémétrie à Azure Monitor. Pour l’instrumentation MANUAL, utilisez la configure_azure_monitor fonction . L’instrumentation AUTOMATIQUE n’est pas encore prise en charge.

Les exportateurs OpenTelemetry d’Azure Monitor sont les main composants pour y parvenir. Vous pourrez utiliser les exportateurs et leurs API directement via ce package. Consultez la documentation de l’exportateur pour comprendre comment les composants OpenTelemetry et Azure Monitor fonctionnent pour activer la collecte et l’exportation de télémétrie.

Actuellement, toutes les instrumentations disponibles dans OpenTelemetry sont dans un état bêta, ce qui signifie qu’elles ne sont pas stables et peuvent avoir des modifications cassants à l’avenir. Des efforts sont déployés pour les pousser à un état plus stable.

Prise en main

Prérequis

Pour utiliser ce package, vous devez disposer des éléments suivants :

Installer le package

Installez la distribution Opentelemetry Azure Monitor avec pip :

pip install azure-monitor-opentelemetry

Utilisation

Vous pouvez utiliser configure_azure_monitor pour configurer l’instrumentation de votre application sur Azure Monitor. configure_azure_monitor prend en charge les arguments facultatifs suivants. Tous les paramètres de pass-in sont prioritaires sur toutes les variables d’environnement associées.

Paramètre Description Variable d’environnement
connection_string Chaîne de connexion pour votre ressource Application Insights. Le chaîne de connexion est automatiquement renseigné à partir de la variable d’environnement APPLICATIONINSIGHTS_CONNECTION_STRING s’il n’est pas explicitement transmis. APPLICATIONINSIGHTS_CONNECTION_STRING
logger_name Nom de l’enregistreur d’événements Python sous lequel les données de télémétrie sont collectées. N/A
instrumentation_options Dictionnaire imbriqué qui détermine les instrumentations à activer ou désactiver. Les instrumentations sont référencées par leur nom de bibliothèque. Par exemple, désactive Azure Core Tracing et l’instrumentation Flask, {"azure_sdk": {"enabled": False}, "flask": {"enabled": False}, "django": {"enabled": True}} mais laisse Django et les autres instrumentations par défaut activées. La OTEL_PYTHON_DISABLED_INSTRUMENTATIONS variable d’environnement expliquée ci-dessous peut également être utilisée pour désactiver les instrumentations. N/A

Vous pouvez configurer davantage avec les variables d’environnement OpenTelemetry telles que : | Variable d’environnement | Description | |-------------|----------------------| | OTEL_SERVICE_NAME, OTEL_RESOURCE_ATTRIBUTES | Spécifie la ressource OpenTelemetry associée à votre application. | | OTEL_LOGS_EXPORTER | Si la valeur est définie sur None, désactive la collecte et l’exportation des données de télémétrie de journalisation. | | OTEL_METRICS_EXPORTER | Si la valeur est définie Nonesur , désactive la collecte et l’exportation de la télémétrie des métriques. | | OTEL_TRACES_EXPORTER | Si la valeur est définie sur None, désactive la collecte et l’exportation des données de télémétrie de suivi distribuées. | | OTEL_BLRP_SCHEDULE_DELAY | Spécifie l’intervalle d’exportation de journalisation en millisecondes. La valeur par défaut est 5 000. | | OTEL_BSP_SCHEDULE_DELAY | Spécifie l’intervalle d’exportation de suivi distribué en millisecondes. La valeur par défaut est 5 000. | | OTEL_TRACES_SAMPLER_ARG | Spécifie le ratio de télémétrie de suivi distribué à échantillonner. Les valeurs acceptées se trouvent dans la plage [0,1]. La valeur par défaut est 1.0, ce qui signifie qu’aucune télémétrie n’est échantillonnées. | | OTEL_PYTHON_DISABLED_INSTRUMENTATIONS | Spécifie laquelle des instrumentations prises en charge doit être désactivée. Les instrumentations désactivées ne sont pas instrumentées dans le cadre de configure_azure_monitor. Toutefois, ils peuvent toujours être instrumentés manuellement avec instrument() directement. Accepte une liste séparée par des virgules de noms de bibliothèque en minuscules. Par exemple, définissez sur "psycopg2,fastapi" pour désactiver les instrumentations Psycopg2 et FastAPI. Par défaut, une liste vide permet d’activer toutes les instrumentations prises en charge. | | OTEL_EXPERIMENTAL_RESOURCE_DETECTORS | Variable d’environnement OpenTelemetry expérimentale utilisée pour spécifier des détecteurs de ressources à utiliser pour générer des attributs de ressource. Il s’agit d’une fonctionnalité expérimentale et le nom de cette variable et son comportement peuvent changer d’une manière non compatible descendante. La valeur par défaut est « azure_app_service azure_vm » pour activer les détecteurs de ressources Azure pour Azure App Service et la machine virtuelle Azure. Pour ajouter ou supprimer des détecteurs de ressources spécifiques, définissez la variable d’environnement en conséquence. Pour plus d’informations, consultez la documentation OpenTelemetry Python Resource Detector . |

Configurations de l’exportateur OpenTelemetry d’Azure Monitor

Vous pouvez passer les paramètres de configuration de l’exportateur OpenTelemetry azure monitor directement dans configure_azure_monitor. Consultez la configuration supplémentaire liée à l’exportation ici.

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

Exemples

Des exemples sont disponibles ici pour montrer comment utiliser les options de configuration ci-dessus.

Surveillance dans Azure Functions

Corrélation de trace

Le suivi des requêtes entrantes entrantes dans votre application Python hébergée dans Azure Functions ne sera pas automatiquement corrélé avec les données de télémétrie qui y sont suivies. Vous pouvez obtenir manuellement une corrélation de trace en extrayant directement le TraceContext comme indiqué ci-dessous :


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èmes de journalisation

Le Azure Functions worker lui-même envoie la télémétrie de journalisation lui-même sans utiliser le sdk azure monitor (l’appel à configure_azure_monitor()). Cela vous amènera à rencontrer des entrées de télémétrie dupliquées lors de l’envoi de la télémétrie de journalisation. Notre recommandation aux clients est d’utiliser uniquement le SDK, car il permettra des données de télémétrie et des fonctionnalités beaucoup plus riches que l’utilisation de celle intégrée fournie par le Azure Functions worker. Vous pouvez désactiver l’enregistreur de télémétrie Azure Functions en effaçant la liste des gestionnaires de votre enregistreur d’événements.

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

Veillez à appeler le ci-dessus AVANT tout enregistreur d’événements ou l’appel à configure_azure_monitor() est configuré.

Vous pouvez également désactiver la journalisation via Azure Functions configuration.

v2.x+

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

v1.x

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

Dépannage

L’exportateur déclenche des exceptions définies dans Azure Core.

Étapes suivantes

Pour plus d’informations, consultez la documentation .

Contribution

Ce projet accepte les contributions et les suggestions. La plupart des contributions vous demandent d’accepter un contrat de licence de contribution (CLA) déclarant que vous avez le droit de nous accorder, et que vous nous accordez réellement, les droits d’utilisation de votre contribution. Pour plus d’informations, visitez https://cla.microsoft.com.

Quand vous envoyez une demande de tirage (pull request), un bot CLA détermine automatiquement si vous devez fournir un contrat CLA et agrémenter la demande de tirage de façon appropriée (par exemple, avec une étiquette ou un commentaire). Suivez simplement les instructions fournies par le bot. Vous ne devez effectuer cette opération qu’une seule fois sur tous les dépôts utilisant notre contrat CLA.

Ce projet a adopté le Code de conduite Open Source de Microsoft. Pour plus d’informations, consultez les Questions fréquentes (FAQ) sur le code de conduite ou envoyez vos questions ou vos commentaires à opencode@microsoft.com.

Documentation complémentaire