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 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.