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. # Configuración del X-Ray SDK para Python **nota** X-Ray SDK/Daemon Aviso de mantenimiento: el 25 de febrero de 2026, AWS X-Ray SDKs/Daemon entrará en modo de mantenimiento, en el que 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 X-Ray instrumentación a otra. OpenTelemetry ](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html) El X-Ray SDK 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. ![Segmente los datos de recursos con los complementos de Amazon EC2 y Elastic Beanstalk.](https://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 se definen en la X-Ray consola para determinar qué solicitudes se van a registrar. La regla predeterminada rastrea la primera solicitud cada segundo y el cinco por ciento de las solicitudes adicionales de todos los servicios a los que se envía el seguimiento X-Ray. [Cree reglas adicionales en la X-Ray consola](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 obtener las reglas de muestreo, vuelve a utilizar una regla local predeterminada que establece la primera solicitud cada segundo y el cinco por ciento de las solicitudes adicionales por host. X-Ray Esto puede ocurrir si el anfitrión no tiene permiso para llamar a las API de muestreo o no puede conectarse al X-Ray daemon, que actúa como proxy TCP para las llamadas a las API que realiza el SDK. También puede configurar el SDK para que cargue las reglas de muestreo desde un documento JSON. El SDK puede usar reglas locales como respaldo en los casos en que el X-Ray muestreo no esté disponible, o usar 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 de forma local es que el objetivo fijo lo aplica cada instancia de la grabadora de forma independiente, en lugar de ser gestionado por el X-Ray servicio. A medida que se implementan más hosts, el porcentaje establecido se multiplica, lo que dificulta el control de la cantidad de datos registrados. Activado AWS Lambda, no se puede 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`— Configura el host y el puerto del X-Ray daemon listener. + `service`: establezca el nombre de servicio que el SDK utiliza para los segmentos. + `plugins`— Registra información sobre los recursos de tu aplicación. AWS + `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`— Configura el host y el puerto del X-Ray daemon listener. + `AWS_XRAY_TRACING_NAME`: establezca el nombre de servicio que el SDK utiliza para los segmentos. + `PLUGINS`— Registra información sobre los recursos de tu aplicación. AWS + `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 para configurar el X-Ray SDK 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`— Configura el host y el puerto del X-Ray daemon listener. 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.