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á.
# AWS 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 é uma biblioteca para aplicações web do Python que fornece classes e métodos para gerar e enviar dados de rastreamento ao daemon do X-Ray. Os dados de rastreamento incluem informações sobre solicitações HTTP recebidas pelo aplicativo e chamadas que o aplicativo faz para serviços downstream usando o AWS SDK, clientes HTTP ou um conector de banco de dados SQL. Você também pode criar segmentos manualmente e adicionar informações de depuração em anotações e metadados.
Você pode baixar o SDK com o `pip`.
```
$ pip install aws-xray-sdk
```
**nota**
O X-Ray SDK para Python é um projeto de código aberto. Você pode acompanhar o projeto e enviar problemas e pull requests em GitHub: [github. com/aws/aws](https://github.com/aws/aws-xray-sdk-python)- xray-sdk-python
Se você usa o Django ou o Flask, comece [adicionando middleware do SDK ao seu aplicativo](xray-sdk-python-middleware.md) para rastrear solicitações recebidas. O middleware cria um [segmento](xray-concepts.md#xray-concepts-segments) para cada solicitação rastreada e conclui o segmento quando a resposta é enviada. Embora o segmento esteja aberto, você pode usar os métodos do cliente do SDK para adicionar informações ao segmento e criar subsegmentos para rastrear as chamadas subsequentes. O SDK também registra automaticamente exceções que seu aplicativo lança enquanto o segmento está aberto. Para outros aplicativos, você pode [criar segmentos manualmente](xray-sdk-python-middleware.md#xray-sdk-python-middleware-manual).
Para funções do Lambda chamadas por uma aplicação ou um serviço instrumentado, o Lambda lê o [cabeçalho de rastreamento](xray-concepts.md#xray-concepts-tracingheader) e rastreia automaticamente as solicitações amostradas. Para outras funções, você pode [configurar o Lambda](xray-services-lambda.md) para amostrar e rastrear solicitações recebidas. Em ambos os casos, o Lambda cria o segmento e o fornece ao X-Ray SDK.
**nota**
No Lambda, o X-Ray SDK é opcional. Se você não o usar em sua função, mesmo assim o mapa de serviço incluirá um nó para o serviço Lambda e um para cada função do Lambda. Ao adicionar o SDK, você pode instrumentar o código da função para adicionar subsegmentos ao segmento de função registrado pelo Lambda. Consulte [AWS Lambda and AWS X-Ray](xray-services-lambda.md) para obter mais informações.
Consulte [Operador](scorekeep-lambda.md#scorekeep-lambda-worker) para ver um exemplo de função do Python instrumentada no Lambda.
Em seguida, use o X-Ray SDK para Python para instrumentar chamadas subsequentes [aplicando patches às bibliotecas da aplicação](xray-sdk-python-patching.md). O SDK é compatível com as seguintes bibliotecas.
**Bibliotecas com suporte**
+ `[botocore](https://pypi.python.org/pypi/botocore)`, `[boto3](https://pypi.python.org/pypi/boto3)` — AWS SDK para Python (Boto) Clientes de instrumentos.
+ `[pynamodb](https://pypi.python.org/pypi/pynamodb/)`: instrumentar a versão do PynamoDB de clientes do Amazon DynamoDB.
+ `[aiobotocore](https://pypi.python.org/pypi/aiobotocore)`, `[aioboto3](https://pypi.python.org/pypi/aioboto3)`: instrumentar as versões integradas ao [asyncio](https://docs.python.org/3/library/asyncio.html) de clientes do SDK para Python.
+ `[requests](https://pypi.python.org/pypi/requests)`, `[aiohttp](https://pypi.python.org/pypi/aiohttp)`: instrumentar clientes HTTP de nível superior.
+ `[httplib](https://docs.python.org/2/library/httplib.html)`, [https://docs.python.org/3/library/http.client.html](https://docs.python.org/3/library/http.client.html): instrumentar clientes HTTP de nível inferior e as bibliotecas de nível superior que os utilizam.
+ `[sqlite3](https://docs.python.org/3/library/sqlite3.html)`— SQLite Clientes de instrumentos.
+ `[mysql-connector-python](https://pypi.python.org/pypi/mysql-connector-python)`: instrumentar clientes do MySQL.
+ `[pg8000](https://pypi.org/project/pg8000/)`: instrumentar a interface PostgreSQL Pure-Python.
+ `[psycopg2](https://pypi.org/project/psycopg2/)`: instrumentar o adaptador de banco de dados PostgreSQL.
+ `[pymongo](https://pypi.org/project/pymongo/)`: instrumentar clientes do MongoDB.
+ `[pymysql](https://pypi.org/project/PyMySQL/)`— Instrumente clientes baseados em PyMy SQL para MySQL e MariaDB.
Sempre que seu aplicativo faz chamadas para AWS um banco de dados SQL ou outros serviços HTTP, o SDK registra as informações sobre a chamada em um subsegmento. Serviços da AWS e os recursos que você acessa nos serviços aparecem como nós downstream no mapa de rastreamento para ajudá-lo a identificar erros e problemas de limitação em conexões individuais.
Depois que você começar a usar o SDK, personalize o comportamento dele [configurando o gravador e o middleware](xray-sdk-python-configuration.md). Você pode adicionar plug-ins para registrar dados sobre os recursos de computação que executam seu aplicativo, personalizar o comportamento de amostragem, estipulando regras de amostragem, e definir o nível de log para ver mais ou menos informações do SDK nos logs do aplicativo.
Registre informações adicionais sobre as solicitações e o trabalho que o aplicativo faz em [anotações e metadados](xray-sdk-python-segment.md). Anotações são simples pares de chave-valor que são indexados para serem usados com [expressões de filtro](xray-console-filters.md) para que você possa pesquisar rastreamentos que contêm dados específicos. As entradas de metadados são menos restritivas e podem registrar matrizes e objetos inteiros: tudo o que pode ser serializado em JSON.
**Anotações e metadados**
Anotações e metadados são textos arbitrários que você adiciona aos segmentos com o X-Ray SDK. As anotações são indexadas para serem usadas com expressões de filtro. Os metadados não são indexados, mas podem ser visualizados no segmento bruto com o console ou a API do X-Ray. Qualquer pessoa à qual você conceder acesso de leitura ao X-Ray poderá visualizar esses dados.
Quando há uma grande quantidade de clientes instrumentados no código, um único segmento de solicitação pode conter um grande número de subsegmentos, um para cada chamada feita com um cliente instrumentado. Você pode organizar e agrupar subsegmentos integrando chamadas de clientes em [subsegmentos personalizados](xray-sdk-python-subsegments.md). Você pode criar um subsegmento personalizado para uma função inteira ou qualquer seção do código. Você pode, então, gravar metadados e anotações no subsegmento em vez de gravar tudo no segmento pai.
Para documentação de referência para as classes e métodos do SDK, consulte a [Referência de API do AWS X-Ray X-Ray SDK para Python](https://docs.aws.amazon.com/xray-sdk-for-python/latest/reference).
## Requisitos
O X-Ray SDK para Python é compatível com as versões de linguagem e biblioteca a seguir.
+ **Python**: 2.7, 3.4 e mais recente
+ **Django**: 1.10 e mais recente
+ **Flask**: 0.10 e mais recente
+ **aiohttp**: 2.3.0 e mais recente
+ **AWS SDK para Python (Boto)**: 1.4.0 e mais recente
+ **botocore**: 1.5.0 e mais recente
+ **enum**: 0.4.7 e mais recente, para Python versões 3.4.0 e mais antigas
+ **jsonpickle**: 1.0.0 e mais recente
+ **setuptools**: 40.6.3 e mais recente
+ **wrapt**: 1.11.0 e mais recente
## Gerenciamento de dependências
O X-Ray SDK para Python está disponível em `pip`.
+ **Pacote**: `aws-xray-sdk`
Adicione o SDK como uma dependência em seu arquivo `requirements.txt`.
**Example requirements.txt**
```
aws-xray-sdk==2.4.2
boto3==1.4.4
botocore==1.5.55
Django==1.11.3
```
Se você usa o Elastic Beanstalk para implantar a aplicação, todos os pacotes são instalados automaticamente em `requirements.txt`.
# 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.
# Rastrear solicitações de entrada com o middleware do 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
Quando você adiciona o middleware ao aplicativo e configura o nome do segmento, o X-Ray SDK para Python cria um segmento para cada solicitação amostrada. Este segmento inclui tempo, método e disposição da solicitação HTTP. Instrumentação adicional cria subsegmentos sobre esse segmento.
O X-Ray SDK para Python é compatível com o seguinte middleware para instrumentar as solicitações HTTP de entrada:
+ Django
+ Flask
+ Bottle
**nota**
Para AWS Lambda funções, o Lambda cria um segmento para cada solicitação de amostra. Consulte [AWS Lambda and AWS X-Ray](xray-services-lambda.md) para obter mais informações.
Consulte [Operador](scorekeep-lambda.md#scorekeep-lambda-worker) para ver um exemplo de função do Python instrumentada no Lambda.
Para scripts ou aplicativos Python em outros frameworks, você pode [criar segmentos manualmente](#xray-sdk-python-middleware-manual).
Cada segmento tem um nome que identifica a aplicação no mapa de serviços. O segmento pode ser nomeado estaticamente ou você pode configurar o SDK para nomeá-lo dinamicamente com base no cabeçalho do host na solicitação de entrada. A nomeação dinâmica permite agrupar rastreamentos com base no nome de domínio na solicitação e aplicar um nome padrão se o nome não corresponder ao padrão esperado (por exemplo, se o cabeçalho do host for falsificado).
**Solicitações encaminhadas**
Se um balanceador de carga ou outro intermediário encaminhar uma solicitação para o aplicativo, o X-Ray obterá o IP do cliente do cabeçalho `X-Forwarded-For` na solicitação em vez do IP de origem no pacote IP. O IP do cliente registrado para uma solicitação encaminhada pode ser falsificado; portanto, não é digno de confiança.
Quando uma solicitação é encaminhada, o SDK define um campo adicional no segmento para indicar isso. Se o segmento tiver o campo `x_forwarded_for` definido como `true`, isso significa que o IP do cliente foi obtido no cabeçalho `X-Forwarded-For` na solicitação HTTP.
O middleware cria um segmento para cada solicitação de entrada com um bloco `http` contendo as seguintes informações:
+ **Método HTTP**: GET, POST, PUT, DELETE etc.
+ **Endereço do cliente**: o endereço IP do cliente que enviou a solicitação.
+ **Código de resposta**: o código de resposta HTTP da solicitação concluída.
+ **Horário**: a hora de início (quando a solicitação foi recebida) e a hora de término (quando a resposta foi enviada).
+ **Agente do usuário**: o `user-agent` da solicitação.
+ **Tamanho do conteúdo**: o `content-length` da resposta.
**Topics**
+ [Adicionar o middleware a seu aplicativo (Django)](#xray-sdk-python-adding-middleware-django)
+ [Adicionar o middleware a seu aplicativo (Flask)](#xray-sdk-python-adding-middleware-flask)
+ [Adicionar o middleware a seu aplicativo (Bottle)](#xray-sdk-python-adding-middleware-bottle)
+ [Instrumentar código Python manualmente](#xray-sdk-python-middleware-manual)
+ [Configurar uma estratégia de nomeação de segmentos](#xray-sdk-python-middleware-naming)
## Adicionar o middleware a seu aplicativo (Django)
Adicione o middleware à lista de `MIDDLEWARE` em seu arquivo `settings.py`. O middleware do X-Ray deve ser a primeira linha em seu arquivo `settings.py` para garantir que as solicitações com falha em outro middleware sejam gravadas.
**Example settings.py: middleware do X-Ray SDK para Python**
```
MIDDLEWARE = [
'aws_xray_sdk.ext.django.middleware.XRayMiddleware',
'django.middleware.security.SecurityMiddleware',
'django.contrib.sessions.middleware.SessionMiddleware',
'django.middleware.common.CommonMiddleware',
'django.middleware.csrf.CsrfViewMiddleware',
'django.contrib.auth.middleware.AuthenticationMiddleware',
'django.contrib.messages.middleware.MessageMiddleware',
'django.middleware.clickjacking.XFrameOptionsMiddleware'
]
```
Adicione a aplicação Django do X-Ray SDK à lista `INSTALLED_APPS` em seu arquivo `settings.py`. Isso permitirá que o gravador do X-Ray seja configurado durante a inicialização da aplicação.
**Example settings.py: aplicação Django do X-Ray SDK para Python**
```
INSTALLED_APPS = [
'aws_xray_sdk.ext.django',
'django.contrib.admin',
'django.contrib.auth',
'django.contrib.contenttypes',
'django.contrib.sessions',
'django.contrib.messages',
'django.contrib.staticfiles',
]
```
Configure um nome de segmento em seu [arquivo `settings.py`](xray-sdk-python-configuration.md#xray-sdk-python-middleware-configuration-django).
**Example settings.py: nome do segmento**
```
XRAY_RECORDER = {
'AWS_XRAY_TRACING_NAME': 'My application',
'PLUGINS': ('EC2Plugin',),
}
```
Isso instrui o gravador do X-Ray a rastrear solicitações atendidas pela aplicação Django com a taxa de amostragem padrão. Você pode [configurar o gravador com seu arquivo de configurações do Django](xray-sdk-python-configuration.md#xray-sdk-python-middleware-configuration-django) para aplicar regras de amostragem personalizadas ou alterar outras configurações.
**nota**
Como os `plugins` são passados como uma tupla, inclua uma `,` à direita ao especificar um único plug-in. Por exemplo, `plugins = ('EC2Plugin',)`.
## Adicionar o middleware a seu aplicativo (Flask)
Para instrumentar seu aplicativo Flask, primeiro configure um nome de segmento no `xray_recorder`. Em seguida, use a função `XRayMiddleware` para corrigir seu aplicativo Flask no código.
**Example app.py**
```
from aws_xray_sdk.core import xray_recorder
from aws_xray_sdk.ext.flask.middleware import XRayMiddleware
app = Flask(__name__)
xray_recorder.configure(service='My application')
XRayMiddleware(app, xray_recorder)
```
Isso instrui o gravador do X-Ray a rastrear solicitações atendidas pela aplicação Flask com a taxa de amostragem padrão. Você pode [configurar o gravador em código](xray-sdk-python-configuration.md#xray-sdk-python-middleware-configuration-code) para aplicar regras de amostragem personalizadas ou alterar outras configurações.
## Adicionar o middleware a seu aplicativo (Bottle)
Para instrumentar seu aplicativo Bottle, primeiro configure um nome de segmento no `xray_recorder`. Depois, use a função `XRayMiddleware` para corrigir seu aplicativo Bottle no código.
**Example app.py**
```
from aws_xray_sdk.core import xray_recorder
from aws_xray_sdk.ext.bottle.middleware import XRayMiddleware
app = Bottle()
xray_recorder.configure(service='fallback_name', dynamic_naming='My application')
app.install(XRayMiddleware(xray_recorder))
```
Isso instrui o gravador do X-Ray a rastrear solicitações atendidas pela aplicação Bottle com a taxa de amostragem padrão. Você pode [configurar o gravador em código](xray-sdk-python-configuration.md#xray-sdk-python-middleware-configuration-code) para aplicar regras de amostragem personalizadas ou alterar outras configurações.
## Instrumentar código Python manualmente
Se você não usar o Django ou o Flask, pode criar segmentos manualmente. Você pode criar um segmento para cada solicitação recebida ou criar segmentos em torno de clientes HTTP ou AWS SDK corrigidos para fornecer contexto para que o gravador adicione subsegmentos.
**Example main.py: instrumentação manual**
```
from aws_xray_sdk.core import xray_recorder
# Start a segment
segment = xray_recorder.begin_segment('segment_name')
# Start a subsegment
subsegment = xray_recorder.begin_subsegment('subsegment_name')
# Add metadata and annotations
segment.put_metadata('key', dict, 'namespace')
subsegment.put_annotation('key', 'value')
# Close the subsegment and segment
xray_recorder.end_subsegment()
xray_recorder.end_segment()
```
## Configurar uma estratégia de nomeação de segmentos
AWS X-Ray usa um *nome de serviço* para identificar seu aplicativo e diferenciá-lo dos outros aplicativos, bancos de dados APIs, AWS recursos externos e que seu aplicativo usa. Quando o X-Ray SDK gera segmentos para solicitações recebidas, ele registra o nome do serviço do aplicativo no [campo de nome](xray-api-segmentdocuments.md#api-segmentdocuments-fields) do segmento.
O X-Ray SDK pode nomear segmentos com o nome do host no cabeçalho da solicitação HTTP. No entanto, esse cabeçalho pode ser falsificado, o que pode resultar em nós inesperados no mapa de serviço. Para evitar que o SDK nomeie segmentos incorretamente devido a solicitações com cabeçalhos de host falsificados, você deve especificar um nome padrão para as solicitações recebidas.
Se o aplicativo atende a solicitações para vários domínios, você pode configurar o SDK para usar uma estratégia de nomeação dinâmica para refletir isso nos nomes dos segmentos. Uma estratégia de nomeação dinâmica permite que o SDK use o nome do host para solicitações que correspondam a um padrão esperado e aplique o nome padrão às solicitações que não correspondem.
Por exemplo, você pode ter uma único aplicativo para atender a solicitações para três subdomínios: `www.example.com`, `api.example.com` e `static.example.com`. Você pode usar uma estratégia de nomeação dinâmica com o padrão `*.example.com` a fim de identificar segmentos para cada subdomínio com um nome diferente, o que resulta em três nós de serviço no mapa de serviços. Se a aplicação receber solicitações com um nome de host que não corresponda ao padrão, você verá um quarto nó no mapa de serviços com um nome alternativo especificado por você.
Para usar o mesmo nome para todos os segmentos de solicitação, especifique o nome da aplicação ao configurar o gravador, conforme mostrado nas [seções anteriores](#xray-sdk-python-adding-middleware-django).
Uma estratégia de nomeação dinâmica define um padrão com o qual os nomes de host devem corresponder e um nome padrão a ser usado se o nome do host na solicitação HTTP não corresponder ao padrão. Para nomear segmentos dinamicamente no Django, adicione a configuração `DYNAMIC_NAMING` a seu arquivo [settings.py](xray-sdk-python-configuration.md#xray-sdk-python-middleware-configuration-django).
**Example settings.py: nomeação dinâmica**
```
XRAY_RECORDER = {
'AUTO_INSTRUMENT': True,
'AWS_XRAY_TRACING_NAME': 'My application',
'DYNAMIC_NAMING': '*.example.com',
'PLUGINS': ('ElasticBeanstalkPlugin', 'EC2Plugin')
}
```
Você pode usar '\$1' no padrão para fazer a correspondência com qualquer string ou '?' para um caractere único. Para o Flask, [configure o gravador no código](xray-sdk-python-configuration.md#xray-sdk-python-middleware-configuration-code).
**Example main.py: nome do segmento**
```
from aws_xray_sdk.core import xray_recorder
xray_recorder.configure(service='My application')
xray_recorder.configure(dynamic_naming='*.example.com')
```
**nota**
Você pode sobrepor o nome do serviço padrão que definiu no código com a [variável de ambiente](xray-sdk-python-configuration.md#xray-sdk-python-configuration-envvars) `AWS_XRAY_TRACING_NAME`.
# Aplicar patches a bibliotecas para instrumentar chamadas downstream
**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
Para instrumentar chamadas subsequentes, use o X-Ray SDK para Python para aplicar patches às bibliotecas usadas pela aplicação. O X-Ray SDK para Python pode corrigir as bibliotecas a seguir.
**Bibliotecas com suporte**
+ `[botocore](https://pypi.python.org/pypi/botocore)`, `[boto3](https://pypi.python.org/pypi/boto3)` — AWS SDK para Python (Boto) Clientes de instrumentos.
+ `[pynamodb](https://pypi.python.org/pypi/pynamodb/)`: instrumentar a versão do PynamoDB de clientes do Amazon DynamoDB.
+ `[aiobotocore](https://pypi.python.org/pypi/aiobotocore)`, `[aioboto3](https://pypi.python.org/pypi/aioboto3)`: instrumentar as versões integradas ao [asyncio](https://docs.python.org/3/library/asyncio.html) de clientes do SDK para Python.
+ `[requests](https://pypi.python.org/pypi/requests)`, `[aiohttp](https://pypi.python.org/pypi/aiohttp)`: instrumentar clientes HTTP de nível superior.
+ `[httplib](https://docs.python.org/2/library/httplib.html)`, [https://docs.python.org/3/library/http.client.html](https://docs.python.org/3/library/http.client.html): instrumentar clientes HTTP de nível inferior e as bibliotecas de nível superior que os utilizam.
+ `[sqlite3](https://docs.python.org/3/library/sqlite3.html)`— SQLite Clientes de instrumentos.
+ `[mysql-connector-python](https://pypi.python.org/pypi/mysql-connector-python)`: instrumentar clientes do MySQL.
+ `[pg8000](https://pypi.org/project/pg8000/)`: instrumentar a interface PostgreSQL Pure-Python.
+ `[psycopg2](https://pypi.org/project/psycopg2/)`: instrumentar o adaptador de banco de dados PostgreSQL.
+ `[pymongo](https://pypi.org/project/pymongo/)`: instrumentar clientes do MongoDB.
+ `[pymysql](https://pypi.org/project/PyMySQL/)`— Instrumente clientes baseados em PyMy SQL para MySQL e MariaDB.
Quando você usa uma biblioteca com patches aplicados, o X-Ray SDK para Python cria um subsegmento para a chamada e grava informações da solicitação e da resposta. Um segmento deve estar disponível para o SDK para criar o subsegmento, no middleware do SDK ou no AWS Lambda.
**nota**
Se você usa SQLAlchemy ORM, pode instrumentar suas consultas SQL importando a versão do SDK das classes SQLAlchemy de sessão e consulta. Consulte [Usar SQLAlchemy ORM](https://github.com/aws/aws-xray-sdk-python/blob/master/README.md#use-sqlalchemy-orm) para obter instruções.
Para aplicar patch a todas as bibliotecas disponíveis, use a função `patch_all` em `aws_xray_sdk.core`. Algumas bibliotecas, como `httplib` e `urllib`, podem precisar habilitar a aplicação de patch dupla chamando `patch_all(double_patch=True)`.
**Example main.py: aplicar patch a todas as bibliotecas compatíveis**
```
import boto3
import botocore
import requests
import sqlite3
from aws_xray_sdk.core import xray_recorder
from aws_xray_sdk.core import patch_all
patch_all()
```
Para aplicar um patch a uma única biblioteca, chame `patch` com uma tupla do nome da biblioteca. Para isso, você precisará fornecer uma única lista de elementos.
**Example main.py: aplicar patch a bibliotecas específicas**
```
import boto3
import botocore
import requests
import mysql-connector-python
from aws_xray_sdk.core import xray_recorder
from aws_xray_sdk.core import patch
libraries = (['botocore'])
patch(libraries)
```
**nota**
Em alguns casos, a chave que você usa para aplicar um patch a uma biblioteca não corresponde ao nome da biblioteca. Algumas chaves servem como aliases para uma ou mais bibliotecas.
`httplib`: `[httplib](https://docs.python.org/2/library/httplib.html)` e [https://docs.python.org/3/library/http.client.html](https://docs.python.org/3/library/http.client.html)
`mysql` – `[mysql-connector-python](https://pypi.python.org/pypi/mysql-connector-python)`
## Rastrear contexto para trabalhos assíncronos
Para bibliotecas integradas `asyncio` ou para [criar subsegmentos para funções assíncronas](xray-sdk-python-subsegments.md), você também deve configurar o X-Ray SDK para Python com um contexto assíncrono. Importe a classe `AsyncContext` e passe um exemplo dela para o gravador do X-Ray.
**nota**
As bibliotecas de suporte a framework da Web, como AIOHTTP, não são tratadas pelo módulo `aws_xray_sdk.core.patcher`. Elas não serão exibidas no catálogo de `patcher` de bibliotecas com suporte.
**Example main.py: aplicar patch a aioboto3**
```
import asyncio
import aioboto3
import requests
from aws_xray_sdk.core.async_context import AsyncContext
from aws_xray_sdk.core import xray_recorder
xray_recorder.configure(service='my_service', context=AsyncContext())
from aws_xray_sdk.core import patch
libraries = (['aioboto3'])
patch(libraries)
```
# Rastreando chamadas AWS do SDK com 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
[Quando seu aplicativo faz chamadas Serviços da AWS para armazenar dados, gravar em uma fila ou enviar notificações, o X-Ray SDK para Python rastreia as chamadas downstream em subsegmentos.](xray-sdk-python-subsegments.md) Os recursos rastreados Serviços da AWS e que você acessa nesses serviços (por exemplo, um bucket do Amazon S3 ou uma fila do Amazon SQS) aparecem como nós downstream no mapa de rastreamento no console X-Ray.
O X-Ray SDK para Python instrumenta automaticamente AWS todos os clientes do SDK quando [você](xray-sdk-python-patching.md) corrige a biblioteca. `botocore` Você não pode instrumentar clientes individuais.
Para todos os serviços, o nome da API chamada no console do X-Ray pode ser visto. Para um subconjunto de serviços, o X-Ray SDK adiciona informações ao segmento para fornecer maior detalhamento no mapa de serviços.
Por exemplo, quando você faz uma chamada com um cliente instrumentado do DynamoDB, o SDK adiciona o nome da tabela ao segmento para chamadas direcionadas a uma tabela. No console, cada tabela aparece como um nó separado no mapa de serviços, com um nó genérico do DynamoDB para chamadas não direcionadas a uma tabela.
**Example Subsegmento para uma chamada ao DynamoDB para salvar um item**
```
{
"id": "24756640c0d0978a",
"start_time": 1.480305974194E9,
"end_time": 1.4803059742E9,
"name": "DynamoDB",
"namespace": "aws",
"http": {
"response": {
"content_length": 60,
"status": 200
}
},
"aws": {
"table_name": "scorekeep-user",
"operation": "UpdateItem",
"request_id": "UBQNSO5AEM8T4FDA4RQDEB94OVTDRVV4K4HIRGVJF66Q9ASUAAJG",
}
}
```
Ao acessar recursos nomeados, as chamadas para os serviços os seguir criam nós adicionais no mapa de serviço. As chamadas que não apontam para recursos específicos criam um nó genérico para o serviço.
+ **Amazon DynamoDB**: nome da tabela
+ **Amazon Simple Storage Service**: nome de chave e bucket
+ **Amazon Simple Queue Service**: nome da fila
# Rastrear chamadas para serviços web HTTP subsequentes usando 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
Quando seu aplicativo faz chamadas para microsserviços ou HTTP público APIs, você pode usar o X-Ray SDK para Python para instrumentar essas chamadas e adicionar a API ao gráfico de serviços como um serviço downstream.
Para instrumentar clientes HTTP, [aplique um patch à biblioteca](xray-sdk-python-patching.md) que você usa para fazer chamadas de saída. Se você usa `requests` ou o cliente HTTP integrado Python, isso é tudo o que você precisa fazer. Para o `aiohttp`, configure também o gravador com um [contexto assíncrono](xray-sdk-python-patching.md#xray-sdk-python-patching-async).
Se você usar a API do cliente do `aiohttp` 3, também precisará configurar o `ClientSession`com uma instância da configuração de rastreamento fornecida pelo SDK.
**Example [API do cliente do `aiohttp` 3](https://github.com/aws/aws-xray-sdk-python#trace-aiohttp-client-requests)**
```
from aws_xray_sdk.ext.aiohttp.client import aws_xray_trace_config
async def foo():
trace_config = aws_xray_trace_config()
async with ClientSession(loop=loop, trace_configs=[trace_config]) as session:
async with session.get(url) as resp
await resp.read()
```
Quando você instrumenta uma chamada para uma API subsequente da web, o X-Ray SDK para Python registra um subsegmento que contém informações sobre a solicitação e a resposta HTTP. O X-Ray usa o subsegmento para gerar um segmento inferido para a API remota.
**Example Subsegmento para uma chamada HTTP downstream**
```
{
"id": "004f72be19cddc2a",
"start_time": 1484786387.131,
"end_time": 1484786387.501,
"name": "names.example.com",
"namespace": "remote",
"http": {
"request": {
"method": "GET",
"url": "https://names.example.com/"
},
"response": {
"content_length": -1,
"status": 200
}
}
}
```
**Example Segmento inferido para uma chamada HTTP de downstream**
```
{
"id": "168416dc2ea97781",
"name": "names.example.com",
"trace_id": "1-62be1272-1b71c4274f39f122afa64eab",
"start_time": 1484786387.131,
"end_time": 1484786387.501,
"parent_id": "004f72be19cddc2a",
"http": {
"request": {
"method": "GET",
"url": "https://names.example.com/"
},
"response": {
"content_length": -1,
"status": 200
}
},
"inferred": true
}
```
# Gerar subsegmentos personalizados com 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
Os subsegmentos estendem o [segmento](xray-concepts.md#xray-concepts-segments) de um rastreamento com detalhes sobre o trabalho realizado para atender a uma solicitação. Sempre que você faz uma chamada com um cliente instrumentado, o X-Ray SDK registra as informações geradas em um subsegmento. Você pode criar subsegmentos adicionais para agrupar outros subsegmentos, medir o desempenho de uma seção do código ou registrar anotações e metadados.
Para gerenciar subsegmentos, use os métodos `begin_subsegment` e `end_subsegment`.
**Example main.py: subsegmento personalizado**
```
from aws_xray_sdk.core import xray_recorder
subsegment = xray_recorder.begin_subsegment('annotations')
subsegment.put_annotation('id', 12345)
xray_recorder.end_subsegment()
```
Para criar um subsegmento para uma função síncrona, use o decorador `@xray_recorder.capture`. Você pode passar um nome para o subsegmento para a função de captura ou deixá-lo usar o nome da função.
**Example main.py: subsegmento de função**
```
from aws_xray_sdk.core import xray_recorder
@xray_recorder.capture('## create_user')
def create_user():
...
```
Para uma função assíncrona, use o decorador `@xray_recorder.capture_async` e passe um contexto assíncrono para o gravador.
**Example main.py: subsegmento de função assíncrona**
```
from aws_xray_sdk.core.async_context import AsyncContext
from aws_xray_sdk.core import xray_recorder
xray_recorder.configure(service='my_service', context=AsyncContext())
@xray_recorder.capture_async('## create_user')
async def create_user():
...
async def main():
await myfunc()
```
Quando você cria um subsegmento dentro de um segmento ou outro subsegmento, o X-Ray SDK para Python gera um ID para ele e registra a hora de início e de término.
**Example Subsegmento com metadados**
```
"subsegments": [{
"id": "6f1605cd8a07cb70",
"start_time": 1.480305974194E9,
"end_time": 1.4803059742E9,
"name": "Custom subsegment for UserModel.saveUser function",
"metadata": {
"debug": {
"test": "Metadata string from UserModel.saveUser"
}
},
```
# Adicionar anotações e metadados aos segmentos com 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
Você pode registrar informações adicionais sobre solicitações, o ambiente ou o aplicativo com anotações e metadados. Também é possível adicionar anotações e metadados aos segmentos que o X-Ray SDK cria ou aos subsegmentos personalizados que você cria.
**Anotações** são pares de chave-valor com valores boolianos, de string ou número. As anotações são indexadas para serem usadas com [expressões de filtro](xray-console-filters.md). Use anotações para registrar dados que você deseja usar para agrupar rastreamentos no console ou ao chamar a API [https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html](https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html).
**Metadados** são pares chave-valor que podem ter valores de qualquer tipo, incluindo objetos e listas, mas não são indexados para uso com expressões de filtro. Use metadados para registrar dados adicionais que você deseja armazenar no rastreamento e não precisa usar com a pesquisa.
Além de anotações e metadados, você também pode [registrar strings de ID de usuário](#xray-sdk-python-segment-userid) em segmentos. IDs Os usuários são registrados em um campo separado nos segmentos e são indexados para uso com a pesquisa.
**Topics**
+ [Registrar anotações com o X-Ray SDK para Python](#xray-sdk-python-segment-annotations)
+ [Registrar metadados com o X-Ray SDK para Python](#xray-sdk-python-segment-metadata)
+ [Gravando usuário IDs com o X-Ray SDK para Python](#xray-sdk-python-segment-userid)
## Registrar anotações com o X-Ray SDK para Python
Use anotações para registrar informações em segmentos ou subsegmentos que você deseja indexar para pesquisa.
**Requisitos de anotação**
+ **Chaves**: a chave para uma anotação do X-Ray pode ter até 500 caracteres alfanuméricos. Você não pode usar espaços ou símbolos que não sejam um ponto (.)
+ **Valores**: o valor de uma anotação do X-Ray pode ter até 1.000 caracteres Unicode.
+ O número de **anotações**: você pode usar até cinquenta anotações por rastreamento.
**Como registrar anotações**
1. Obtenha uma referência para o segmento ou subsegmento atual no `xray_recorder`.
```
from aws_xray_sdk.core import xray_recorder
...
document = xray_recorder.current_segment()
```
ou
```
from aws_xray_sdk.core import xray_recorder
...
document = xray_recorder.current_subsegment()
```
1. Chame `put_annotation` com uma chave de string e um valor de número, string ou booliano.
```
document.put_annotation("mykey", "my value");
```
O exemplo a seguir mostra como chamar `putAnnotation` com uma chave String que inclui um ponto e um valor booliano, numérico ou de string.
```
document.putAnnotation("testkey.test", "my value");
```
Também é possível usar o método `put_annotation` em `xray_recorder`. Esse método registra anotações no subsegmento atual ou, se nenhum subsegmento estiver aberto, no segmento.
```
xray_recorder.put_annotation("mykey", "my value");
```
O SDK registra anotações como pares de chave-valor em um objeto `annotations` no documento de segmentos. Chamar `put_annotation` duas vezes com a mesma chave substitui os valores registrados anteriormente no mesmo segmento ou subsegmento.
Para encontrar rastreamentos que têm anotações com valores específicos, use a palavra-chave `annotation[key]` em uma [expressão de filtro](xray-console-filters.md).
## Registrar metadados com o X-Ray SDK para Python
**Atenção**
Não adicione objetos com referências circulares como valores de metadados no SDK do X-Ray para Python. Esses objetos não podem ser serializados em JSON e podem criar loops infinitos no SDK. Além disso, evite adicionar objetos grandes e complexos como metadados para evitar problemas de desempenho.
Use metadados para registrar informações em segmentos ou subsegmentos dos quais você não precisa indexados para pesquisa. Valores de metadados podem ser strings, números, boolianos ou qualquer objeto que possa ser serializado em uma matriz ou objeto JSON.
**Como registrar metadados**
1. Obtenha uma referência para o segmento ou subsegmento atual no `xray_recorder`.
```
from aws_xray_sdk.core import xray_recorder
...
document = xray_recorder.current_segment()
```
ou
```
from aws_xray_sdk.core import xray_recorder
...
document = xray_recorder.current_subsegment()
```
1. Chame `put_metadata` com uma chave de string, um booliano, um número, uma string ou valor de objeto e um namespace de string.
```
document.put_metadata("my key", "my value", "my namespace");
```
or
Chame `put_metadata` com apenas uma chave e valor.
```
document.put_metadata("my key", "my value");
```
Também é possível usar o método `put_metadata` em `xray_recorder`. Esse método registra metadados no subsegmento atual ou, se nenhum subsegmento estiver aberto, no segmento.
```
xray_recorder.put_metadata("my key", "my value");
```
Se você não especificar um namespace, o SDK usará `default`. Chamar `put_metadata` duas vezes com a mesma chave substitui os valores registrados anteriormente no mesmo segmento ou subsegmento.
## Gravando usuário IDs com o X-Ray SDK para Python
Registre o usuário IDs nos segmentos da solicitação para identificar o usuário que enviou a solicitação.
**Para gravar usuário IDs**
1. Obtenha uma referência para o segmento atual em `xray_recorder`.
```
from aws_xray_sdk.core import xray_recorder
...
document = xray_recorder.current_segment()
```
1. Chame `setUser` com um ID de string do usuário que enviou a solicitação.
```
document.set_user("U12345");
```
Você pode acionar `set_user` em seus controladores para registrar o ID de usuário assim que o aplicativo começar a processar uma solicitação.
Para encontrar rastreamentos para um ID de usuário, use a `user` palavra-chave em uma [expressão de filtragem](xray-console-filters.md).
# Instrumentar frameworks da web implantadas em ambientes sem servidor
**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 AWS X-Ray SDK para Python oferece suporte a estruturas web de instrumentação implantadas em aplicativos sem servidor. Sem servidor é a arquitetura nativa da nuvem que permite transferir mais das suas responsabilidades operacionais à AWS, aumentando a agilidade e a inovação.
Arquitetura sem servidor é um modelo de aplicativo de software que permite que você crie e execute aplicativos e serviços sem se preocupar com servidores. Ela elimina as tarefas de gerenciamento de infraestrutura, como provisionamento de servidores ou de clusters, aplicação de patches, manutenção do sistema operacional e provisionamento de capacidade. Você pode criar soluções sem servidor para praticamente qualquer tipo de aplicativo ou serviço de back-end, e cuidaremos de tudo o que for necessário para executar e escalar aplicativos com alta disponibilidade.
Este tutorial mostra como instrumentar automaticamente AWS X-Ray em uma estrutura web, como Flask ou Django, que é implantada em um ambiente sem servidor. A instrumentação X-Ray do aplicativo permite que você visualize todas as chamadas downstream feitas, começando pelo Amazon API Gateway até sua AWS Lambda função, e as chamadas de saída que seu aplicativo faz.
O X-Ray SDK para Python é compatível com os seguintes frameworks de aplicação Python:
+ Flask versão 0.8 ou posterior
+ Django versão 1.0 ou posterior
Este tutorial desenvolve um exemplo de aplicação sem servidor que é implantada no Lambda e invocada pelo API Gateway. Este tutorial usa o Zappa para implantar automaticamente a aplicação no Lambda e configurar o endpoint do API Gateway.
## Pré-requisitos
+ [Zappa](https://github.com/Miserlou/Zappa)
+ [Python](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-python.html): versão 2.7 ou 3.6.
+ [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html)— Verifique se você AWS CLI está configurado com a conta e Região da AWS na qual você implantará seu aplicativo.
+ [Pip](https://pypi.org/project/pip/)
+ [Virtualenv](https://virtualenv.pypa.io/en/latest/)
## Etapa 1: Criar um ambiente
Nesta etapa, você cria um ambiente virtual usando `virtualenv` para hospedar um aplicativo.
1. Usando o AWS CLI, crie um diretório para o aplicativo. Altere para o novo diretório.
```
mkdir serverless_application
cd serverless_application
```
1. Em seguida, crie um ambiente virtual no novo diretório. Use o comando a seguir para ativá-lo:
```
# Create our virtual environment
virtualenv serverless_env
# Activate it
source serverless_env/bin/activate
```
1. Instale o X-Ray, o Flask, o Zappa e a biblioteca de solicitações em seu ambiente.
```
# Install X-Ray, Flask, Zappa, and Requests into your environment
pip install aws-xray-sdk flask zappa requests
```
1. Adicione o código do aplicativo ao diretório `serverless_application`. Para este exemplo, podemos criar a partir do exemplo [Hello World](https://flask.palletsprojects.com/en/3.0.x/quickstart/) do Flask.
No diretório `serverless_application`, crie um arquivo chamado `my_app.py`. Depois, use um editor de texto para adicionar os comandos a seguir. Este aplicativo instrumenta a biblioteca de solicitações, aplica patches ao middleware do aplicativo Flask e abre o endpoint `'/'`.
```
# Import the X-Ray modules
from aws_xray_sdk.ext.flask.middleware import XRayMiddleware
from aws_xray_sdk.core import patcher, xray_recorder
from flask import Flask
import requests
# Patch the requests module to enable automatic instrumentation
patcher.patch(('requests',))
app = Flask(__name__)
# Configure the X-Ray recorder to generate segments with our service name
xray_recorder.configure(service='My First Serverless App')
# Instrument the Flask application
XRayMiddleware(app, xray_recorder)
@app.route('/')
def hello_world():
resp = requests.get("https://aws.amazon.com")
return 'Hello, World: %s' % resp.url
```
## Etapa 2: Criar e implantar um ambiente do Zappa
Nesta etapa, você usará o Zappa para configurar automaticamente um endpoint do API Gateway e implantá-lo no Lambda.
1. Inicialize o Zappa de dentro do diretório `serverless_application`. Para este exemplo, usamos as configurações padrão, mas se você tiver preferências de personalização, o Zappa exibirá as instruções de configuração.
```
zappa init
```
```
What do you want to call this environment (default 'dev'): dev
...
What do you want to call your bucket? (default 'zappa-*******'): zappa-*******
...
...
It looks like this is a Flask application.
What's the modular path to your app's function?
This will likely be something like 'your_module.app'.
We discovered: my_app.app
Where is your app's function? (default 'my_app.app'): my_app.app
...
Would you like to deploy this application globally? (default 'n') [y/n/(p)rimary]: n
```
1. Habilite o X-Ray. Abra o arquivo `zappa_settings.json` e verifique se ele é similar ao exemplo.
```
{
"dev": {
"app_function": "my_app.app",
"aws_region": "us-west-2",
"profile_name": "default",
"project_name": "serverless-exam",
"runtime": "python2.7",
"s3_bucket": "zappa-*********"
}
}
```
1. Adicione `"xray_tracing": true` como uma entrada ao arquivo de configuração.
```
{
"dev": {
"app_function": "my_app.app",
"aws_region": "us-west-2",
"profile_name": "default",
"project_name": "serverless-exam",
"runtime": "python2.7",
"s3_bucket": "zappa-*********",
"xray_tracing": true
}
}
```
1. Implante o aplicativo . Isso configura automaticamente o endpoint do API Gateway e carrega o código no Lambda.
```
zappa deploy
```
```
...
Deploying API Gateway..
Deployment complete!: https://**********.execute-api.us-west-2.amazonaws.com/dev
```
## Etapa 3: Habilitar o rastreamento do X-Ray para o API Gateway
Nesta etapa, você interagirá com o console do API Gateway para habilitar o rastreamento do X-Ray.
1. Faça login no Console de gerenciamento da AWS e abra o console do API Gateway em [https://console.aws.amazon.com/apigateway/](https://console.aws.amazon.com/apigateway/).
1. Encontre sua API recém-gerada. Ele deve ser semelhante a `serverless-exam-dev`.
1. Escolha **Estágios**.
1. Escolha o nome de seu estágio de implantação. O padrão é `dev`.
1. Na guia **Logs/Tracing (Logs/rastreamento)**, marque a caixa **Enable X-Ray Tracing (Habilitar rastreamento do X-Ray)**.
1. Escolha **Salvar alterações**.
1. Acesse o endpoint em seu navegador. Se você usou o aplicativo de exemplo `Hello World`, ele deve exibir o seguinte.
```
"Hello, World: https://aws.amazon.com/"
```
## Etapa 4: Visualizar o rastreamento criado
Nesta etapa, você interagirá com o console do X-Ray para visualizar o rastreamento criado pela aplicação de exemplo. Para obter uma demonstração detalhada sobre a análise de rastreamento, consulte [Visualizar o mapa de serviço](https://docs.aws.amazon.com/xray/latest/devguide/xray-console.html#xray-console-servicemap).
1. Faça login Console de gerenciamento da AWS e abra o console X-Ray em [https://console.aws.amazon.com/xray/casa](https://console.aws.amazon.com/xray/home).
1. Visualize os segmentos gerados pelo API Gateway, pela função do Lambda e pelo contêiner do Lambda.
1. No segmento da função do Lambda, visualize um subsegmento chamado `My First Serverless App`. Ele é seguido por um segundo subsegmento chamado `https://aws.amazon.com`.
1. Durante a inicialização, o Lambda também pode gerar um terceiro subsegmento chamado `initialization`.
![\[Visualização de segmento de rastreamento.\]](http://docs.aws.amazon.com/pt_br/xray/latest/devguide/images/serverless-traceView.png)
![\[Visualização do gráfico de serviço\]](http://docs.aws.amazon.com/pt_br/xray/latest/devguide/images/serverless-serviceView.png)
## Etapa 5: limpar
Sempre encerre os recursos que não estão mais em uso para evitar o acúmulo de custos inesperados. Como este tutorial demonstra, ferramentas como o Zappa simplificam a reimplantação sem servidor.
Para remover sua aplicação do Lambda, do API Gateway e do Amazon S3, execute o comando a seguir no diretório do projeto usando a AWS CLI.
```
zappa undeploy dev
```
## Próximas etapas
Adicione mais recursos ao seu aplicativo adicionando AWS clientes e instrumentando-os com o X-Ray. Saiba mais sobre as opções de computação sem servidor em [Sem servidor na AWS](https://aws.amazon.com/serverless).