As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá. # Migrar para Python OpenTelemetry Este guia ajuda você a migrar aplicativos Python do X-Ray SDK OpenTelemetry para a instrumentação. Ele abrange abordagens de instrumentação automática e manual, com exemplos de código para cenários comuns. **Topics** + [Soluções de instrumentação automática de código zero](#zero-code-python) + [Instrumente suas aplicações manualmente](#manual-instrumentation-python) + [Inicialização da configuração de rastreamento](#manual-instrumentation-python-tracing) + [Rastreamento de solicitações de entrada](#tracing-incoming-requests-python) + [AWS Instrumentação do SDK](#aws-sdk-instrumentation-python) + [Instrumentar chamadas HTTP de saída por meio de solicitações](#http-instrumentation-python) + [Suporte de instrumentação para outras bibliotecas](#xray-migration-libraries-python) + [Criar dados de rastreamento manualmente](#manual-trace-creation-python) + [Instrumentação do Lambda](#lambda-instrumentation-python) ## Soluções de instrumentação automática de código zero Com o X-Ray SDK, você precisava modificar o código do aplicativo para rastrear solicitações. OpenTelemetry oferece soluções de instrumentação automática de código zero para rastrear solicitações. Com OpenTelemetry, você tem a opção de usar soluções de instrumentação automática de código zero para rastrear solicitações. **Código zero com OpenTelemetry instrumentações automáticas baseadas** 1. [Usando a AWS Distro for OpenTelemetry (ADOT) Auto-instrumentation para Python — Para instrumentação automática para aplicativos Python, consulte Rastreamento e métricas com a Distro for Python Auto-Instrumentation. AWS OpenTelemetry ](https://aws-otel.github.io/docs/getting-started/python-sdk/auto-instr) (Opcional) Você também pode ativar o CloudWatch Application Signals ao instrumentar automaticamente seus aplicativos AWS com a instrumentação automática ADOT Python para monitorar a integridade atual do aplicativo e acompanhar o desempenho de longo prazo do aplicativo em relação aos seus objetivos de negócios. O Application Signals fornece uma visualização unificada e centrada em aplicativos para aplicativos, serviços e dependências, além de ajudar você a monitorar e realizar a triagem da integridade do aplicativo. 1. [Usando a instrumentação automática de código zero do OpenTelemetry Python — Para instrumentação automática com o Python, consulte Instrumentação de código zero do Python. OpenTelemetry ](https://opentelemetry.io/docs/zero-code/python/) ## Instrumente suas aplicações manualmente Você pode instrumentar suas aplicações de forma manual com o 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 ``` ------ ## Inicialização da configuração de rastreamento ------ #### [ With X-Ray SDK ] No X-Ray, o `xray_recorder` global é inicializado e usado para gerar segmentos e subsegmentos. ------ #### [ With OpenTelemetry SDK ] **nota** No momento, o X-Ray Remote Sampling não está disponível para ser configurado para OpenTelemetry Python. No entanto, o suporte para a amostragem remota do X-Ray está atualmente disponível por meio da instrumentação automática do ADOT para Python. Em OpenTelemetry, você precisa inicializar um global`TracerProvider`. Ao usar este `TracerProvider`, é possível adquirir um [Rastreador](https://opentelemetry.io/docs/concepts/signals/traces/#tracer) que pode ser usado para gerar extensões em qualquer lugar da sua aplicação. É recomendável configurar os seguintes componentes: + `OTLPSpanExporter`— Necessário para exportar traços para o CloudWatch OpenTelemetry Agente/Coletor + Um propagador de AWS raio-X — necessário para propagar o contexto de rastreamento para AWS serviços integrados ao 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 ``` ------ **Com instrumentação automática do ADOT para Python** Você pode usar a instrumentação automática ADOT para Python para configurar OpenTelemetry automaticamente seus aplicativos Python. Ao usar a instrumentação automática ADOT, você não precisa fazer alterações manuais no código para rastrear solicitações recebidas ou rastrear bibliotecas, como os AWS clientes SDK ou HTTP. Para obter mais informações, consulte [Rastreamento e métricas com a AWS distro for Python OpenTelemetry ](https://aws-otel.github.io/docs/getting-started/python-sdk/auto-instr) Auto-Instrumentation. A instrumentação automática do ADOT para Python é compatível com: + Amostragem remota do X-Ray por meio de variável de ambiente `export OTEL_TRACES_SAMPLER=xray` + Propagação do contexto de rastreamento do X-Ray (habilitada por padrão) + Detecção de recursos (a detecção de recursos para ambientes Amazon EC2, Amazon ECS e Amazon EKS é habilitada por padrão) + As instrumentações automáticas da biblioteca para todas as OpenTelemetry instrumentações suportadas estão habilitadas por padrão. Você pode desativá-las seletivamente por meio da variável de ambiente `OTEL_PYTHON_DISABLED_INSTRUMENTATIONS `(todas são habilitadas por padrão) + Criação manual de expansões **De plug-ins de serviço X-Ray a provedores de OpenTelemetry AWS recursos** O SDK do X-Ray contém plug-ins que podem ser adicionados ao `xray_recorder` para capturar as informações específicas da plataforma do serviço hospedado, como Amazon EC2, Amazon ECS e Elastic Beanstalk. É semelhante aos provedores de recursos, pois captura OpenTelemetry as informações como atributos de recursos. Há vários provedores de recursos disponíveis para diferentes AWS plataformas. + Comece instalando o pacote AWS de extensão, `pip install opentelemetry-sdk-extension-aws` + Configure o detector de recursos desejado. O exemplo a seguir mostra como configurar o provedor de recursos do Amazon EC2 no 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) ``` ## Rastreamento de solicitações de entrada ------ #### [ With X-Ray SDK ] O SDK Python do X-Ray é compatível com estruturas de aplicações como Django, Flask e Bottle no rastreamento de solicitações recebidas de aplicações Python executadas nelas. Para fazer isso, adicione `XRayMiddleware` à aplicação de cada estrutura. ------ #### [ With OpenTelemetry SDK ] OpenTelemetry fornece instrumentações para [Django](https://opentelemetry-python-contrib.readthedocs.io/en/latest/instrumentation/django/django.html) e [Flask](https://opentelemetry-python-contrib.readthedocs.io/en/latest/instrumentation/flask/flask.html) por meio de bibliotecas de instrumentação específicas. [Não há instrumentação para Bottle disponível em OpenTelemetry, as aplicações ainda podem ser rastreadas usando a instrumentação WSGI. OpenTelemetry ](https://opentelemetry-python-contrib.readthedocs.io/en/latest/instrumentation/wsgi/wsgi.html) Para o exemplo de código a seguir, você precisa da seguinte dependência: ``` pip install opentelemetry-instrumentation-flask ``` Você deve inicializar o OpenTelemetry SDK e registrar o global TracerProvider antes de adicionar instrumentações à estrutura do seu aplicativo. Sem isso, as operações de rastreamento serão `no-ops`. Após configurar o `TracerProvider` global, você pode usar o instrumentor para sua estrutura de aplicações. O exemplo a seguir demonstra um aplicativo 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 Instrumentação do SDK ------ #### [ With X-Ray SDK ] O X-Ray Python SDK rastreia a solicitação do cliente AWS SDK aplicando patches na biblioteca. `botocore` Para obter mais informações, consulte [Rastreando chamadas do AWS SDK com o X-Ray SDK para Python](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-python-awssdkclients.html). Na sua aplicação, o método `patch_all()` é usado para instrumentar todas as bibliotecas ou corrigir seletivamente usando as bibliotecas `botocore` ou `boto3` com `patch((['botocore']))`. Qualquer um dos métodos escolhidos instrumenta todos os clientes do Boto3 na sua aplicação e gera um subsegmento para qualquer chamada feita usando esses clientes. ------ #### [ With OpenTelemetry SDK ] Para o exemplo de código a seguir, você precisará da seguinte dependência: ``` pip install opentelemetry-instrumentation-botocore ``` Use a instrumentação [OpenTelemetry Botocore programaticamente para instrumentar](https://opentelemetry-python-contrib.readthedocs.io/en/latest/instrumentation/botocore/botocore.html) todos os clientes do Boto3 em seu aplicativo. Os exemplos a seguir demonstram a instrumentação do `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}") ``` ------ ## Instrumentar chamadas HTTP de saída por meio de solicitações ------ #### [ With X-Ray SDK ] O X-Ray Python SDK rastreia chamadas HTTP de saída por meio de solicitações corrigindo a biblioteca de solicitações. Para obter mais informações, consulte [ Rastrear chamadas para serviços web HTTP downstream usando o SDK do X-Ray para Python](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-python-httpclients.html). Na sua aplicação, você pode usar o método `patch_all()` para instrumentar todas as bibliotecas ou corrigir seletivamente as bibliotecas de solicitações usando `patch((['requests']))`. Qualquer uma das opções instrumenta a biblioteca `requests`, gerando um subsegmento para qualquer chamada feita por meio de `requests`. ------ #### [ With OpenTelemetry SDK ] Para o exemplo de código a seguir, você precisará da seguinte dependência: ``` pip install opentelemetry-instrumentation-requests ``` Use a Instrumentação de OpenTelemetry Solicitações programaticamente para instrumentar a biblioteca de solicitações para gerar rastreamentos para solicitações HTTP feitas por ela em seu aplicativo. Para obter mais informações, consulte [OpenTelemetry solicitações de instrumentação](https://opentelemetry-python-contrib.readthedocs.io/en/latest/instrumentation/requests/requests.html). O exemplo a seguir demonstra a instrumentação da biblioteca `requests`. ``` from opentelemetry.instrumentation.requests import RequestsInstrumentor # Instrument Requests RequestsInstrumentor().instrument() ... example_session = requests.Session() example_session.get(url="https://example.com") ``` Outra opção é instrumentar a biblioteca `urllib3` subjacente para rastrear solicitações 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") ``` ------ ## Suporte de instrumentação para outras bibliotecas Você pode encontrar a lista completa de instrumentações de biblioteca compatíveis com OpenTelemetry Python em [Bibliotecas, estruturas, servidores](https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/docs/supported-libraries.md) de aplicativos e. JVMs Como alternativa, você pode pesquisar no OpenTelemetry Registro para descobrir se OpenTelemetry suporta instrumentação. Consulte o [Registry](https://opentelemetry.io/ecosystem/registry/) para começar a pesquisar. ## Criar dados de rastreamento manualmente Você pode criar segmentos e subsegmentos usando o `xray_recorder` na sua aplicação Python. Para saber mais, consulte [Instrumentar o código Python manualmente](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-python-middleware.html#xray-sdk-python-middleware-manual). Você também pode adicionar manualmente anotações e metadados aos dados de rastreamento. **Criação de extensões com OpenTelemetry o SDK** Use a `start_as_current_span` API para iniciar uma extensão e configurá-la para criar extensões. Para ver exemplos de criação de extensões, consulte [Criar extensões](https://opentelemetry.io/docs/languages/python/instrumentation/#creating-spans). Depois que um período é iniciado e está no escopo atual, você poderá adicionar mais informações a ele ao acrescentar atributos, eventos, exceções, links e assim por diante. Da mesma forma que temos segmentos e subsegmentos no X-Ray, existem diferentes tipos de extensões. OpenTelemetry Somente os intervalos do tipo `SERVER` são convertidos em segmentos do X-Ray, enquanto outros são convertidos em subsegmentos do 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 ``` **Adicionar anotações e metadados aos rastreamentos com o SDK OpenTelemetry ** O X-Ray Python SDK fornece anotações `put_annotation` e `put_metadata` metadados separados APIs a um rastreamento. No OpenTelemetry SDK, as anotações e os metadados são simplesmente atributos em um intervalo, adicionados por meio da API. `set_attribute` Os atributos de extensão, que você quer que sejam anotações em um rastreamento, são adicionados à chave reservada `aws.xray.annotations` cujo valor é uma lista de pares de anotações de valor-chave. Todos os outros atributos de extensão se tornam metadados no segmento ou no subsegmento convertido. Além disso, se você estiver usando o coletor ADOT, poderá configurar quais atributos de extensão deverão ser convertidos em anotações do X-Ray especificando o `indexed_attributes` na configuração do coletor. O exemplo abaixo demonstra como adicionar anotações e metadados a um rastreamento usando o SDK. OpenTelemetry ``` 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") ``` ## Instrumentação do Lambda Para monitorar suas funções do lambda no X-Ray, habilite o X-Ray e adicione as permissões apropriadas ao perfil de invocação da função. Além disso, se você rastreia solicitações downstream da sua função, está instrumentando o código com o X-Ray Python SDK. Com OpenTelemetry o for X-Ray, é recomendável usar a camada AWS Lambda para OpenTelemetry com os [sinais de aplicativos](https://docs.aws.amazon.com/lambda/latest/dg/monitoring-application-signals.html) desativados. Isso instrumenta automaticamente sua função e gera extensões para a invocação da função e qualquer solicitação downstream da sua função. Além do rastreamento, se você tiver interesse em usar o Application Signals para monitorar a integridade da sua função, consulte [Ativar suas aplicações no Lambda](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Application-Signals-Enable-LambdaMain.html). + Encontre o ARN da camada Lambda necessário para sua função em [AWS Lambda](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Application-Signals-Enable-LambdaMain.html#Enable-Lambda-Layers) Layer for e adicione-o. OpenTelemetry ARNs + Defina as seguintes variáveis de ambiente para sua função. + `AWS_LAMBDA_EXEC_WRAPPER=/opt/otel-instrument`: carrega a instrumentação automática para a função + `OTEL_AWS_APPLICATION_SIGNALS_ENABLED=false`: desabilitará o monitoramento do Application Signals **Criar manualmente extensões com instrumentação do Lambda** Além disso, você pode gerar extensões personalizadas na sua função para monitorar o trabalho. Você pode fazer isso usando somente o `opentelemetry-api` pacote em conjunto com a AWS Lambda Layer OpenTelemetry para instrumentação automática. 1. Inclua a `opentelemetry-api` como uma dependência na sua função 1. O snippet de código a seguir é um exemplo para gerar extensões personalizadas ``` 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 } ```