Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.
# AWS X-Ray SDK para Python
**nota**
Aviso de SDK/Daemon mantenimiento de X-Ray: el 25 de febrero de 2026, el AWS X-Ray SDKs/Daemon entrará en modo de mantenimiento, donde AWS se limitarán las versiones de X-Ray SDK y Daemon para abordar únicamente los problemas de seguridad. Para obtener más información sobre la cronología del soporte, consulte [Cronología de X-Ray SDK y Daemon Support](xray-sdk-daemon-timeline.md). Recomendamos migrar a. OpenTelemetry Para obtener más información sobre la migración a OpenTelemetry, consulte [Migración de una instrumentación de rayos X a una instrumentación](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html). OpenTelemetry
El SDK de X-Ray para Python es una biblioteca para las aplicaciones web de Python que proporciona clases y métodos para generar y enviar datos de rastreo al daemon de X-Ray. Los datos de rastreo incluyen información sobre las solicitudes HTTP entrantes atendidas por la aplicación y las llamadas que la aplicación realiza a los servicios descendentes mediante el AWS SDK, los clientes HTTP o un conector de base de datos SQL. También puede crear segmentos de forma manual y agregar información de depuración en anotaciones y metadatos.
Puede descargar el SDK con `pip`.
```
$ pip install aws-xray-sdk
```
**nota**
El SDK de X-Ray para Python es un proyecto de código abierto. Puedes seguir el proyecto y enviar las incidencias y solicitudes de cambios en GitHub: [github. com/aws/aws](https://github.com/aws/aws-xray-sdk-python)- xray-sdk-python
Si usa Django o Flask, empiece [agregando el middleware del SDK a la aplicación](xray-sdk-python-middleware.md) para rastrear las solicitudes entrantes. El middleware crea un [segmento](xray-concepts.md#xray-concepts-segments) para cada solicitud rastreada y lo completa cuando se envía la respuesta. Mientras el segmento está abierto, puede utilizar los métodos del cliente del SDK para añadir información al segmento y crear subsegmentos para rastrear llamadas posteriores. El SDK también registra automáticamente las excepciones que produce su aplicación mientras el segmento está abierto. Para otras aplicaciones, puede [crear segmentos manualmente](xray-sdk-python-middleware.md#xray-sdk-python-middleware-manual).
En el caso de las funciones de Lambda llamadas por una aplicación o un servicio instrumentados, Lambda lee el [encabezado de rastreo](xray-concepts.md#xray-concepts-tracingheader) y rastrea automáticamente las solicitudes muestreadas. Para otras funciones, puede [configurar Lambda](xray-services-lambda.md) con el fin de muestrear y rastrear las solicitudes entrantes. En cualquier caso, Lambda crea el segmento y se lo proporciona al SDK de X-Ray.
**nota**
En Lambda, el SDK de X-Ray es opcional. Si no lo usa en su función, el mapa de servicio seguirá incluyendo un nodo para el servicio de Lambda y uno para cada función de Lambda. Al añadir el SDK, puede instrumentar el código de función para añadir subsegmentos al segmento de función registrado por Lambda. Para obtener más información, consulte [AWS Lambda y AWS X-Ray](xray-services-lambda.md).
Consulte [Entorno de trabajo](scorekeep-lambda.md#scorekeep-lambda-worker) para ver un ejemplo de una función de Python instrumentada en Lambda.
A continuación, utilice el SDK de X-Ray para Python con el fin de instrumentar llamadas posteriores [aplicando parches a las bibliotecas de su aplicación](xray-sdk-python-patching.md). El SDK admite las siguientes bibliotecas.
**Bibliotecas compatibles**
+ `[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/)`: instrumente la versión de PynamoDB del cliente de Amazon DynamoDB.
+ `[aiobotocore](https://pypi.python.org/pypi/aiobotocore)`, `[aioboto3](https://pypi.python.org/pypi/aioboto3)`: instrumente las versiones integradas en [asyncio](https://docs.python.org/3/library/asyncio.html) de los clientes del SDK para Python.
+ `[requests](https://pypi.python.org/pypi/requests)`, `[aiohttp](https://pypi.python.org/pypi/aiohttp)`: instrumente clientes HTTP de alto nivel.
+ `[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): instrumente los clientes HTTP de bajo nivel y las bibliotecas de más alto nivel que los utilizan.
+ `[sqlite3](https://docs.python.org/3/library/sqlite3.html)`— SQLite Clientes de instrumentos.
+ `[mysql-connector-python](https://pypi.python.org/pypi/mysql-connector-python)`: instrumente los clientes de MySQL.
+ `[pg8000](https://pypi.org/project/pg8000/)`: instrumente la interfaz PostgreSQL Pure-Python.
+ `[psycopg2](https://pypi.org/project/psycopg2/)`: instrumente el adaptador de base de datos PostgreSQL.
+ `[pymongo](https://pypi.org/project/pymongo/)`: instrumente clientes de MongoDB.
+ `[pymysql](https://pypi.org/project/PyMySQL/)`— Clientes basados en Instrument PyMy SQL y MariaDB.
Cada vez que la aplicación realiza llamadas a AWS una base de datos SQL u otros servicios HTTP, el SDK registra la información sobre la llamada en un subsegmento. Servicios de AWS y los recursos a los que accedes desde los servicios aparecen como nodos descendentes en el mapa de rastreo para ayudarte a identificar los errores y los problemas de limitación en las conexiones individuales.
En cuanto empiece a utilizar el SDK, personalice su comportamiento [configurando la grabadora y el controlador y el middleware](xray-sdk-python-configuration.md). Puede añadir complementos para registrar los datos sobre los recursos informáticos que ejecutan su aplicación, personalizar el comportamiento de muestreo mediante la definición de reglas de muestreo y definir el nivel de log para ver más o menos información del SDK en los logs de las aplicaciones.
Registre información adicional acerca de las solicitudes y el trabajo que la aplicación realiza en [anotaciones y metadatos](xray-sdk-python-segment.md). Las anotaciones son pares sencillos de clave-valor que se indexan para su uso con [expresiones de filtro](xray-console-filters.md) para poder buscar rastros que contengan datos específicos. Las entradas de metadatos son menos restrictivas y pueden registrar objetos y matrices completos, es decir, todo lo que se pueda serializar en JSON.
**Anotaciones y metadatos**
Las anotaciones y los metadatos son texto arbitrario que se agrega a los segmentos con el SDK de X-Ray. Las anotaciones se indexan para su uso con expresiones de filtro. Los metadatos no se indexan pero se pueden ver en el segmento sin procesar con la consola o la API de X-Ray. Cualquier persona a la que conceda acceso de lectura a X-Ray puede ver estos datos.
Cuando tenga muchos clientes instrumentados en su código, un único segmento de solicitud puede contener un gran número de subsegmentos, uno para cada llamada realizada con un cliente instrumentado. Puede organizar y agrupar los subsegmentos incluyendo las llamadas del cliente en [subsegmentos personalizados](xray-sdk-python-subsegments.md). Puede crear un subsegmento personalizado para toda una función o cualquier sección de código. A continuación, puede registrar metadatos y anotaciones en el subsegmento en lugar de escribir todo en el segmento principal.
Para acceder a la documentación de referencia de las clases y los métodos del SDK, consulte la [Referencia de la API del SDK de AWS X-Ray para Python](https://docs.aws.amazon.com/xray-sdk-for-python/latest/reference).
## Requisitos
El SDK de X-Ray para Python es compatible con los siguientes lenguajes y versiones de biblioteca.
+ **Python**: 2.7, 3.4 y posteriores
+ **Django**: 1.10 y posteriores
+ **Flask**: 0.10 y posteriores
+ **aiohttp**: 2.3.0 y posteriores
+ **AWS SDK para Python (Boto)**: 1.4.0 y posteriores
+ **botocore**: 1.5.0 y posteriores
+ **enum**: 0.4.7 y posteriores, para Python 3.4.0 y anteriores
+ **jsonpickle: 1.0.0** y posteriores
+ **setuptools**: 40.6.3 y posteriores
+ **wrapt**: 1.11.0 y posteriores
## Administración de dependencias
El SDK de X-Ray para Python está disponible en `pip`.
+ **Paquete**: `aws-xray-sdk`
Añada el SDK como una dependencia en su archivo `requirements.txt`.
**Example requirements.txt**
```
aws-xray-sdk==2.4.2
boto3==1.4.4
botocore==1.5.55
Django==1.11.3
```
Si utiliza Elastic Beanstalk para implementar su aplicación, Elastic Beanstalk instala todos los paquetes en `requirements.txt` de forma automática.
# Configuración del SDK de X-Ray para Python
**nota**
Aviso de SDK/Daemon mantenimiento de X-Ray: el 25 de febrero de 2026, el AWS X-Ray SDKs/Daemon entrará en modo de mantenimiento, donde AWS se limitarán las versiones de X-Ray SDK y Daemon para abordar únicamente los problemas de seguridad. Para obtener más información sobre la cronología del soporte, consulte [Cronología de X-Ray SDK y Daemon Support](xray-sdk-daemon-timeline.md). Recomendamos migrar a. OpenTelemetry Para obtener más información sobre la migración a OpenTelemetry, consulte [Migración de una instrumentación de rayos X a una instrumentación](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html). OpenTelemetry
El SDK de X-Ray para Python tiene una clase denominada `xray_recorder` que proporciona la grabadora global. Puede configurar la grabadora global para que personalice el middleware que crea los segmentos para las llamadas HTTP entrantes.
**Topics**
+ [Complementos del servicio](#xray-sdk-python-configuration-plugins)
+ [Reglas de muestreo](#xray-sdk-python-configuration-sampling)
+ [Registro](#xray-sdk-python-configuration-logging)
+ [Configuración de la grabadora en código](#xray-sdk-python-middleware-configuration-code)
+ [Configuración de la grabadora con Django](#xray-sdk-python-middleware-configuration-django)
+ [Variables de entorno](#xray-sdk-python-configuration-envvars)
## Complementos del servicio
Utilice `plugins` para registrar información sobre el servicio que aloja la aplicación.
**Plugins**
+ Amazon EC2 : `EC2Plugin` agrega el ID de la instancia, la zona de disponibilidad y el grupo de CloudWatch registros.
+ Elastic Beanstalk: `ElasticBeanstalkPlugin` añade el nombre de entorno, la etiqueta de versión y el ID de implementación.
+ Amazon ECS: `ECSPlugin` agrega el ID de contenedor.
![\[Segment - Scorekeep overview showing Elastic Beanstalk and EC2 deployment details.\]](http://docs.aws.amazon.com/es_es/xray/latest/devguide/images/scorekeep-PUTrules-segment-resources-python09.png)
Para utilizar un complemento, llame a `configure` en el `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**
Dado que se transfieren `plugins` como tupla, asegúrese de incluir una `,` después al especificar un único complemento. Por ejemplo, `plugins = ('EC2Plugin',)`
También puede utilizar las [variables de entorno](#xray-sdk-python-configuration-envvars), que tienen prioridad frente a los valores establecidos en código, para configurar la grabadora.
Configure los complementos antes de [aplicar parches en las bibliotecas](xray-sdk-python-patching.md) para registrar las llamadas posteriores.
El SDK también usa la configuración del complemento para establecer el campo `origin` en el segmento. Esto indica el tipo de AWS recurso que ejecuta la aplicación. Cuando utilizas varios complementos, el SDK utiliza el siguiente orden de resolución para determinar el origen: ElasticBeanstalk > EKS > ECS > EC2.
## Reglas de muestreo
El SDK utiliza las reglas de muestreo que define el usuario en la consola de X-Ray para determinar qué solicitudes registrar. La regla predeterminada rastrea la primera solicitud cada segundo y el 5 % de las solicitudes adicionales de todos los servicios que envían rastros a X-Ray. [Cree reglas adicionales en la consola de X-Ray](xray-console-sampling.md) para personalizar la cantidad de datos registrados para cada una de sus aplicaciones.
El SDK aplica las reglas personalizadas en el orden en que se definen. Si una solicitud coincide con varias reglas personalizadas, el SDK solo aplica la primera regla.
**nota**
Si el SDK no puede comunicarse con X-Ray para obtener las reglas de muestreo, vuelve a una regla local predeterminada de la primera solicitud cada segundo y del 5 % de las solicitudes adicionales por host. Esto puede ocurrir si el host no tiene permiso para llamar al muestreo APIs o no puede conectarse al daemon X-Ray, que actúa como proxy TCP para las llamadas a la API realizadas por el SDK.
También puede configurar el SDK para que cargue las reglas de muestreo desde un documento JSON. El SDK puede usar las reglas locales como respaldo para los casos en que el muestreo de X-Ray no esté disponible, o puede usar las reglas locales exclusivamente.
**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
}
}
```
En este ejemplo se define una regla personalizada y una regla predeterminada. La regla personalizada aplica un porcentaje de muestreo del 5 % sin un número mínimo de solicitudes de rastreo para las rutas incluidas bajo `/api/move/`. La regla predeterminada rastrea la primera solicitud cada segundo y el 10 % de las solicitudes adicionales.
La desventaja de definir las reglas localmente es que el objetivo establecido lo aplica cada instancia de la grabadora de forma independiente, en lugar de ser administrado por el servicio de X-Ray. A medida que se implementan más hosts, el porcentaje establecido se multiplica, lo que dificulta el control de la cantidad de datos registrados.
Sí AWS Lambda, no puedes modificar la frecuencia de muestreo. Si un servicio instrumentado llama a su función, Lambda registrará las llamadas que generaron solicitudes muestreadas por ese servicio. Si el rastreo activo está activado y no hay ningún encabezado de rastreo, Lambda toma la decisión de muestreo.
Para configurar las reglas de muestreo de respaldo`xray_recorder.configure`, llame, como se muestra en el siguiente ejemplo, a un diccionario de reglas o a la ruta absoluta a un archivo JSON que contiene reglas de muestreo. *rules*
```
xray_recorder.configure(sampling_rules=rules)
```
Para utilizar solo reglas locales, configure la grabadora con un `LocalSampler`.
```
from aws_xray_sdk.core.sampling.local.sampler import LocalSampler
xray_recorder.configure(sampler=LocalSampler())
```
También puede configurar la grabadora global para deshabilitar el muestreo e instrumentar todas las solicitudes entrantes.
**Example main.py: deshabilite el muestreo**
```
xray_recorder.configure(sampling=False)
```
## Registro
El SDK usa el módulo integrado `logging` de Python con un nivel de registro predeterminado `WARNING`. Obtenga una referencia al registrador para la clase `aws_xray_sdk` y llame `setLevel` en la misma para configurar el nivel de log diferente para la biblioteca y el resto de la aplicación.
**Example app.py registro**
```
logging.basicConfig(level='WARNING')
logging.getLogger('aws_xray_sdk').setLevel(logging.ERROR)
```
Utilice registros de depuración para identificar problemas como la presencia de subsegmentos sin cerrar al [generar subsegmentos de forma manual](xray-sdk-python-subsegments.md).
## Configuración de la grabadora en código
Hay disponibles ajustes adicionales a partir del método `configure` en `xray_recorder`.
+ `context_missing`: establezca esta opción en `LOG_ERROR` para evitar que se produzcan excepciones cuando el código instrumentado intente registrar datos sin que haya ningún segmento abierto.
+ `daemon_address`: establezca el host y el puerto del oyente del daemon de X-Ray.
+ `service`: establezca un nombre de servicio que el SDK utiliza para los segmentos.
+ `plugins`— Registra información sobre los AWS recursos de tu aplicación.
+ `sampling`: establezca esta opción en `False` para deshabilitar el muestreo.
+ `sampling_rules`: establezca la ruta del archivo JSON que contiene sus [reglas de muestreo](#xray-sdk-python-configuration-sampling).
**Example main.py: deshabilite excepciones de falta de contexto**
```
from aws_xray_sdk.core import xray_recorder
xray_recorder.configure(context_missing='LOG_ERROR')
```
## Configuración de la grabadora con Django
Si utiliza el marco de Django, puede utilizar el archivo `settings.py` de Django para configurar opciones en la grabadora global.
+ `AUTO_INSTRUMENT` (solo Django): registra subsegmentos para operaciones de representación de plantilla y base de datos integrada.
+ `AWS_XRAY_CONTEXT_MISSING`: establezca esta opción en `LOG_ERROR` para evitar que se produzcan excepciones cuando el código instrumentado intente registrar datos sin que haya ningún segmento abierto.
+ `AWS_XRAY_DAEMON_ADDRESS`: establezca el host y el puerto del oyente del daemon de X-Ray.
+ `AWS_XRAY_TRACING_NAME`: establezca un nombre de servicio que el SDK utiliza para los segmentos.
+ `PLUGINS`— Registre la información sobre AWS los recursos de su aplicación.
+ `SAMPLING`: establezca esta opción en `False` para deshabilitar el muestreo.
+ `SAMPLING_RULES`: establezca la ruta del archivo JSON que contiene sus [reglas de muestreo](#xray-sdk-python-configuration-sampling).
Para habilitar la configuración de la grabadora en `settings.py`, añada el middleware de Django a la lista de aplicaciones instaladas.
**Example settings.py: aplicaciones instaladas**
```
INSTALLED_APPS = [
...
'django.contrib.sessions',
'aws_xray_sdk.ext.django',
]
```
Configure los ajustes disponibles en un diccionario denominado `XRAY_RECORDER`.
**Example settings.py: aplicaciones instaladas**
```
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,
}
```
## Variables de entorno
Puede usar variables de entorno con el fin de configurar el SDK de X-Ray para Python. El SDK admite las siguientes variables:
+ `AWS_XRAY_TRACING_NAME`: establezca un nombre de servicio que el SDK utiliza para los segmentos. Anula el nombre de servicio que se establece mediante programación.
+ `AWS_XRAY_SDK_ENABLED`: cuando se establece en `false`, deshabilita el SDK. De forma predeterminada, el SDK está habilitado a menos que la variable de entorno esté establecida en false.
+ Cuando está deshabilitado, el grabador global genera automáticamente segmentos y subsegmentos ficticios que no se envían al demonio y se deshabilita la aplicación automática de parches. El middleware se registra como un contenedor en el grabador local. Todos los segmentos y subsegmentos que se generan a través del middleware también se vuelven ficticios.
+ Establezca el valor de `AWS_XRAY_SDK_ENABLED` a través de la variable de entorno o interactuando directamente con el objeto `global_sdk_config` de la biblioteca `aws_xray_sdk`. La configuración de la variable de entorno invalida estas interacciones.
+ `AWS_XRAY_DAEMON_ADDRESS`: establezca el host y el puerto del oyente del daemon de X-Ray. De forma predeterminada, el SDK utiliza `127.0.0.1:2000` tanto para los datos de rastro (UDP) como para el muestreo (TCP). Use esta variable si ha configurado el daemon para que [escuche en un puerto diferente](xray-daemon-configuration.md) o si se ejecuta en un host diferente.
**Formato**
+ **El mismo puerto**: `address:port`
+ **Puertos diferentes**: `tcp:address:port udp:address:port`
+ `AWS_XRAY_CONTEXT_MISSING`: establezca esta opción en `RUNTIME_ERROR` para generar excepciones cuando el código instrumentado intente registrar datos sin que haya ningún segmento abierto.
**Valores válidos**
+ `RUNTIME_ERROR`: lance una excepción de tiempo de ejecución.
+ `LOG_ERROR`: registre un error y continúe (predeterminado).
+ `IGNORE_ERROR`: ignore el error y continúe.
Se pueden producir errores relativos a segmentos o subsegmentos inexistentes al intentar usar un cliente instrumentado en el código de inicio que se ejecuta cuando no hay ninguna solicitud abierta o en el código que inicia un nuevo subproceso.
Las variables de entorno anulan los valores establecidos en el código.
# Rastreo de las solicitudes entrantes con el SDK de X-Ray para middleware de Python
**nota**
Aviso de SDK/Daemon mantenimiento de X-Ray: el 25 de febrero de 2026, el AWS X-Ray SDKs/Daemon entrará en modo de mantenimiento, donde AWS se limitarán las versiones de X-Ray SDK y Daemon para abordar únicamente los problemas de seguridad. Para obtener más información sobre la cronología del soporte, consulte [Cronología de X-Ray SDK y Daemon Support](xray-sdk-daemon-timeline.md). Recomendamos migrar a. OpenTelemetry Para obtener más información sobre la migración a OpenTelemetry, consulte [Migración de una instrumentación de rayos X a una instrumentación](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html). OpenTelemetry
Cuando añade el middleware a su aplicación y configura un nombre de segmento, el SDK de X-Ray para Python crea un segmento para cada solicitud muestreada. Este segmento incluye el momento, el método y la disposición de la solicitud HTTP. La instrumentación adicional crea subsegmentos en este segmento.
El SDK de X-Ray para Python admite el siguiente middleware para instrumentar solicitudes HTTP entrantes:
+ Django
+ Flask
+ Bottle
**nota**
Para AWS Lambda las funciones, Lambda crea un segmento para cada solicitud muestreada. Para obtener más información, consulte [AWS Lambda y AWS X-Ray](xray-services-lambda.md).
Consulte [Entorno de trabajo](scorekeep-lambda.md#scorekeep-lambda-worker) para ver un ejemplo de una función de Python instrumentada en Lambda.
Para scripts o aplicaciones Python en otros marcos de trabajo, puede [crear los segmentos manualmente](#xray-sdk-python-middleware-manual).
Cada segmento tiene un nombre que identifica la aplicación en el mapa de servicio. El nombre del segmento se puede asignar de forma estática o se puede configurar el SDK para que le asigne un nombre dinámico en función del encabezado del host de la solicitud entrante. La nomenclatura dinámica permite agrupar los rastros en función del nombre de dominio de la solicitud y aplicar un nombre predeterminado si el nombre no coincide con el patrón esperado (por ejemplo, si el encabezado del host está falsificado).
**Solicitudes reenviadas**
Si un equilibrador de carga u otro intermediario reenvía una solicitud a la aplicación, X-Ray toma la IP de cliente del encabezado `X-Forwarded-For` de la solicitud en lugar de tomar la IP de origen del paquete IP. La IP de cliente que se graba para una solicitud reenviada puede estar falsificada, por lo que no se debe confiar en ella.
Cuando se reenvía una solicitud, el SDK crea un campo adicional en el segmento para indicar que se realizó esta acción. Si el segmento contiene el campo `x_forwarded_for` configurado en `true`, el IP del cliente se obtiene a partir del encabezado `X-Forwarded-For` en la solicitud HTTP.
El middleware crea un segmento para cada solicitud entrante con un bloque `http` que contiene la siguiente información:
+ **Método HTTP**: GET, POST, PUT, DELETE, etc.
+ **Dirección del cliente**: la dirección IP del cliente que envió la solicitud.
+ **Código de respuesta**: el código de respuesta HTTP para la solicitud finalizada.
+ **Intervalo**: la hora de inicio (cuando se recibió la solicitud) y la hora de finalización (cuando se envió la respuesta).
+ **Agente del usuario**: el `user-agent` de la solicitud.
+ **Longitud del contenido**: la `content-length` de la respuesta.
**Topics**
+ [Agregar el middleware a su aplicación (Django)](#xray-sdk-python-adding-middleware-django)
+ [Agregar el middleware a su aplicación (flask)](#xray-sdk-python-adding-middleware-flask)
+ [Agregar el middleware a su aplicación (Bottle)](#xray-sdk-python-adding-middleware-bottle)
+ [Instrumentación manual del código de Python](#xray-sdk-python-middleware-manual)
+ [Configuración de una estrategia de nomenclatura de segmentos](#xray-sdk-python-middleware-naming)
## Agregar el middleware a su aplicación (Django)
Añada el middleware a la lista `MIDDLEWARE` en su archivo `settings.py`. El middleware de X-Ray debe ser la primera línea de su archivo `settings.py` para garantizar que se registren las solicitudes que fallan en otros middleware.
**Example settings.py: SDK de X-Ray para middleware de 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'
]
```
Añada la aplicación Django del SDK de X-Ray a la lista `INSTALLED_APPS` de su archivo `settings.py`. Eso permitirá configurar la grabadora de X-Ray durante el inicio de la aplicación.
**Example settings.py: aplicación Django del SDK de X-Ray 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 un nombre de segmento en su [`settings.py` archivo](xray-sdk-python-configuration.md#xray-sdk-python-middleware-configuration-django).
**Example settings.py: nombre de segmento**
```
XRAY_RECORDER = {
'AWS_XRAY_TRACING_NAME': 'My application',
'PLUGINS': ('EC2Plugin',),
}
```
Esto indica a la grabadora de X-Ray que rastree solicitudes servidas por la aplicación Django con el porcentaje de muestreo predeterminado. Puede [configurar la grabadora con el archivo de configuración de Django](xray-sdk-python-configuration.md#xray-sdk-python-middleware-configuration-django) para aplicar reglas de muestreo personalizadas o cambiar otros ajustes.
**nota**
Dado que se transfieren `plugins` como tupla, asegúrese de incluir una `,` después al especificar un único complemento. Por ejemplo, `plugins = ('EC2Plugin',)`
## Agregar el middleware a su aplicación (flask)
Para instrumentar su aplicación Flask, en primer lugar configure un nombre de segmento en el `xray_recorder`. A continuación, utilice la función `XRayMiddleware` para aplicar un parche a su aplicación Flask en 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)
```
Esto indica a la grabadora de X-Ray que rastree solicitudes servidas por la aplicación Flask con el porcentaje de muestreo predeterminado. Puede [configurar la grabadora en código](xray-sdk-python-configuration.md#xray-sdk-python-middleware-configuration-code) para aplicar reglas de muestreo personalizadas o cambiar otros ajustes.
## Agregar el middleware a su aplicación (Bottle)
Para instrumentar su aplicación Bottle, en primer lugar configure un nombre de segmento en el `xray_recorder`. A continuación, utilice la función `XRayMiddleware` para aplicar un parche a su aplicación Bottle en 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))
```
Esto indica a la grabadora de X-Ray que rastree solicitudes servidas por la aplicación Bottle con el porcentaje de muestreo predeterminado. Puede [configurar la grabadora en código](xray-sdk-python-configuration.md#xray-sdk-python-middleware-configuration-code) para aplicar reglas de muestreo personalizadas o cambiar otros ajustes.
## Instrumentación manual del código de Python
Si no utiliza Django o Flask, puede crear segmentos manualmente. Puede crear un segmento para cada solicitud entrante o crear segmentos en torno a clientes HTTP o AWS SDK parcheados para proporcionar un contexto que permita a la grabadora añadir subsegmentos.
**Example main.py: instrumentación 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()
```
## Configuración de una estrategia de nomenclatura de segmentos
AWS X-Ray utiliza un *nombre de servicio* para identificar la aplicación y distinguirla del resto de aplicaciones, bases de datos, recursos externos APIs y otros AWS recursos que utiliza la aplicación. Cuando el SDK de X-Ray genera segmentos para las solicitudes entrantes, registra el nombre del servicio de la aplicación en el [campo de nombre](xray-api-segmentdocuments.md#api-segmentdocuments-fields) del segmento.
El SDK de X-Ray puede nombrar los segmentos utilizando el nombre de host en el encabezado de la solicitud HTTP. Sin embargo, este encabezado se puede falsificar, lo que podría provocar nodos inesperados en el mapa de servicio. Para evitar que el SDK nombre los segmentos de forma incorrecta debido a que las solicitudes tienen encabezados de host falsificados, debe especificar un nombre predeterminado para las solicitudes entrantes.
Si la aplicación atiende solicitudes de varios dominios, puede configurar el SDK para que utilice una estrategia de nomenclatura dinámica que refleje esto en los nombres de los segmentos. Una estrategia de nomenclatura dinámica permite al SDK usar el nombre de host para las solicitudes que coinciden con un patrón esperado y aplicar el nombre predeterminado a las solicitudes que no coincidan.
Por ejemplo, es posible que tenga una sola aplicación que atienda solicitudes a tres subdominios: `www.example.com`, `api.example.com` y `static.example.com`. Puede usar una estrategia de nomenclatura dinámica con el patrón `*.example.com` para identificar los segmentos de cada subdominio con un nombre diferente, lo que da como resultado tres nodos de servicio en el mapa de servicio. Si su aplicación recibe solicitudes con un nombre de host que no coincide con el patrón, verá un cuarto nodo en el mapa de servicio con el nombre alternativo que especifique.
Si desea utilizar el mismo nombre para todos los segmentos de solicitud, especifique el nombre de la aplicación cuando configure la grabadora, como se muestra en las [secciones anteriores](#xray-sdk-python-adding-middleware-django).
Una estrategia de nomenclatura dinámica define un patrón con el que deben coincidir los nombres de host y un nombre predeterminado que se utiliza si el nombre de host de la solicitud HTTP no coincide con el patrón. Para nombrar segmentos de forma dinámica en Django, añada la configuración `DYNAMIC_NAMING` a su archivo [settings.py](xray-sdk-python-configuration.md#xray-sdk-python-middleware-configuration-django).
**Example settings.py: nomenclatura dinámica**
```
XRAY_RECORDER = {
'AUTO_INSTRUMENT': True,
'AWS_XRAY_TRACING_NAME': 'My application',
'DYNAMIC_NAMING': '*.example.com',
'PLUGINS': ('ElasticBeanstalkPlugin', 'EC2Plugin')
}
```
Puede utilizar "\$1" en el patrón para buscar coincidencia con cualquier cadena o "?" para buscar coincidencias con cualquier carácter único. Para Flask, [configure la grabadora en código](xray-sdk-python-configuration.md#xray-sdk-python-middleware-configuration-code).
**Example main.py: nombre de segmento**
```
from aws_xray_sdk.core import xray_recorder
xray_recorder.configure(service='My application')
xray_recorder.configure(dynamic_naming='*.example.com')
```
**nota**
Puede anular el nombre de servicio predeterminado que ha definido en el código mediante la `AWS_XRAY_TRACING_NAME`variable de entorno[Variables de entorno](xray-sdk-python-configuration.md#xray-sdk-python-configuration-envvars).
# Aplicación de parches a bibliotecas para instrumentar llamadas posteriores
**nota**
Aviso de SDK/Daemon mantenimiento de X-Ray: el 25 de febrero de 2026, el AWS X-Ray SDKs/Daemon entrará en modo de mantenimiento, donde AWS se limitarán las versiones de X-Ray SDK y Daemon para abordar únicamente los problemas de seguridad. Para obtener más información sobre la cronología del soporte, consulte [Cronología de X-Ray SDK y Daemon Support](xray-sdk-daemon-timeline.md). Recomendamos migrar a. OpenTelemetry Para obtener más información sobre la migración a OpenTelemetry, consulte [Migración de una instrumentación de rayos X a una instrumentación](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html). OpenTelemetry
Para instrumentar llamadas posteriores, utilice el SDK de X-Ray para Python para aplicar parches a las bibliotecas que utiliza la aplicación. El SDK de X-Ray para Python puede aplicar parches a las siguientes bibliotecas.
**Bibliotecas compatibles**
+ `[botocore](https://pypi.python.org/pypi/botocore)`, `[boto3](https://pypi.python.org/pypi/boto3)` — Clientes de instrumentos. AWS SDK para Python (Boto)
+ `[pynamodb](https://pypi.python.org/pypi/pynamodb/)`: instrumente la versión de PynamoDB del cliente de Amazon DynamoDB.
+ `[aiobotocore](https://pypi.python.org/pypi/aiobotocore)`, `[aioboto3](https://pypi.python.org/pypi/aioboto3)`: instrumente las versiones integradas en [asyncio](https://docs.python.org/3/library/asyncio.html) de los clientes del SDK para Python.
+ `[requests](https://pypi.python.org/pypi/requests)`, `[aiohttp](https://pypi.python.org/pypi/aiohttp)`: instrumente clientes HTTP de alto nivel.
+ `[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): instrumente los clientes HTTP de bajo nivel y las bibliotecas de más alto nivel que los utilizan.
+ `[sqlite3](https://docs.python.org/3/library/sqlite3.html)`— SQLite Clientes de instrumentos.
+ `[mysql-connector-python](https://pypi.python.org/pypi/mysql-connector-python)`: instrumente los clientes de MySQL.
+ `[pg8000](https://pypi.org/project/pg8000/)`: instrumente la interfaz PostgreSQL Pure-Python.
+ `[psycopg2](https://pypi.org/project/psycopg2/)`: instrumente el adaptador de base de datos PostgreSQL.
+ `[pymongo](https://pypi.org/project/pymongo/)`: instrumente clientes de MongoDB.
+ `[pymysql](https://pypi.org/project/PyMySQL/)`— Clientes basados en Instrument PyMy SQL y MariaDB.
Al utilizar una biblioteca con parches, el SDK de X-Ray para Python crea un subsegmento para la llamada y registra información desde la solicitud y la respuesta. Debe haber un segmento disponible para que el SDK cree el subsegmento, ya sea desde el middleware del SDK o desde AWS Lambda.
**nota**
Si utilizas SQLAlchemy ORM, puedes instrumentar tus consultas SQL importando la versión del SDK de las clases SQLAlchemy de sesión y consulta. Consulta Cómo [usar SQLAlchemy ORM](https://github.com/aws/aws-xray-sdk-python/blob/master/README.md#use-sqlalchemy-orm) para obtener instrucciones.
Para aplicar parches a todas las bibliotecas disponibles, utilice la función `patch_all` en `aws_xray_sdk.core`. Es posible que algunas bibliotecas, como `httplib` y `urllib`, necesiten habilitar la aplicación de parches dobles llamando a `patch_all(double_patch=True)`.
**Example main.py: aplique parches a todas las bibliotecas compatibles**
```
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 parches a una sola biblioteca, llame a `patch` con una tupla del nombre de la biblioteca. Para ello, deberá proporcionar una sola lista de elementos.
**Example main.py: aplique parches 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**
En algunos casos, la clave que se utiliza aplicar parches a una biblioteca no coincide con el nombre de la biblioteca. Algunas claves sirven como alias para una o varias bibliotecas.
`httplib`: `[httplib](https://docs.python.org/2/library/httplib.html)` y [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)`
## Seguimiento del contexto para el funcionamiento asíncrono
Para las bibliotecas integradas de `asyncio` o para [crear subsegmentos para funciones asíncronas](xray-sdk-python-subsegments.md), también debe configurar el SDK de X-Ray para Python con un contexto asíncrono. Importe la clase `AsyncContext` y pase una instancia de ella a la grabadora de X-Ray.
**nota**
Las bibliotecas compatibles con el marco de trabajo web, como AIOHTTP, no se gestionan a través del módulo `aws_xray_sdk.core.patcher`. No aparecerán en el catálogo de bibliotecas admitidas de`patcher`.
**Example main.py: aplique parches 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)
```
# Rastreo de llamadas al AWS SDK con el SDK de X-Ray para Python
**nota**
Aviso de SDK/Daemon mantenimiento de X-Ray: el 25 de febrero de 2026, el AWS X-Ray SDKs/Daemon entrará en modo de mantenimiento, donde AWS se limitarán las versiones de X-Ray SDK y Daemon para abordar únicamente los problemas de seguridad. Para obtener más información sobre la cronología del soporte, consulte [Cronología de X-Ray SDK y Daemon Support](xray-sdk-daemon-timeline.md). Recomendamos migrar a. OpenTelemetry Para obtener más información sobre la migración a OpenTelemetry, consulte [Migración de una instrumentación de rayos X a una instrumentación](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html). OpenTelemetry
[Cuando la aplicación realiza llamadas Servicios de AWS para almacenar datos, escribir en una cola o enviar notificaciones, el SDK de X-Ray para Python rastrea las llamadas en sentido descendente en subsegmentos.](xray-sdk-python-subsegments.md) El rastreo Servicios de AWS y los recursos a los que accede dentro de esos servicios (por ejemplo, un bucket de Amazon S3 o una cola de Amazon SQS) aparecen como nodos descendentes en el mapa de rastreo de la consola X-Ray.
El SDK de X-Ray para Python instrumenta automáticamente todos los clientes AWS del SDK cuando se aplica [un parche a la `botocore` biblioteca](xray-sdk-python-patching.md). No puede instrumentar clientes individuales.
Para todos los servicios, puede ver el nombre de la API a la que se llama en la consola de X-Ray. Para un subconjunto de servicios, el SDK de X-Ray agrega información al segmento para proporcionar una mayor granularidad en el mapa de servicio.
Por ejemplo, cuando realiza una llamada con un cliente instrumentado de DynamoDB, el SDK agrega el nombre de tabla al segmento para las llamadas que se dirigen a una tabla. En la consola, cada tabla aparece como nodo independiente en el mapa de servicio, con un nodo genérico de DynamoDB para las llamadas que no se dirigen a una tabla.
**Example Subsegmento para una llamada a DynamoDB con el fin de guardar un elemento**
```
{
"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",
}
}
```
Cuando accede a recursos designados, las llamadas a los siguientes servicios crean nodos adicionales en el mapa de servicio. Las llamadas que no están dirigidas a recursos concretos crean un nodo genérico en el servicio.
+ **Amazon DynamoDB**: nombre de tabla
+ **Amazon Simple Storage Service**: nombre de bucket y de clave
+ **Amazon Simple Queue Service**: nombre de cola
# Rastreo de llamadas a servicios web HTTP posteriores utilizando el SDK de X-Ray para Python
**nota**
Aviso de SDK/Daemon mantenimiento de X-Ray: el 25 de febrero de 2026, el AWS X-Ray SDKs/Daemon entrará en modo de mantenimiento, donde AWS se limitarán las versiones de X-Ray SDK y Daemon para abordar únicamente los problemas de seguridad. Para obtener más información sobre la cronología del soporte, consulte [Cronología de X-Ray SDK y Daemon Support](xray-sdk-daemon-timeline.md). Recomendamos migrar a. OpenTelemetry Para obtener más información sobre la migración a OpenTelemetry, consulte [Migración de una instrumentación de rayos X a una instrumentación](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html). OpenTelemetry
Cuando tu aplicación realiza llamadas a microservicios o HTTP públicos APIs, puedes usar el SDK de X-Ray para Python para instrumentar esas llamadas y añadir la API al gráfico del servicio como un servicio descendente.
Para instrumentar clientes HTTP, debe [aplicar parches a la biblioteca](xray-sdk-python-patching.md) que se utiliza para realizar llamadas salientes. Si utiliza `requests` o el cliente HTTP integrado de Python, eso es lo único que tiene que hacer. Para `aiohttp`, también debe configurar la grabadora con un [contexto asíncrono](xray-sdk-python-patching.md#xray-sdk-python-patching-async).
Si utiliza la API del cliente de `aiohttp` 3, es posible que también deba configurar la sesión de `ClientSession` con una instancia de la configuración de seguimiento proporcionada en el SDK.
**Example [API del cliente 3 de `aiohttp`](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()
```
Cuando se instrumenta una llamada a una API web posterior, el SDK de X-Ray para Python registra un subsegmento que contiene información acerca de la solicitud HTTP y la respuesta. X-Ray utiliza el subsegmento para generar un segmento inferido de la API remota.
**Example Subsegmento para una llamada HTTP posterior**
```
{
"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 una llamada HTTP posterior**
```
{
"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
}
```
# Generación de subsegmentos personalizados con el SDK de X-Ray para Python
**nota**
Aviso de SDK/Daemon mantenimiento de X-Ray: el 25 de febrero de 2026, el AWS X-Ray SDKs/Daemon entrará en modo de mantenimiento, donde AWS se limitarán las versiones de X-Ray SDK y Daemon para abordar únicamente los problemas de seguridad. Para obtener más información sobre la cronología del soporte, consulte [Cronología de X-Ray SDK y Daemon Support](xray-sdk-daemon-timeline.md). Recomendamos migrar a. OpenTelemetry Para obtener más información sobre la migración a OpenTelemetry, consulte [Migración de una instrumentación de rayos X a una instrumentación](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html). OpenTelemetry
Los subsegmentos amplían el [segmento](xray-concepts.md#xray-concepts-segments) de un rastro con detalles sobre el trabajo realizado para atender una solicitud. Cada vez que usted realiza una llamada con un cliente instrumentado, el SDK de X-Ray registra la información generada en un subsegmento. Puede crear subsegmentos adicionales para agrupar otros subsegmentos, medir el rendimiento de una sección de código o registrar anotaciones y metadatos.
Para administrar los subsegmentos, utilice los métodos `begin_subsegment` y `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 crear un subsegmento para una función síncrona, utilice el decorador `@xray_recorder.capture`. Puede transferir un nombre para el subsegmento a la función de captura o dejarlo para utilizar el nombre de la función.
**Example main.py: subsegmento de función**
```
from aws_xray_sdk.core import xray_recorder
@xray_recorder.capture('## create_user')
def create_user():
...
```
Si se trata de una función asíncrona, utilice el decorador `@xray_recorder.capture_async` y pase un contexto asíncrono a la grabadora.
**Example main.py: subsegmento de función así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()
```
Cuando crea un subsegmento dentro de un segmento o de otro subsegmento, el SDK de X-Ray para Python genera un ID para dicho subsegmento y registra la hora de inicio y la hora de finalización.
**Example Subsegmentos con metadatos**
```
"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"
}
},
```
# Adición de anotaciones y metadatos a los segmentos con el SDK de X-Ray para Python
**nota**
Aviso de SDK/Daemon mantenimiento de X-Ray: el 25 de febrero de 2026, el AWS X-Ray SDKs/Daemon entrará en modo de mantenimiento, donde AWS se limitarán las versiones de X-Ray SDK y Daemon para abordar únicamente los problemas de seguridad. Para obtener más información sobre la cronología del soporte, consulte [Cronología de X-Ray SDK y Daemon Support](xray-sdk-daemon-timeline.md). Recomendamos migrar a. OpenTelemetry Para obtener más información sobre la migración a OpenTelemetry, consulte [Migración de una instrumentación de rayos X a una instrumentación](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html). OpenTelemetry
Puede registrar información adicional acerca de las solicitudes, el entorno o su aplicación con anotaciones y metadatos. Puede añadir anotaciones y metadatos a los segmentos que crea el SDK de X-Ray o a los subsegmentos personalizados que cree usted mismo.
Las **anotaciones** son pares de clave-valor con valores de cadena, numéricos o booleanos. Las anotaciones se indexan para su uso con [expresiones de filtro](xray-console-filters.md). Utilice anotaciones para registrar los datos que desee utilizar para agrupar rastros en la consola o cuando llame a la API de [https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html](https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html).
Los **metadatos** son pares de clave-valor con valores de cualquier tipo, por ejemplo objetos y listas, pero que no se indexan para utilizarlos con expresiones de filtro. Utilice los metadatos para registrar datos adicionales que desee almacenar en el rastro, pero que no necesite usar para hacer búsquedas.
Además de anotaciones y metadatos, también puede [registrar cadenas de ID de usuario](#xray-sdk-python-segment-userid) en los segmentos. IDs Los usuarios se registran en un campo independiente en los segmentos y se indexan para usarlos en la búsqueda.
**Topics**
+ [Registro de anotaciones con el SDK de X-Ray para Python](#xray-sdk-python-segment-annotations)
+ [Registro de metadatos con el SDK de X-Ray para Python](#xray-sdk-python-segment-metadata)
+ [Grabación del usuario IDs con el SDK de X-Ray para Python](#xray-sdk-python-segment-userid)
## Registro de anotaciones con el SDK de X-Ray para Python
Utilice anotaciones para registrar información sobre segmentos o subsegmentos que desee indexar para las búsquedas.
**Requisitos de anotación**
+ **Claves**: la clave de una anotación de X-Ray puede contener hasta 500 caracteres alfanuméricos. No se pueden usar espacios ni símbolos, excepto el punto (.)
+ **Valores**: el valor de una anotación de X-Ray puede contener hasta 1000 caracteres Unicode.
+ Número de **anotaciones**: se pueden utilizar hasta 50 anotaciones por rastro.
**Para registrar anotaciones**
1. Obtenga una referencia al segmento o subsegmento actual desde `xray_recorder`.
```
from aws_xray_sdk.core import xray_recorder
...
document = xray_recorder.current_segment()
```
o
```
from aws_xray_sdk.core import xray_recorder
...
document = xray_recorder.current_subsegment()
```
1. Llame a `put_annotation` con una clave de cadena y un valor booleano, numérico o de cadena.
```
document.put_annotation("mykey", "my value");
```
El siguiente ejemplo muestra cómo llamar a `putAnnotation` con una clave de cadena que incluye un punto y un valor booleano, numérico o de cadena.
```
document.putAnnotation("testkey.test", "my value");
```
También puede utilizar el método `put_annotation` en el `xray_recorder`. Este método registra las anotaciones en el subsegmento actual o, si no hay ningún subsegmento abierto, en el segmento.
```
xray_recorder.put_annotation("mykey", "my value");
```
El SDK registra las anotaciones como pares de clave-valor en un objeto `annotations` del documento de segmento. Si llama dos veces a `put_annotation` con la misma clave, se sobrescriben los valores previamente registrados en ese segmento o subsegmento.
Para encontrar rastros que tengan anotaciones con valores específicos, utilice la palabra clave `annotation[key]` en una [expresión de filtro](xray-console-filters.md).
## Registro de metadatos con el SDK de X-Ray para Python
**aviso**
No agregue objetos con referencias circulares como valores de metadatos en el SDK de X-Ray para Python. Estos objetos no se pueden serializar en JSON y pueden crear bucles infinitos en el SDK. Además, evite agregar objetos grandes y complejos como metadatos para evitar problemas de rendimiento.
Utilice los metadatos para registrar información sobre segmentos o subsegmentos que no necesite indexar para las búsquedas. Los valores de metadatos pueden ser cadenas, números, booleanos o cualquier objeto que se pueda serializar en un objeto o matriz JSON.
**Para registrar metadatos**
1. Obtenga una referencia al segmento o subsegmento actual desde `xray_recorder`.
```
from aws_xray_sdk.core import xray_recorder
...
document = xray_recorder.current_segment()
```
o
```
from aws_xray_sdk.core import xray_recorder
...
document = xray_recorder.current_subsegment()
```
1. Llame a `put_metadata` con una clave de cadena; un valor booleano, numérico, de cadena o de objeto y un espacio de nombres de cadena.
```
document.put_metadata("my key", "my value", "my namespace");
```
o
Llame a `put_metadata` con solo una clave y un valor.
```
document.put_metadata("my key", "my value");
```
También puede utilizar el método `put_metadata` en el `xray_recorder`. Este método registra los metadatos en el subsegmento actual o, si no hay ningún subsegmento abierto, en el segmento.
```
xray_recorder.put_metadata("my key", "my value");
```
Si no especifica un espacio de nombres, el SDK utiliza `default`. Si llama dos veces a `put_metadata` con la misma clave, se sobrescriben los valores previamente registrados en ese segmento o subsegmento.
## Grabación del usuario IDs con el SDK de X-Ray para Python
Registre IDs el usuario en los segmentos de solicitud para identificar al usuario que envió la solicitud.
**Para registrar al usuario IDs**
1. Obtenga una referencia al segmento actual desde `xray_recorder`.
```
from aws_xray_sdk.core import xray_recorder
...
document = xray_recorder.current_segment()
```
1. Llame a `setUser` con un ID de cadena del usuario que envió la solicitud.
```
document.set_user("U12345");
```
Puede llamar a `set_user` en sus controladores para registrar el ID de usuario en cuanto la aplicación empiece a procesar la solicitud.
Para buscar rastros de un ID de usuario, utilice la palabra clave `user` en una [expresión de filtro](xray-console-filters.md).
# Instrumentación de marcos de trabajo web implementados en entornos sin servidor
**nota**
Aviso de SDK/Daemon mantenimiento de X-Ray: el 25 de febrero de 2026, el AWS X-Ray SDKs/Daemon entrará en modo de mantenimiento, donde AWS se limitarán las versiones de X-Ray SDK y Daemon para abordar únicamente los problemas de seguridad. Para obtener más información sobre la cronología del soporte, consulte [Cronología de X-Ray SDK y Daemon Support](xray-sdk-daemon-timeline.md). Recomendamos migrar a. OpenTelemetry Para obtener más información sobre la migración a OpenTelemetry, consulte [Migración de una instrumentación de rayos X a una instrumentación](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html). OpenTelemetry
El SDK de AWS X-Ray para Python admite la instrumentación de marcos web implementados en aplicaciones sin servidor. La arquitectura nativa de la nube carece de servidores, lo que le permite delegar más responsabilidades de gestión en AWS y mejorar la agilidad y la innovación.
La arquitectura sin servidor es un modelo de aplicaciones de software que permite crear y ejecutar aplicaciones y servicios sin preocuparse por los servidores. En esta arquitectura, ya no son necesarias las tareas de administración de la infraestructura, como el aprovisionamiento de servidores o clústeres, la aplicación de parches, el mantenimiento del sistema operativo y el aprovisionamiento de capacidad. Puede crear soluciones sin servidor para prácticamente cualquier tipo de aplicación o servicio de backend. Además, será usted quien se encargue de administrar todo lo necesario para ejecutar y escalar las aplicaciones con alta disponibilidad.
En este tutorial, se muestra cómo AWS X-Ray instrumentar automáticamente un marco web, como Flask o Django, que se implementa en un entorno sin servidor. La instrumentación de rayos X de la aplicación le permite ver todas las llamadas posteriores que se realizan, empezando por Amazon API Gateway y pasando por su AWS Lambda función, y las llamadas salientes que realiza la aplicación.
El SDK de X-Ray para Python admite los siguientes marcos de trabajo de aplicaciones de Python:
+ Flask versión 0.8 o posteriores
+ Django versión 1.0 o posteriores
En este tutorial se desarrolla un ejemplo de aplicación sin servidor que está implementada en Lambda y se invoca a través de API Gateway. En este tutorial se utiliza Zappa para implementar automáticamente la aplicación en Lambda y para configurar el punto de conexión de API Gateway.
## Requisitos previos
+ [Zappa](https://github.com/Miserlou/Zappa)
+ [Python](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-python.html): versión 2.7 o 3.6.
+ [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html)— Compruebe que AWS CLI está configurada con la cuenta Región de AWS en la que va a implementar la aplicación.
+ [Pip](https://pypi.org/project/pip/)
+ [Virtualenv](https://virtualenv.pypa.io/en/latest/)
## Paso 1: crear un entorno
En este paso, va a crear un entorno virtual utilizando `virtualenv` para hospedar la aplicación.
1. Con el AWS CLI, cree un directorio para la aplicación. A continuación, cambie al nuevo directorio.
```
mkdir serverless_application
cd serverless_application
```
1. Cree un entorno virtual en este nuevo directorio. Utilice el comando siguiente para activarlo.
```
# Create our virtual environment
virtualenv serverless_env
# Activate it
source serverless_env/bin/activate
```
1. Instale X-Ray, Flask, Zappa y la biblioteca de solicitudes en el entorno.
```
# Install X-Ray, Flask, Zappa, and Requests into your environment
pip install aws-xray-sdk flask zappa requests
```
1. Añada el código de la aplicación al directorio `serverless_application`. En este caso, puede utilizar como referencia el ejemplo [Hello World](https://flask.palletsprojects.com/en/3.0.x/quickstart/) de Flasks.
En el directorio `serverless_application`, cree un archivo llamado `my_app.py`. A continuación, utilice un editor de texto para añadir los siguientes comandos. Esta aplicación instrumenta la biblioteca de solicitudes, aplica parches en el middleware de la aplicación de Flask y abre el punto de enlace `'/'`.
```
# 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
```
## Paso 2: Crear e implementar un entorno de Zappa
En este paso, utilizará Zappa para configurar automáticamente un punto de conexión de API Gateway e implementarlo en Lambda.
1. Inicialice Zappa desde dentro del directorio `serverless_application`. En este ejemplo, hemos utilizado la configuración predeterminada. Sin embargo, si tiene sus propias preferencias de personalización, Zappa le mostrará las instrucciones de configuración.
```
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 X-Ray. Abra el archivo `zappa_settings.json` y compruebe que sea similar al del ejemplo.
```
{
"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. Añada `"xray_tracing": true` como entrada en el archivo de configuración.
```
{
"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. Implemente la aplicación . Esto configurará automáticamente el punto de conexión de API Gateway y cargará el código en Lambda.
```
zappa deploy
```
```
...
Deploying API Gateway..
Deployment complete!: https://**********.execute-api.us-west-2.amazonaws.com/dev
```
## Paso 3: habilitar el rastreo de X-Ray para API Gateway
En este paso, interactuará con la consola de API Gateway para habilitar el rastreo de X-Ray.
1. Inicie sesión en la consola de API Gateway Consola de administración de AWS y ábrala en [https://console.aws.amazon.com/apigateway/](https://console.aws.amazon.com/apigateway/).
1. Busque la API que acaba de generar. La URL debería parecerse a esta: `serverless-exam-dev`.
1. Elija **Etapas**.
1. Seleccione el nombre de la etapa de implementación. El valor predeterminado es `dev`.
1. En la pestaña **Logs/Tracing (Registros/rastreo)**, active la casilla **Enable X-Ray Tracing (Habilitar rastreo de X-Ray)**.
1. Elija **Save changes (Guardar cambios)**.
1. Obtenga acceso al punto de enlace a través del navegador. Si utilizó la aplicación `Hello World` de ejemplo, debería aparecer lo siguiente.
```
"Hello, World: https://aws.amazon.com/"
```
## Paso 4: Consultar el registro de seguimiento creado
En este paso, interactuará con la consola de X-Ray para ver el rastro creado por la aplicación de ejemplo. Para ver una explicación detallada del análisis del seguimiento, consulte [Uso del mapa de servicio](https://docs.aws.amazon.com/xray/latest/devguide/xray-console.html#xray-console-servicemap).
1. Inicie sesión en la consola de X-Ray Consola de administración de AWS y ábrala en [https://console.aws.amazon.com/xray/casa](https://console.aws.amazon.com/xray/home).
1. Consulte los segmentos generados por API Gateway, la función de Lambda y el contenedor de Lambda.
1. En el segmento de la función de Lambda, consulte un subsegmento llamado `My First Serverless App`. Detrás hay un segundo subsegmento llamado `https://aws.amazon.com`.
1. Durante la inicialización, Lambda podría generar también un tercer subsegmento llamado `initialization`.
![\[Vista del segmento de seguimiento.\]](http://docs.aws.amazon.com/es_es/xray/latest/devguide/images/serverless-traceView.png)
![\[Vista del gráfico de servicio.\]](http://docs.aws.amazon.com/es_es/xray/latest/devguide/images/serverless-serviceView.png)
## Paso 5: Eliminar
Termine siempre los recursos que ya no utilice para evitar que se acumulen costos inesperados. Tal y como se explica en este tutorial, existen herramientas como Zappa que optimizan la implementación sin servidor.
Para eliminar la aplicación de Lambda, API Gateway y Amazon S3, ejecute el siguiente comando en el directorio del proyecto a través de la AWS CLI.
```
zappa undeploy dev
```
## Siguientes pasos
Añada más funciones a su aplicación añadiendo AWS clientes e instrumentándolos con X-Ray. Consulte más información sobre las opciones de computación sin servidor de [Sin servidor en AWS](https://aws.amazon.com/serverless).