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á. # Configurar o X-Ray SDK para Python **nota** Aviso de SDK/Daemon manutenção do X-Ray — Em 25 de fevereiro de 2026, o AWS X-Ray SDKs/Daemon entrará no modo de manutenção, onde AWS limitará as versões do X-Ray SDK e do Daemon para tratar apenas de problemas de segurança. Para obter mais informações sobre a linha do tempo do suporte, consulte [Cronograma de suporte do X-Ray SDK e do Daemon Support](xray-sdk-daemon-timeline.md). Recomendamos migrar para o. OpenTelemetry Para obter mais informações sobre a migração para OpenTelemetry, consulte [Migrando da instrumentação X-Ray para a instrumentação](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html). OpenTelemetry O X-Ray SDK para Python tem uma classe chamada `xray_recorder`, que fornece o gravador global. Você pode configurar o gravador global para personalizar o middleware que cria segmentos para chamadas HTTP de entrada. **Topics** + [Plug-ins de serviço](#xray-sdk-python-configuration-plugins) + [Regras de amostragem](#xray-sdk-python-configuration-sampling) + [Registro em log](#xray-sdk-python-configuration-logging) + [Configuração do gravador no código](#xray-sdk-python-middleware-configuration-code) + [Configuração do gravador com o Django](#xray-sdk-python-middleware-configuration-django) + [Variáveis de ambiente](#xray-sdk-python-configuration-envvars) ## Plug-ins de serviço Use `plugins` para registrar informações sobre o serviço que hospeda o aplicativo. **Plugins** + Amazon EC2 — `EC2Plugin` adiciona o ID da instância, a zona de disponibilidade e o grupo de CloudWatch registros. + Elastic Beanstalk: o `ElasticBeanstalkPlugin` adiciona o nome do ambiente, o rótulo da versão e o ID de implantação. + Amazon ECS: o `ECSPlugin` adiciona o ID do contêiner. ![\[Segment - Scorekeep overview showing Elastic Beanstalk and EC2 deployment details.\]](http://docs.aws.amazon.com/pt_br/xray/latest/devguide/images/scorekeep-PUTrules-segment-resources-python09.png) Para usar um plug-in, chame `configure` no `xray_recorder`. ``` from aws_xray_sdk.core import xray_recorder from aws_xray_sdk.core import patch_all xray_recorder.configure(service='My app') plugins = ('ElasticBeanstalkPlugin', 'EC2Plugin') xray_recorder.configure(plugins=plugins) patch_all() ``` **nota** Como os `plugins` são passados como uma tupla, inclua uma `,` à direita ao especificar um único plug-in. Por exemplo, `plugins = ('EC2Plugin',)`. Você também pode usar [variáveis de ambiente](#xray-sdk-python-configuration-envvars), que têm precedência sobre valores definidos no código, para configurar o gravador. Configure plug-ins antes de [bibliotecas de patches](xray-sdk-python-patching.md) para gravar chamadas downstream. O SDK também usa as configurações do plug-in para definir o campo `origin` no segmento. Isso indica o tipo de AWS recurso que executa seu aplicativo. Quando você usa vários plug-ins, o SDK usa a seguinte ordem de resolução para determinar a origem: ElasticBeanstalk > EKS > ECS >. EC2 ## Regras de amostragem O SDK usa as regras de amostragem que você define no console do X-Ray para determinar quais solicitações serão registradas. A regra padrão rastreia a primeira solicitação a cada segundo e 5% de todas as solicitações adicionais em todos os serviços que enviam rastreamentos ao X-Ray. [Crie regras adicionais no console do X-Ray](xray-console-sampling.md) para personalizar a quantidade de dados registrados para cada uma dos aplicativos. O SDK aplica regras personalizadas na ordem em que elas estão definidas. Se uma solicitação corresponder a várias regras personalizadas, o SDK aplicará somente a primeira regra. **nota** Se o SDK não conseguir acessar o X-Ray para obter regras de amostragem, ele reverterá para uma regra local padrão da primeira solicitação a cada segundo e 5% de todas as solicitações adicionais por host. Isso pode ocorrer se o host não tiver permissão para chamar a amostragem APIs ou não conseguir se conectar ao daemon X-Ray, que atua como um proxy TCP para chamadas de API feitas pelo SDK. Você também pode configurar o SDK para carregar regras de amostragem de um documento JSON. O SDK pode usar regras locais como backup para casos em que a amostragem do X-Ray não está disponível ou usar exclusivamente regras locais. **Example sampling-rules.json** ``` { "version": 2, "rules": [ { "description": "Player moves.", "host": "*", "http_method": "*", "url_path": "/api/move/*", "fixed_target": 0, "rate": 0.05 } ], "default": { "fixed_target": 1, "rate": 0.1 } } ``` Este exemplo define uma regra personalizada e uma regra padrão. A regra personalizada aplica uma taxa de amostragem de 5% sem um número mínimo de solicitações para rastrear os caminhos em `/api/move/`. A regra padrão rastreia a primeira solicitação a cada segundo e 10% das solicitações adicionais. A desvantagem de definir regras localmente é que o destino fixo é aplicado por instância do gravador de forma independente, em vez de ser gerenciado pelo serviço X-Ray. À medida que você implanta mais hosts, a taxa fixa é multiplicada, dificultando o controle da quantidade de dados registrados. Ativado AWS Lambda, você não pode modificar a taxa de amostragem. Se sua função for chamada por um serviço instrumentado, as chamadas que geraram solicitações que foram amostradas por esse serviço serão registradas pelo Lambda. Se o rastreamento ativo estiver habilitado e nenhum cabeçalho de rastreamento estiver presente, o Lambda tomará a decisão de amostragem. Para configurar as regras de amostragem de backup`xray_recorder.configure`, chame, conforme mostrado no exemplo a seguir, where *rules* é um dicionário de regras ou o caminho absoluto para um arquivo JSON contendo regras de amostragem. ``` xray_recorder.configure(sampling_rules=rules) ``` Para usar somente regras locais, configure o gravador com um `LocalSampler`. ``` from aws_xray_sdk.core.sampling.local.sampler import LocalSampler xray_recorder.configure(sampler=LocalSampler()) ``` Você também pode configurar o gravador global para desabilitar a amostragem e instrumentar todas as solicitações de entrada. **Example main.py: desabilitar a amostragem** ``` xray_recorder.configure(sampling=False) ``` ## Registro em log O SDK usa o módulo `logging` integrado do Python com um nível de registro em log `WARNING` padrão. Obtenha uma referência ao agente de log para a classe `aws_xray_sdk` e chame `setLevel` nela para configurar o nível de log diferente para a biblioteca e o restante de seu aplicativo. **Example app.py: Registrar em log** ``` logging.basicConfig(level='WARNING') logging.getLogger('aws_xray_sdk').setLevel(logging.ERROR) ``` Use logs de depuração para identificar problemas como subsegmentos não fechados ao [gerar subsegmentos manualmente](xray-sdk-python-subsegments.md). ## Configuração do gravador no código Configurações adicionais estão disponíveis no método `configure` no `xray_recorder`. + `context_missing`: defina como `LOG_ERROR` para evitar o lançamento de exceções, caso o código instrumentado tente registrar dados quando nenhum segmento estiver aberto. + `daemon_address`: defina o host e a porta do receptor do daemon do X-Ray. + `service`: defina um nome de serviço para o SDK usar para segmentos. + `plugins`— Registre informações sobre os AWS recursos do seu aplicativo. + `sampling`: defina como `False` para desabilitar a amostragem. + `sampling_rules`: defina o caminho do arquivo JSON que contém suas [regras de amostragem](#xray-sdk-python-configuration-sampling). **Example main.py: desabilitar exceções de contexto ausente** ``` from aws_xray_sdk.core import xray_recorder xray_recorder.configure(context_missing='LOG_ERROR') ``` ## Configuração do gravador com o Django Se você usar a estrutura do Django, poderá usar o arquivo `settings.py` do Django para configurar as opções no gravador global. + `AUTO_INSTRUMENT` (Somente para Django): registre os subsegmentos para operações de renderização de banco de dados e de modelo integrados. + `AWS_XRAY_CONTEXT_MISSING`: defina como `LOG_ERROR` para evitar o lançamento de exceções, caso o código instrumentado tente registrar dados quando nenhum segmento estiver aberto. + `AWS_XRAY_DAEMON_ADDRESS`: defina o host e a porta do receptor do daemon do X-Ray. + `AWS_XRAY_TRACING_NAME`: defina um nome de serviço para o SDK usar para segmentos. + `PLUGINS`— Registre informações sobre os AWS recursos do seu aplicativo. + `SAMPLING`: defina como `False` para desabilitar a amostragem. + `SAMPLING_RULES`: defina o caminho do arquivo JSON que contém suas [regras de amostragem](#xray-sdk-python-configuration-sampling). Para habilitar a configuração do gravador em `settings.py`, adicione o middleware do Django à lista de aplicativos instalados. **Example settings.py: aplicações instalados** ``` INSTALLED_APPS = [ ... 'django.contrib.sessions', 'aws_xray_sdk.ext.django', ] ``` Configurar as configurações disponíveis em um dict chamado `XRAY_RECORDER`. **Example settings.py: aplicações instalados** ``` XRAY_RECORDER = { 'AUTO_INSTRUMENT': True, 'AWS_XRAY_CONTEXT_MISSING': 'LOG_ERROR', 'AWS_XRAY_DAEMON_ADDRESS': '127.0.0.1:5000', 'AWS_XRAY_TRACING_NAME': 'My application', 'PLUGINS': ('ElasticBeanstalkPlugin', 'EC2Plugin', 'ECSPlugin'), 'SAMPLING': False, } ``` ## Variáveis de ambiente É possível usar variáveis de ambiente para configurar o X-Ray SDK para Python. O SDK é compatível com as seguintes variáveis: + `AWS_XRAY_TRACING_NAME`: defina um nome de serviço para o SDK usar para segmentos. Substitui o nome do serviço definido programaticamente. + `AWS_XRAY_SDK_ENABLED`: quando definido como `false`, desabilita o SDK. Por padrão, o SDK está habilitado, a menos que a variável de ambiente esteja definida como falsa. + Quando desabilitado, o gravador global gera automaticamente segmentos e subsegmentos fictícios que não são enviados para o daemon, e a aplicação automática de patches está desabilitada. Os middlewares são gravados como um wrapper pelo gravador global. Toda a geração de segmentos e subsegmentos pelo middleware também se torna segmentos fictícios e subsegmentos fictícios. + Defina o valor de `AWS_XRAY_SDK_ENABLED` por meio da variável de ambiente ou por meio de interação direta com o objeto `global_sdk_config` da biblioteca de `aws_xray_sdk`. As configurações para a variável de ambiente substituem essas interações. + `AWS_XRAY_DAEMON_ADDRESS`: defina o host e a porta do receptor do daemon do X-Ray. Por padrão, o SDK usa `127.0.0.1:2000` para dados de rastreamento (UDP) e para amostragem (TCP). Use essa variável se você tiver configurado o daemon para [escutar em uma porta diferente](xray-daemon-configuration.md) ou se ele estiver sendo executado em um host diferente. **Formato** + **Mesma porta**: `address:port` + **Portas diferentes**: `tcp:address:port udp:address:port` + `AWS_XRAY_CONTEXT_MISSING`: defina como `RUNTIME_ERROR` para lançar exceções, caso o código instrumentado tente registrar dados quando nenhum segmento estiver aberto. **Valores válidos** + `RUNTIME_ERROR`: lance uma exceção de tempo de execução. + `LOG_ERROR`: registre um erro e continue (padrão). + `IGNORE_ERROR`: ignore o erro e continue. Erros relativos a segmentos ou subsegmentos ausentes poderão ocorrer quando você tentar usar um cliente instrumentado no código de inicialização que é executado quando nenhuma solicitação estiver aberta ou em um código que gere um novo thread. As variáveis de ambiente substituem os valores definidos no código.