Configuración del SDK de X-Ray para Python - AWS X-Ray
Complementos del servicioReglas de muestreoRegistroConfiguración de la grabadora en códigoConfiguración de la grabadora con DjangoVariables de entorno

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

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.

Complementos del servicio

Utilice plugins para registrar información sobre el servicio que aloja la aplicación.

Complementos

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

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, 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 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 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 la regla local predeterminada de la primera solicitud recibida al principio de cada segundo y del cinco por ciento de las solicitudes adicionales por host. Eso puede ocurrir si el host no tiene permiso para llamar a las API de muestreo o no puede conectarse al daemon de X-Ray, que actúa como proxy TCP para las llamadas a las 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.

ejemplo 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 copia de seguridad, llame a xray_recorder.configure, tal y como se muestra en el siguiente ejemplo, donde reglas es un diccionario de reglas o la ruta absoluta a un archivo JSON que contiene reglas de muestreo.

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.

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

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

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

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

Para habilitar la configuración de la grabadora en settings.py, añada el middleware de Django a la lista de aplicaciones instaladas.

ejemplo settings.py: aplicaciones instaladas
INSTALLED_APPS = [
    ...
    'django.contrib.sessions',
    'aws_xray_sdk.ext.django',
]

Configure los ajustes disponibles en un diccionario denominado XRAY_RECORDER.

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