Adición de anotaciones y metadatos a los segmentos con el SDK de X-Ray para Python

Puede usar anotaciones y metadatos para registrar información adicional sobre las solicitudes, el entorno o la aplicación. 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. Utilice anotaciones para registrar los datos que desee utilizar para agrupar rastros en la consola o cuando llame a la API de GetTraceSummaries.

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 en los segmentos. Los identificadores de usuario se registran en un campo aparte en segmentos y se indexan para su uso con la búsqueda.

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

• Teclas: la clave de una anotación de X-Ray puede tener hasta 500 caracteres alfanuméricos. No puede utilizar espacios ni símbolos distintos del símbolo de subrayado (_).

• Valores: el valor de una anotación de X-Ray puede tener hasta 1000 caracteres Unicode.

• Número de anotaciones: puede utilizar hasta 50 anotaciones por traza.

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()

2. Llame a put_annotation con una clave de cadena y un valor booleano, numérico o de cadena.

   document.put_annotation("mykey", "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 annotations.key en una expresión de filtro.

Registro de metadatos con el SDK de X-Ray para Python

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()

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

Registro de ID de usuario con el SDK de X-Ray para Python

Registre identificadores de usuario en segmentos de solicitud para identificar al usuario que envió la solicitud.

Para registrar identificadores de usuario

1. Obtenga una referencia al segmento actual desde xray_recorder.

   from aws_xray_sdk.core import xray_recorder
   ...
   document = xray_recorder.current_segment()

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