Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés. # Migrar a OpenTelemetry Python Esta guía le ayuda a migrar las aplicaciones de Python del SDK de X-Ray a la OpenTelemetry instrumentación. Abarca los enfoques de instrumentación automática y manual, con ejemplos de código para escenarios comunes. **Topics** + [Soluciones de instrumentación automática sin código](#zero-code-python) + [Instrumentación de las aplicaciones manualmente](#manual-instrumentation-python) + [Inicialización de la configuración de seguimiento](#manual-instrumentation-python-tracing) + [Seguimiento de solicitudes entrantes](#tracing-incoming-requests-python) + [AWS Instrumentación del SDK](#aws-sdk-instrumentation-python) + [Instrumentación de llamadas a HTTP salientes a través de solicitudes](#http-instrumentation-python) + [Compatibilidad de instrumentación para otras bibliotecas](#xray-migration-libraries-python) + [Creación manual de datos de rastros](#manual-trace-creation-python) + [Instrumentación de Lambda](#lambda-instrumentation-python) ## Soluciones de instrumentación automática sin código Con el SDK de X-Ray, tenías que modificar el código de tu aplicación para rastrear las solicitudes. OpenTelemetry ofrece soluciones de autoinstrumentación sin código para rastrear las solicitudes. Con OpenTelemetry, tiene la opción de utilizar soluciones de autoinstrumentación sin código para rastrear las solicitudes. **Código cero con instrumentaciones automáticas basadas OpenTelemetry** 1. Uso de la AWS distribución para la instrumentación automática OpenTelemetry (ADOT) para Python: para obtener información sobre la instrumentación automática para aplicaciones de Python, [consulte Seguimiento y métricas con la distribución para la AWS instrumentación](https://aws-otel.github.io/docs/getting-started/python-sdk/auto-instr) automática de Python. OpenTelemetry (Opcional) También puede habilitar CloudWatch Application Signals al instrumentar automáticamente sus aplicaciones AWS con la instrumentación automática de ADOT Python para monitorear el estado actual de las aplicaciones y realizar un seguimiento del rendimiento de las aplicaciones a largo plazo en comparación con sus objetivos comerciales. Application Signals le proporciona una visión unificada y centrada en las aplicaciones de sus aplicaciones, servicios y dependencias y lo ayuda a supervisar y evaluar el estado de las aplicaciones. 1. [Uso de la instrumentación automática de código cero de OpenTelemetry Python: para la instrumentación automática con Python OpenTelemetry , consulte Instrumentación de código cero de Python.](https://opentelemetry.io/docs/zero-code/python/) ## Instrumentación de las aplicaciones manualmente Puede instrumentar las aplicaciones manualmente mediante el comando `pip`. ------ #### [ 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 ``` ------ ## Inicialización de la configuración de seguimiento ------ #### [ With X-Ray SDK ] En X-Ray, el `xray_recorder` global se inicializa y se usa para generar segmentos y subsegmentos. ------ #### [ With OpenTelemetry SDK ] **nota** El muestreo remoto de X-Ray no está disponible actualmente para configurarlo para OpenTelemetry Python. Sin embargo, la compatibilidad para el muestreo remoto de X-Ray está disponible actualmente a través de la instrumentación automática de ADOT para Python. En OpenTelemetry, necesita inicializar un global`TracerProvider`. Con este `TracerProvider`, puede adquirir un [Rastreador](https://opentelemetry.io/docs/concepts/signals/traces/#tracer) que puede usar para generar intervalos en cualquier parte de la aplicación. Se recomienda que configure los siguientes componentes: + `OTLPSpanExporter`— Necesario para exportar las trazas al CloudWatch OpenTelemetry agente/recopilador + Un propagador de AWS rayos X: necesario para propagar el contexto de rastreo a AWS los servicios que están integrados con 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 ``` ------ **Con la instrumentación automática de ADOT para Python** Puede utilizar la instrumentación automática de ADOT para Python para configurar automáticamente OpenTelemetry sus aplicaciones de Python. Al utilizar la instrumentación automática de ADOT, no es necesario realizar cambios manuales en el código para rastrear las solicitudes entrantes ni para rastrear bibliotecas como el AWS SDK o los clientes HTTP. Para obtener más información, consulte [Seguimiento y métricas con la AWS distribución para la instrumentación automática de OpenTelemetry Python](https://aws-otel.github.io/docs/getting-started/python-sdk/auto-instr). La instrumentación automática de ADOT para Python admite: + Muestreo remoto de X-Ray a través de la variable de entorno `export OTEL_TRACES_SAMPLER=xray` + Propagación de contexto de rastros de X-Ray (habilitada de forma predeterminada) + Detección de recursos (la detección de recursos para los entornos de Amazon EC2, Amazon ECS y Amazon EKS está habilitada de forma predeterminada) + Las instrumentaciones de biblioteca automáticas para todas las instrumentaciones compatibles OpenTelemetry están habilitadas de forma predeterminada. Puede desactivarlas de forma selectiva a través de la variable de entorno `OTEL_PYTHON_DISABLED_INSTRUMENTATIONS ` (todas están habilitadas de forma predeterminada) + Creación manual de intervalos **Desde complementos del servicio de X-Ray hasta proveedores de OpenTelemetry AWS recursos** El SDK de X-Ray incluye complementos que puede agregar al `xray_recorder` para capturar la información específica de la plataforma desde el servicio alojado, como Amazon EC2, Amazon ECS y Elastic Beanstalk. Es similar a los proveedores de recursos en el sentido de OpenTelemetry que captura la información como atributos de los recursos. Hay varios proveedores de recursos disponibles para diferentes AWS plataformas. + Comience por instalar el paquete AWS de extensión, `pip install opentelemetry-sdk-extension-aws` + Configure el detector de recursos deseado. El siguiente ejemplo muestra cómo configurar el proveedor de recursos de Amazon EC2 en el 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) ``` ## Seguimiento de solicitudes entrantes ------ #### [ With X-Ray SDK ] El X-Ray Python SDK admite marcos de aplicaciones como Django, Flask y Bottle para rastrear las solicitudes entrantes de las aplicaciones de Python que se ejecutan en ellos. Esto se hace agregando `XRayMiddleware` a la aplicación para cada marco. ------ #### [ With OpenTelemetry SDK ] OpenTelemetry proporciona instrumentaciones para [Django](https://opentelemetry-python-contrib.readthedocs.io/en/latest/instrumentation/django/django.html) y [Flask](https://opentelemetry-python-contrib.readthedocs.io/en/latest/instrumentation/flask/flask.html) a través de las bibliotecas de instrumentación específicas. [No hay instrumentación para Bottle disponible en OpenTelemetry, pero aún se pueden rastrear las aplicaciones utilizando la instrumentación WSGI. OpenTelemetry ](https://opentelemetry-python-contrib.readthedocs.io/en/latest/instrumentation/wsgi/wsgi.html) Para el ejemplo de código siguiente, necesita la siguiente dependencia: ``` pip install opentelemetry-instrumentation-flask ``` Debe inicializar el OpenTelemetry SDK y registrar el global TracerProvider antes de añadir instrumentaciones al marco de su aplicación. Sin él, las operaciones de rastreo serán `no-ops`. Una vez que haya configurado el `TracerProvider` global, puede usar el instrumentor para el marco de la aplicación. El ejemplo siguiente muestra una aplicación de 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 Instrumentación del SDK ------ #### [ With X-Ray SDK ] El SDK de Python de X-Ray rastrea la solicitud del cliente del AWS SDK parcheando la `botocore` biblioteca. Para obtener más información, consulta [Rastrear las llamadas AWS del SDK con el SDK de X-Ray para Python](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-python-awssdkclients.html). En la aplicación, el método `patch_all()` se utiliza para instrumentar todas las bibliotecas o aplicar parches de forma selectiva mediante las bibliotecas de `botocore` o `boto3` que utilizan `patch((['botocore']))`. Cualquiera de los métodos elegidos instrumenta todos los clientes de Boto3 de la aplicación y genera un subsegmento para cualquier llamada realizada con estos clientes. ------ #### [ With OpenTelemetry SDK ] Para el ejemplo de código siguiente, necesitará la siguiente dependencia: ``` pip install opentelemetry-instrumentation-botocore ``` Utilice la [instrumentación de OpenTelemetry Botocore mediante programación para instrumentar](https://opentelemetry-python-contrib.readthedocs.io/en/latest/instrumentation/botocore/botocore.html) todos los clientes de Boto3 de su aplicación. En el ejemplo siguiente se muestra la instrumentación de `botocore`. ``` 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}") ``` ------ ## Instrumentación de llamadas a HTTP salientes a través de solicitudes ------ #### [ With X-Ray SDK ] El X-Ray Python SDK rastrea las llamadas a HTTP salientes a través de solicitudes parcheando la biblioteca de solicitudes. Para obtener más información, consulte [Rastreo de llamadas a servicios web HTTP posteriores con el SDK de X-Ray para Python](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-python-httpclients.html). En la aplicación, puede usar el método `patch_all()` para instrumentar todas las bibliotecas o aplicar parches de forma selectiva a las bibliotecas de solicitudes mediante `patch((['requests']))`. Cualquiera de las opciones instrumenta la biblioteca de `requests` y genera un subsegmento para cualquier llamada realizada a través de `requests`. ------ #### [ With OpenTelemetry SDK ] Para el ejemplo de código siguiente, necesitará la siguiente dependencia: ``` pip install opentelemetry-instrumentation-requests ``` Utilice la instrumentación de OpenTelemetry solicitudes mediante programación para instrumentar la biblioteca de solicitudes a fin de generar un seguimiento de las solicitudes HTTP que realice en su aplicación. [Para obtener más información, consulta OpenTelemetry la sección Instrumentación de solicitudes.](https://opentelemetry-python-contrib.readthedocs.io/en/latest/instrumentation/requests/requests.html) En el ejemplo siguiente se muestra la instrumentación de la biblioteca de `requests`. ``` from opentelemetry.instrumentation.requests import RequestsInstrumentor # Instrument Requests RequestsInstrumentor().instrument() ... example_session = requests.Session() example_session.get(url="https://example.com") ``` Como opción alternativa, también puede instrumentar la biblioteca de `urllib3` subyacente para rastrear las solicitudes 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") ``` ------ ## Compatibilidad de instrumentación para otras bibliotecas Puede encontrar la lista completa de instrumentaciones de biblioteca compatibles para OpenTelemetry Python en [Bibliotecas, marcos, servidores de aplicaciones](https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/docs/supported-libraries.md) y. JVMs Como alternativa, puedes buscar en el OpenTelemetry Registro para averiguar si es OpenTelemetry compatible con la instrumentación. Consulte [Registro](https://opentelemetry.io/ecosystem/registry/) para empezar a buscar. ## Creación manual de datos de rastros Puede crear segmentos y subsegmentos mediante `xray_recorder` en la aplicación de Python. Para obtener más información, consulte [Instrumentación manual del código de Python](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-python-middleware.html#xray-sdk-python-middleware-manual). También puede agregar anotaciones y metadatos de forma manual a los datos de rastros. **Cómo crear intervalos con OpenTelemetry el SDK** Use la API de `start_as_current_span` para iniciar un intervalo y configúrelo para crear intervalos. Para ver ejemplos sobre la creación de intervalos, consulte [Creación de intervalos](https://opentelemetry.io/docs/languages/python/instrumentation/#creating-spans). Una vez que se inicia un intervalo y se encuentra en el ámbito actual, puede agregarle más información agregando atributos, eventos, excepciones, enlaces, etc. Al igual que tenemos segmentos y subsegmentos en X-Ray, hay diferentes tipos de intervalos. OpenTelemetry Solo los intervalos del tipo `SERVER` se convierten en segmentos de X-Ray, mientras que otros se convierten en subsegmentos de 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 ``` **Añadir anotaciones y metadatos a las trazas con el SDK OpenTelemetry ** El SDK de Python de X-Ray proporciona anotaciones `put_annotation` y metadatos independientes APIs `put_metadata` para añadir anotaciones y metadatos a una traza. En el OpenTelemetry SDK, las anotaciones y los metadatos son simplemente atributos de un intervalo que se agregan a través de la `set_attribute` API. Los atributos de intervalo que desee que sean anotaciones en un rastro se agregan en la clave reservada, `aws.xray.annotations` cuyo valor es una lista de pares de anotaciones clave-valor. Todos los demás atributos del intervalo se convierten en metadatos del segmento o subsegmento convertido. Además, si utiliza el recopilador de ADOT, puede configurar qué atributos de intervalo deben convertirse en anotaciones de X-Ray especificando `indexed_attributes` en la configuración del recopilador. En el siguiente ejemplo, se muestra cómo añadir anotaciones y metadatos a una traza mediante OpenTelemetry el 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") ``` ## Instrumentación de Lambda Para supervisar las funciones de lambda en X-Ray, habilite X-Ray y agregue los permisos adecuados al rol de invocación de la función. Además, si está rastreando las solicitudes posteriores de la función, estaría instrumentando el código con X-Ray Python SDK. Con OpenTelemetry X-Ray, se recomienda utilizar la capa AWS Lambda OpenTelemetry con [las señales de aplicación desactivadas](https://docs.aws.amazon.com/lambda/latest/dg/monitoring-application-signals.html). Esto instrumentará automáticamente la función y generará intervalos para la invocación de la función y cualquier solicitud posterior de la función. Además del rastreo, si está interesado en usar Application Signals para supervisar el estado de su función, consulte [Habilitación de sus aplicaciones en Lambda](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Application-Signals-Enable-LambdaMain.html). + Busque el ARN de la capa Lambda necesario para su función en [AWS Lambda](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Application-Signals-Enable-LambdaMain.html#Enable-Lambda-Layers) Layer for y agréguelo. OpenTelemetry ARNs + Establezca las siguientes variables de entorno para la función. + `AWS_LAMBDA_EXEC_WRAPPER=/opt/otel-instrument`: esto carga la instrumentación automática de la función + `OTEL_AWS_APPLICATION_SIGNALS_ENABLED=false`: esto desactivará la supervisión de Application Signals **Creación manual de intervalos con instrumentación de Lambda** Además, puede generar intervalos personalizados dentro de la función para realizar un seguimiento del trabajo. Puede hacerlo utilizando solo el `opentelemetry-api` paquete junto con la capa AWS Lambda para OpenTelemetry la autoinstrumentación. 1. Incluir la `opentelemetry-api` como una dependencia en la función 1. El siguiente fragmento de código es un ejemplo para generar intervalos personalizados ``` 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 } ```