Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.
# Migrer vers OpenTelemetry Python
Ce guide vous aide à migrer les applications Python du SDK X-Ray vers l' OpenTelemetry instrumentation. Il couvre les approches d'instrumentation automatique et manuelle, avec des exemples de code pour des scénarios courants.
**Topics**
+ [Solutions d'instrumentation automatique à code zéro](#zero-code-python)
+ [Instrumentez manuellement vos applications](#manual-instrumentation-python)
+ [Initialisation de la configuration de suivi](#manual-instrumentation-python-tracing)
+ [Suivi des demandes entrantes](#tracing-incoming-requests-python)
+ [AWS Instrumentation du SDK](#aws-sdk-instrumentation-python)
+ [Instrumentation des appels HTTP sortants par le biais de requêtes](#http-instrumentation-python)
+ [Support d'instrumentation pour d'autres bibliothèques](#xray-migration-libraries-python)
+ [Création manuelle de données de trace](#manual-trace-creation-python)
+ [Instrumentation Lambda](#lambda-instrumentation-python)
## Solutions d'instrumentation automatique à code zéro
Avec le SDK X-Ray, vous deviez modifier le code de votre application pour suivre les demandes. OpenTelemetry propose des solutions d'instrumentation automatique sans code pour suivre les demandes. Avec OpenTelemetry, vous avez la possibilité d'utiliser des solutions d'auto-instrumentation à code zéro pour suivre les demandes.
**Code zéro avec instrumentations automatiques OpenTelemetry basées sur la base**
1. Utilisation de la AWS distribution pour l'instrumentation automatique OpenTelemetry (ADOT) pour Python — Pour l'instrumentation automatique pour les applications Python, voir [Traçage et métriques avec la AWS distribution pour OpenTelemetry l'instrumentation](https://aws-otel.github.io/docs/getting-started/python-sdk/auto-instr) automatique de Python.
(Facultatif) Vous pouvez également activer les signaux CloudWatch d'application lorsque vous instrumentez automatiquement vos applications à l' AWS aide de l'instrumentation automatique ADOT Python pour surveiller l'état actuel des applications et suivre les performances des applications à long terme par rapport à vos objectifs commerciaux. Application Signals vous offre une vue unifiée et orientée application de vos services, dépendances et applications, et vous aide à surveiller et à trier l’état des applications.
1. Utilisation de l'instrumentation automatique à code zéro en OpenTelemetry Python — Pour l'instrumentation automatique avec OpenTelemetry Python, voir Instrumentation en [code zéro en Python](https://opentelemetry.io/docs/zero-code/python/).
## Instrumentez manuellement vos applications
Vous pouvez instrumenter manuellement vos applications à l'aide de la `pip` commande.
------
#### [ With X-Ray SDK ]
```
pip install aws-xray-sdk
```
------
#### [ With OpenTelemetry SDK ]
```
pip install opentelemetry-api opentelemetry-sdk opentelemetry-exporter-otlp opentelemetry-propagator-aws-xray
```
------
## Initialisation de la configuration de suivi
------
#### [ With X-Ray SDK ]
Dans X-Ray, le global `xray_recorder` est initialisé et utilisé pour générer des segments et des sous-segments.
------
#### [ With OpenTelemetry SDK ]
**Note**
X-Ray Remote Sampling n'est actuellement pas disponible pour être configuré pour OpenTelemetry Python. Cependant, la prise en charge de l'échantillonnage à distance X-Ray est actuellement disponible via l'ADOT Auto-Instrumentation pour Python.
Dans OpenTelemetry, vous devez initialiser un global`TracerProvider`. Vous pouvez `TracerProvider` ainsi acquérir un [traceur](https://opentelemetry.io/docs/concepts/signals/traces/#tracer) que vous pouvez utiliser pour générer des spans n'importe où dans votre application. Il est recommandé de configurer les composants suivants :
+ `OTLPSpanExporter`— Nécessaire pour exporter les traces vers l' CloudWatch OpenTelemetry agent/le collecteur
+ Un propagateur de AWS rayons X : nécessaire pour propager le contexte de trace aux AWS services intégrés à X-Ray
```
from opentelemetry import (
trace,
propagate
)
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.propagators.aws import AwsXRayPropagator
# Sends generated traces in the OTLP format to an OTel Collector running on port 4318
otlp_exporter = OTLPSpanExporter(endpoint="http://localhost:4318/v1/traces")
# Processes traces in batches as opposed to immediately one after the other
span_processor = BatchSpanProcessor(otlp_exporter)
# More configurations can be done here. We will visit them later.
# Sets the global default tracer provider
provider = TracerProvider(active_span_processor=span_processor)
trace.set_tracer_provider(provider)
# Configures the global propagator to use the X-Ray Propagator
propagate.set_global_textmap(AwsXRayPropagator())
# Creates a tracer from the global tracer provider
tracer = trace.get_tracer("my.tracer.name")
# Use this tracer to create Spans
```
------
**Avec l'auto-instrumentation ADOT pour Python**
Vous pouvez utiliser l'instrumentation automatique ADOT pour Python afin de configurer automatiquement vos OpenTelemetry applications Python. En utilisant l'instrumentation automatique ADOT, vous n'avez pas besoin de modifier manuellement le code pour suivre les demandes entrantes ou pour suivre les bibliothèques telles que le AWS SDK ou les clients HTTP. Pour plus d'informations, consultez [Tracing and Metrics with the AWS Distro for OpenTelemetry Python Auto-Instrumentation](https://aws-otel.github.io/docs/getting-started/python-sdk/auto-instr).
L'auto-instrumentation ADOT pour Python prend en charge :
+ Échantillonnage à distance X-Ray via la variable d'environnement `export OTEL_TRACES_SAMPLER=xray`
+ Propagation du contexte X-Ray Trace (activée par défaut)
+ Détection des ressources (la détection des ressources pour les environnements Amazon EC2, Amazon ECS et Amazon EKS est activée par défaut)
+ Les instrumentations de bibliothèque automatiques pour toutes les OpenTelemetry instrumentations prises en charge sont activées par défaut. Vous pouvez le désactiver de manière sélective via la variable d'`OTEL_PYTHON_DISABLED_INSTRUMENTATIONS `environnement. (tous sont activés par défaut)
+ Création manuelle de Spans
**Des plug-ins du service X-Ray aux fournisseurs de OpenTelemetry AWS ressources**
Le SDK X-Ray fournit des plug-ins que vous pouvez ajouter pour capturer les informations spécifiques `xray_recorder` à la plate-forme à partir du service hébergé tel qu'Amazon EC2, Amazon ECS et Elastic Beanstalk. Il est similaire aux fournisseurs de ressources en OpenTelemetry ce sens qu'il capture les informations sous forme d'attributs de ressources. Plusieurs fournisseurs de ressources sont disponibles pour différentes AWS plateformes.
+ Commencez par installer le package d' AWS extension, `pip install opentelemetry-sdk-extension-aws`
+ Configurez le détecteur de ressources souhaité. L'exemple suivant montre comment configurer le fournisseur de ressources Amazon EC2 dans le SDK OpenTelemetry
```
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.extension.aws.resource.ec2 import (
AwsEc2ResourceDetector,
)
from opentelemetry.sdk.resources import get_aggregated_resources
provider = TracerProvider(
active_span_processor=span_processor,
resource=get_aggregated_resources([
AwsEc2ResourceDetector(),
]))
trace.set_tracer_provider(provider)
```
## Suivi des demandes entrantes
------
#### [ With X-Ray SDK ]
Le SDK Python X-Ray prend en charge les frameworks d'applications tels que Django, Flask et Bottle pour suivre les demandes entrantes pour les applications Python exécutées sur ces derniers. Cela se fait en ajoutant `XRayMiddleware` à l'application pour chaque framework.
------
#### [ With OpenTelemetry SDK ]
OpenTelemetry fournit des instrumentations pour [Django](https://opentelemetry-python-contrib.readthedocs.io/en/latest/instrumentation/django/django.html) et [Flask](https://opentelemetry-python-contrib.readthedocs.io/en/latest/instrumentation/flask/flask.html) via les bibliothèques d'instrumentation spécifiques. Aucune instrumentation pour Bottle n'est disponible dans OpenTelemetry, les applications peuvent toujours être tracées à l'aide de l'[instrumentation OpenTelemetry WSGI](https://opentelemetry-python-contrib.readthedocs.io/en/latest/instrumentation/wsgi/wsgi.html).
Pour l'exemple de code suivant, vous avez besoin de la dépendance suivante :
```
pip install opentelemetry-instrumentation-flask
```
Vous devez initialiser le OpenTelemetry SDK et enregistrer le global TracerProvider avant d'ajouter des instrumentations pour votre infrastructure d'application. Sans cela, les opérations de traçage le seront`no-ops`. Une fois que vous avez configuré le global`TracerProvider`, vous pouvez utiliser l'instrument pour votre infrastructure d'application. L'exemple suivant illustre une application Flask.
```
from flask import Flask
from opentelemetry import trace
from opentelemetry.instrumentation.flask import FlaskInstrumentor
from opentelemetry.sdk.extension.aws.resource import AwsEc2ResourceDetector
from opentelemetry.sdk.resources import get_aggregated_resources
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor, ConsoleSpanExporter
provider = TracerProvider(resource=get_aggregated_resources(
[
AwsEc2ResourceDetector(),
]))
processor = BatchSpanProcessor(ConsoleSpanExporter())
provider.add_span_processor(processor)
trace.set_tracer_provider(provider)
# Creates a tracer from the global tracer provider
tracer = trace.get_tracer("my.tracer.name")
app = Flask(__name__)
# Instrument the Flask app
FlaskInstrumentor().instrument_app(app)
@app.route('/')
def hello_world():
return 'Hello World!'
if __name__ == '__main__':
app.run()
```
------
## AWS Instrumentation du SDK
------
#### [ With X-Ray SDK ]
Le SDK Python de X-Ray trace la demande du client du AWS SDK en appliquant des correctifs à la bibliothèque. `botocore` Pour plus d'informations, consultez la section [Tracing AWS SDK calls with the X-Ray SDK for Python](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-python-awssdkclients.html). Dans votre application, la `patch_all()` méthode est utilisée pour instrumenter toutes les bibliothèques ou appliquer des correctifs de manière sélective à l'aide de la `botocore` ou `boto3` des bibliothèques utilisant`patch((['botocore']))`. L'une des méthodes choisies instrumente tous les clients Boto3 de votre application et génère un sous-segment pour tout appel effectué à l'aide de ces clients.
------
#### [ With OpenTelemetry SDK ]
Pour l'exemple de code suivant, vous aurez besoin de la dépendance suivante :
```
pip install opentelemetry-instrumentation-botocore
```
Utilisez l'[instrumentation OpenTelemetry Botocore](https://opentelemetry-python-contrib.readthedocs.io/en/latest/instrumentation/botocore/botocore.html) de manière programmatique pour instrumenter tous les clients Boto3 de votre application. L'exemple suivant illustre l'`botocore`instrumentation.
```
import boto3
import opentelemetry.trace as trace
from botocore.exceptions import ClientError
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.resources import get_aggregated_resources
from opentelemetry.sdk.trace.export import (
BatchSpanProcessor,
ConsoleSpanExporter,
)
from opentelemetry.instrumentation.botocore import BotocoreInstrumentor
provider = TracerProvider()
processor = BatchSpanProcessor(ConsoleSpanExporter())
provider.add_span_processor(processor)
trace.set_tracer_provider(provider)
# Creates a tracer from the global tracer provider
tracer = trace.get_tracer("my.tracer.name")
# Instrument BotoCore
BotocoreInstrumentor().instrument()
# Initialize S3 client
s3 = boto3.client("s3", region_name="us-east-1")
# Your bucket name
bucket_name = "my-example-bucket"
# Get bucket location (as an example of describing it)
try:
response = s3.get_bucket_location(Bucket=bucket_name)
region = response.get("LocationConstraint") or "us-east-1"
print(f"Bucket '{bucket_name}' is in region: {region}")
# Optionally, get bucket's creation date via list_buckets
buckets = s3.list_buckets()
for bucket in buckets["Buckets"]:
if bucket["Name"] == bucket_name:
print(f"Bucket created on: {bucket['CreationDate']}")
break
except ClientError as e:
print(f"Failed to describe bucket: {e}")
```
------
## Instrumentation des appels HTTP sortants par le biais de requêtes
------
#### [ With X-Ray SDK ]
Le SDK Python de X-Ray trace les appels HTTP sortants via les requêtes en appliquant des correctifs à la bibliothèque de requêtes. Pour plus d'informations, voir [Suivi des appels aux services Web HTTP en aval à l'aide du SDK X-Ray pour Python](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-python-httpclients.html). Dans votre application, vous pouvez utiliser la `patch_all()` méthode pour instrumenter toutes les bibliothèques ou en appliquant des correctifs sélectifs aux bibliothèques de requêtes en utilisant`patch((['requests']))`. N'importe laquelle des options instrumente la `requests` bibliothèque, générant un sous-segment pour chaque appel effectué via`requests`.
------
#### [ With OpenTelemetry SDK ]
Pour l'exemple de code suivant, vous aurez besoin de la dépendance suivante :
```
pip install opentelemetry-instrumentation-requests
```
Utilisez l'instrumentation OpenTelemetry des requêtes par programmation pour instrumenter la bibliothèque de requêtes afin de générer des traces pour les requêtes HTTP qu'elle effectue dans votre application. Pour plus d'informations, consultez la section [Instrumentation OpenTelemetry des requêtes](https://opentelemetry-python-contrib.readthedocs.io/en/latest/instrumentation/requests/requests.html). L'exemple suivant illustre l'instrumentation de la `requests` bibliothèque.
```
from opentelemetry.instrumentation.requests import RequestsInstrumentor
# Instrument Requests
RequestsInstrumentor().instrument()
...
example_session = requests.Session()
example_session.get(url="https://example.com")
```
Vous pouvez également instrumenter la `urllib3` bibliothèque sous-jacente pour suivre les requêtes HTTP :
```
# pip install opentelemetry-instrumentation-urllib3
from opentelemetry.instrumentation.urllib3 import URLLib3Instrumentor
# Instrument urllib3
URLLib3Instrumentor().instrument()
...
example_session = requests.Session()
example_session.get(url="https://example.com")
```
------
## Support d'instrumentation pour d'autres bibliothèques
Vous trouverez la liste complète des instrumentations de bibliothèque prises en charge pour OpenTelemetry Python sous [Bibliothèques, frameworks, serveurs d'applications pris en charge et JVMs](https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/docs/supported-libraries.md).
Vous pouvez également effectuer une recherche OpenTelemetry dans le registre pour savoir si l'instrumentation est OpenTelemetry compatible. Consultez le [registre](https://opentelemetry.io/ecosystem/registry/) pour commencer la recherche.
## Création manuelle de données de trace
Vous pouvez créer des segments et des sous-segments en utilisant le `xray_recorder` dans votre application Python. Pour plus d'informations, consultez [Instrumentation manuelle du code Python](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-python-middleware.html#xray-sdk-python-middleware-manual). Vous pouvez également ajouter manuellement des annotations et des métadonnées aux données de trace.
**Création de spans avec le SDK OpenTelemetry **
Utilisez l'`start_as_current_span`API pour démarrer un intervalle et configurez-le pour créer des intervalles. Pour des exemples de création de travées, voir [Création de travées](https://opentelemetry.io/docs/languages/python/instrumentation/#creating-spans). Une fois qu'une période est démarrée et qu'elle est dans son étendue actuelle, vous pouvez y ajouter des informations supplémentaires en ajoutant des attributs, des événements, des exceptions, des liens, etc. Tout comme nous avons des segments et des sous-segments dans X-Ray, il existe différents types de travées. OpenTelemetry Seules les plages de `SERVER` type sont converties en segments X-Ray, tandis que les autres sont converties en sous-segments X-Ray.
```
from opentelemetry import trace
from opentelemetry.trace import SpanKind
import time
tracer = trace.get_tracer("my.tracer.name")
# Create a new span to track some work
with tracer.start_as_current_span("parent", kind=SpanKind.SERVER) as parent_span:
time.sleep(1)
# Create a nested span to track nested work
with tracer.start_as_current_span("child", kind=SpanKind.CLIENT) as child_span:
time.sleep(2)
# the nested span is closed when it's out of scope
# Now the parent span is the current span again
time.sleep(1)
# This span is also closed when it goes out of scope
```
**Ajouter des annotations et des métadonnées aux traces avec OpenTelemetry le SDK**
Le SDK X-Ray Python fournit une solution séparée APIs permettant d'ajouter `put_metadata` des annotations et des métadonnées à une trace. `put_annotation` Dans le OpenTelemetry SDK, les annotations et les métadonnées sont simplement des attributs sur une plage, ajoutés via l'`set_attribute`API.
Les attributs Span que vous souhaitez utiliser comme annotations sur une trace sont ajoutés sous la clé réservée `aws.xray.annotations` dont la valeur est une liste de paires clé-valeur d'annotations. Tous les autres attributs span deviennent des métadonnées sur le segment ou le sous-segment converti.
De plus, si vous utilisez le collecteur ADOT, vous pouvez configurer les attributs de span à convertir en annotations X-Ray en les spécifiant `indexed_attributes` dans la configuration du collecteur.
L'exemple ci-dessous montre comment ajouter des annotations et des métadonnées à une trace à l'aide du OpenTelemetry SDK.
```
with tracer.start_as_current_span("parent", kind=SpanKind.SERVER) as parent_span:
parent_span.set_attribute("TransactionId", "qwerty12345")
parent_span.set_attribute("AccountId", "1234567890")
# This will convert the TransactionId and AccountId to be searchable X-Ray annotations
parent_span.set_attribute("aws.xray.annotations", ["TransactionId", "AccountId"])
with tracer.start_as_current_span("child", kind=SpanKind.CLIENT) as child_span:
# The MicroTransactionId will be converted to X-Ray metadata for the child subsegment
child_span.set_attribute("MicroTransactionId", "micro12345")
```
## Instrumentation Lambda
Pour surveiller vos fonctions Lambda sur X-Ray, vous avez activé X-Ray et ajouté les autorisations appropriées au rôle d'invocation des fonctions. De plus, si vous suivez les requêtes en aval de votre fonction, vous instrumenterez le code avec le SDK X-Ray Python.
OpenTelemetry Pour X-Ray, il est recommandé d'utiliser la couche AWS Lambda lorsque les [signaux OpenTelemetry d'application](https://docs.aws.amazon.com/lambda/latest/dg/monitoring-application-signals.html) sont désactivés. Cela instrumentera automatiquement votre fonction et générera des intervalles pour l'invocation de la fonction et pour toute demande en aval émanant de votre fonction. Outre le suivi, si vous souhaitez utiliser les signaux d'application pour surveiller l'état de votre fonction, consultez [Activer vos applications sur Lambda](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Application-Signals-Enable-LambdaMain.html).
+ Trouvez l'ARN de couche Lambda requis pour votre fonction dans [AWS Lambda Layer for OpenTelemetry ARNs](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Application-Signals-Enable-LambdaMain.html#Enable-Lambda-Layers) et ajoutez-le.
+ Définissez les variables d'environnement suivantes pour votre fonction.
+ `AWS_LAMBDA_EXEC_WRAPPER=/opt/otel-instrument`— Cela charge l'auto-instrumentation pour la fonction
+ `OTEL_AWS_APPLICATION_SIGNALS_ENABLED=false`— Cela désactivera la surveillance des signaux d'application
**Création manuelle de travées à l'aide de l'instrumentation Lambda**
En outre, vous pouvez générer des intervalles personnalisés au sein de votre fonction pour suivre le travail. Vous pouvez le faire en utilisant uniquement le `opentelemetry-api` package en conjonction avec la couche AWS Lambda pour OpenTelemetry l'instrumentation automatique.
1. Incluez le `opentelemetry-api` en tant que dépendance dans votre fonction
1. L'extrait de code suivant est un exemple permettant de générer des étendues personnalisées
```
from opentelemetry import trace
# Get the tracer (auto‑configured by the AWS Lambda Layer for OpenTelemetry)
tracer = trace.get_tracer(__name__)
def handler(event, context):
# This span is a child of the layer's root span
with tracer.start_as_current_span("my-custom-span") as span:
span.set_attribute("key1", "value1")
span.add_event("custom-event", {"detail": "something happened"})
# Any logic you want to trace
result = some_internal_logic()
return {
"statusCode": 200,
"body": result
}
```