AWS X-Ray segmentar documentos - AWS X-Ray
Campos de segmentosSubsegmentosDatos de solicitudes HTTPAnnotationsMetadatosAWS datos de recursosErrores y excepcionesConsultas SQL

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 segmentar documentos

Un segmento de rastreo es una representación JSON de una solicitud que atiende su aplicación. Un segmento de rastreo registra información sobre la solicitud original, información sobre el trabajo que la aplicación realiza localmente y subsegmentos con información sobre las llamadas posteriores que la aplicación realiza a AWS los recursos, las API HTTP y las bases de datos SQL.

Un documento de segmento transmite información sobre un segmento a X-Ray. Un documento de segmento puede tener un tamaño de hasta 64 kB y contener un segmento completo con subsegmentos, un fragmento de un segmento que indique que una solicitud está en curso o un único subsegmento que se envía por separado. Puede enviar documentos de segmento directamente a X-Ray mediante la API de PutTraceSegments.

X-Ray compila y procesa los documentos de segmento para generar resúmenes de rastros y rastros completos que admiten consultas a los que puede obtener acceso mediante las API de GetTraceSummaries y BatchGetTraces, respectivamente. Además de los segmentos y subsegmentos que envía a X-Ray, el servicio utiliza la información de los subsegmentos para generar segmentos inferidos, que se añaden al rastro completo. Los segmentos inferidos representan los servicios y recursos posteriores en el mapa de rastreo.

X-Ray proporciona un esquema JSON para los documentos de segmento. Puede descargar el esquema aquí: xray-segmentdocument-schema-v 1.0.0. Los campos y objetos incluidos en el esquema se describen con más detalle en las secciones siguientes.

X-Ray indexa un subconjunto de los campos de segmento para su uso con expresiones de filtro. Por ejemplo, si establece el campo user de un segmento en un identificador único, puede buscar los segmentos asociados a usuarios específicos en la consola de X-Ray o mediante la API de GetTraceSummaries. Para obtener más información, consulte Uso de expresiones de filtro.

Cuando instrumente su aplicación con el SDK de X-Ray, el SDK generará automáticamente los documentos de segmento. En lugar de enviar documentos directamente a X-Ray, el SDK los transmite a través de un puerto UDP local al daemon de X-Ray. Para obtener más información, consulte Envío de documentos de segmento al daemon de X-Ray.

Campos de segmentos

Un segmento registra información de rastreo sobre una solicitud que atiende su aplicación. Como mínimo, un segmento registra el nombre, ID, hora de inicio, ID de rastro y el tiempo total de la solicitud.

ejemplo Segmento completo mínimo
{
  "name" : "example.com",
  "id" : "70de5b6f19ff9a0a",
  "start_time" : 1.478293361271E9,
  "trace_id" : "1-581cf771-a006649127e371903a2de979",
  "end_time" : 1.478293361449E9
}

Los siguientes campos son obligatorios o necesarios en determinadas circunstancias para los segmentos.

nota

Los valores deben ser cadenas (de hasta 250 caracteres), a menos que se indique lo contrario.

Campos de segmentos obligatorios

  • name: nombre lógico del servicio que gestiona la solicitud (hasta 200 caracteres). Por ejemplo, el nombre de su aplicación o el nombre de dominio. Los nombres pueden contener letras Unicode, números y espacios en blanco, así como los siguientes símbolos: _, ., :, /, %, &, #, =, +, \, -, @

  • id: un identificador de 64 bits para el segmento, único entre otros segmentos del mismo rastro, en 16 dígitos hexadecimales.

  • trace_id: un identificador único que conecta todos los segmentos y subsegmentos procedentes de una única solicitud de cliente.

    Formato de identificación de trazas de rayos X

    Un trace_id de X-Ray consta de tres números separados por guiones. Por ejemplo, 1-58406520-a006649127e371903a2de979. Esto incluye:

    • El número de versión, que es1.

    • La hora de la solicitud original en Unix (época) con 8 dígitos hexadecimales.

      Por ejemplo, a las 10:00 a. m. del 1 de diciembre de 2016 (hora peninsular española) se indica en 1480615200 segundos o 58406520 en dígitos hexadecimales.

    • Un identificador de 96 bits único a nivel mundial para el rastreo en 24 dígitos hexadecimales.

    nota

    X-Ray ahora admite los ID de rastreo que se crean utilizando OpenTelemetry y cualquier otro marco que cumpla con la especificación Trace Context del W3C. Un identificador de rastreo del W3C debe estar formateado en formato de identificador de rastreo de rayos X cuando se envía a X-Ray. Por ejemplo, el identificador de rastreo del W3C 4efaaf4d1e8720b39541901950019ee5 debe tener el mismo formato que 1-4efaaf4d-1e8720b39541901950019ee5 cuando se envía a X-Ray. Los ID de rastreo de rayos X incluyen la marca de tiempo original de la solicitud en Unix epoch Time, pero esto no es obligatorio cuando se envían los ID de rastreo del W3C en formato X-Ray.

    Seguridad de ID de rastro

    Los ID de rastro se pueden ver en los encabezados de respuesta. Genere ID de rastro con algoritmo aleatorio seguro para garantizar que los atacantes no puedan calcular futuros ID de rastro y enviar solicitudes con esos ID a su aplicación.

  • start_time: número que representa el momento en que se creó el segmento, en segundos de punto flotante en formato de tiempo Unix. Por ejemplo, 1480615200.010 o 1.480615200010E9. Use tantos decimales como necesite. Se recomienda una precisión de microsegundos cuando sea posible.

  • end_time: número que representa el momento en que se cerró el segmento. Por ejemplo, 1480615200.090 o 1.480615200090E9. Especifique un end_time o in_progress.

  • in_progress: booleano que se establece en true en lugar de especificar un end_time para registrar que se inició un subsegmento pero que no se completó. Envíe un segmento en curso cuando su aplicación reciba una solicitud que llevará tiempo atender, para rastrear la recepción de la solicitud. Cuando la respuesta se envía, envíe el segmento completo para sobrescribir el segmento en curso. Envíe solo un segmento completo o uno o cero segmentos en curso por solicitud.

Nombres de servicio

El name de un segmento debe coincidir con el nombre de dominio o el nombre lógico del servicio que genere el segmento. Sin embargo, este requisito no se exige. Cualquier aplicación que tenga permiso para PutTraceSegments puede enviar segmentos con cualquier nombre.

Los siguientes campos son opcionales para los segmentos.

Campos de segmentos opcionales

  • service: un objeto con información sobre su aplicación.

    • version: una cadena que identifica la versión de la aplicación que atiende la solicitud.

  • user: una cadena que identifica el usuario que envía la solicitud.

  • origin— El tipo de AWS recurso que ejecuta la aplicación.

    Valores admitidos

    • AWS::EC2::Instance: una instancia de Amazon EC2.

    • AWS::ECS::Container: un contenedor de Amazon ECS.

    • AWS::ElasticBeanstalk::Environment: un entorno de Elastic Beanstalk

    Si hay varios valores que sean aplicables a su aplicación, utilice el que sea más específico. Por ejemplo, supongamos que un Docker multicontenedor en Elastic Beanstalk ejecuta su aplicación en un contenedor de Amazon ECS que, a su vez, se ejecuta en una instancia de Amazon EC2. En este caso, el origen se establecería en AWS::ElasticBeanstalk::Environment, puesto que es el elemento principal de los otros dos recursos.

  • parent_id: un ID de subsegmento que especifica si la solicitud se originó desde una aplicación instrumentada. El SDK de X-Ray añade el ID del subsegmento principal al encabezado de rastreo para las llamadas HTTP posteriores. En el caso de subsegmentos anidados, un subsegmento puede tener un segmento o un subsegmento como padre.

  • http: objetos http con información sobre la solicitud HTTP original.

  • aws— awsobjeto con información sobre el AWS recurso en el que la aplicación atendió la solicitud.

  • error, throttle, fault y cause: campos de error que indican que se ha producido un error y que incluyen información sobre la excepción que ha causado el error.

  • annotations: objeto annotations con pares de clave-valor que X-Ray debe indexar para las búsquedas.

  • metadata: objeto metadata con los datos adicionales que desea almacenar en el segmento.

  • subsegments: matriz de objetos subsegment.

Subsegmentos

Puedes crear subsegmentos para registrar las llamadas Servicios de AWS y los recursos que realices con el AWS SDK, las llamadas a las API web HTTP internas o externas o las consultas a bases de datos SQL. También puede crear subsegmentos para depurar o anotar bloques de código en su aplicación. Los subsegmentos pueden contener otros subsegmentos, por lo que un subsegmento personalizado que registre los metadatos de una llamada a una función interna puede contener otros subsegmentos personalizados y subsegmentos para llamadas posteriores.

Un subsegmento registra una llamada posterior desde el punto de vista del servicio que llama. X-Ray utiliza subsegmentos para identificar los servicios posteriores que no envían segmentos y crean entradas para segmentos en el gráfico de servicios.

Un subsegmento puede incrustarse en un documento de segmentos completos o enviarse por separado. Envíe subsegmentos por separado para realizar un rastreo asíncrono de las llamadas posteriores para realizar solicitudes de larga ejecución o para evitar superar el tamaño máximo del documento de segmentos.

ejemplo Segmento con un subsegmento incrustado

Un subsegmento independiente tiene un type de subsegment y un parent_id que identifica el segmento principal.

{
  "trace_id"   : "1-5759e988-bd862e3fe1be46a994272793",
  "id"         : "defdfd9912dc5a56",
  "start_time" : 1461096053.37518,
  "end_time"   : 1461096053.4042,
  "name"       : "www.example.com",
  "http"       : {
    "request"  : {
      "url"        : "https://www.example.com/health",
      "method"     : "GET",
      "user_agent" : "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_6) AppleWebKit/601.7.7",
      "client_ip"  : "11.0.3.111"
    },
    "response" : {
      "status"         : 200,
      "content_length" : 86
    }
  },
  "subsegments" : [
    {
      "id"         : "53995c3f42cd8ad8",
      "name"       : "api.example.com",
      "start_time" : 1461096053.37769,
      "end_time"   : 1461096053.40379,
      "namespace"  : "remote",
      "http"       : {
        "request"  : {
          "url"    : "https://api.example.com/health",
          "method" : "POST",
          "traced" : true
        },
        "response" : {
          "status"         : 200,
          "content_length" : 861
        }
      }
    }
  ]
}

En el caso de las solicitudes de larga ejecución, puede enviar un segmento en curso para notificar a X-Ray que la solicitud se ha recibido y, a continuación, enviar por separado los subsegmentos para que se rastreen antes de que se complete la solicitud original.

ejemplo Segmento en curso
{
  "name" : "example.com",
  "id" : "70de5b6f19ff9a0b",
  "start_time" : 1.478293361271E9,
  "trace_id" : "1-581cf771-a006649127e371903a2de979",
  "in_progress": true
}
ejemplo Subsegmentos independientes

Un subsegmento independiente tiene un type de subsegment, un trace_id y un parent_id que identifica el segmento principal.

{
  "name" : "api.example.com",
  "id" : "53995c3f42cd8ad8",
  "start_time" : 1.478293361271E9,
  "end_time" : 1.478293361449E9,
  "type" : "subsegment",
  "trace_id" : "1-581cf771-a006649127e371903a2de979"
  "parent_id" : "defdfd9912dc5a56",
  "namespace"  : "remote",
  "http"       : {
      "request"  : {
          "url"    : "https://api.example.com/health",
          "method" : "POST",
          "traced" : true
      },
      "response" : {
          "status"         : 200,
          "content_length" : 861
      }
  }
}

Cuando se complete la solicitud, cierre el segmento reenviándolo con un end_time. El segmento completo sobrescribe el segmento en curso.

También puede enviar subsegmentos por separado para solicitudes realizadas que activen flujos de trabajo asíncronos. Por ejemplo, una API web puede devolver una respuesta OK 200 inmediatamente antes de iniciar el trabajo que el usuario ha solicitado. Puede enviar un segmento completo a X-Ray en cuanto se envíe la respuesta, seguido de subsegmentos para el trabajo realizado más adelante. Al igual que con los segmentos, también puede enviar un fragmento de un subsegmento para registrar que el subsegmento se ha iniciado y, a continuación, sobrescribirlo con un subsegmento completo una vez que se haya completado la llamada posterior.

Los siguientes campos son obligatorios o necesarios en determinadas circunstancias para los subsegmentos.

nota

Los valores son cadenas (de hasta 250 caracteres), a menos que se indique lo contrario.

Campos de subsegmentos obligatorios

  • id: un identificador de 64 bits para el subsegmento, único entre otros segmentos del mismo rastro, en 16 dígitos hexadecimales.

  • name: nombre lógico del subsegmento. En el caso de las llamadas posteriores, asigne un nombre al subsegmento detrás del recurso o servicio llamado. Para los subsegmentos personalizados, asigne el nombre al subsegmento detrás del código que lo instrumenta (por ejemplo, un nombre de función).

  • start_time: número que representa el momento en que se creó el subsegmento, en segundos de punto flotante en tiempo Unix, con una precisión de milisegundos. Por ejemplo, 1480615200.010 o 1.480615200010E9.

  • end_time: número que representa el momento en que se cerró el subsegmento. Por ejemplo, 1480615200.090 o 1.480615200090E9. Especifique un valor para end_time o in_progress.

  • in_progress: booleano que se establece en true en lugar de especificar un end_time para registrar que se inició un subsegmento pero que no se completó. Envíe solo un subsegmento completo y uno o cero subsegmentos en curso por solicitud posterior.

  • trace_id: ID de rastro del segmento principal del subsegmento. Solo es necesario si el envío del subsegmento se realiza por separado.

    Formato de identificación de trazas de rayos X

    Un trace_id de X-Ray consta de tres números separados por guiones. Por ejemplo, 1-58406520-a006649127e371903a2de979. Esto incluye:

    • El número de versión, que es1.

    • La hora de la solicitud original en Unix (época) con 8 dígitos hexadecimales.

      Por ejemplo, a las 10:00 a. m. del 1 de diciembre de 2016 (hora peninsular española) se indica en 1480615200 segundos o 58406520 en dígitos hexadecimales.

    • Un identificador de 96 bits único a nivel mundial para el rastreo en 24 dígitos hexadecimales.

    nota

    X-Ray ahora admite los ID de rastreo que se crean utilizando OpenTelemetry y cualquier otro marco que cumpla con la especificación Trace Context del W3C. Un identificador de rastreo del W3C debe estar formateado en formato de identificador de rastreo de rayos X cuando se envía a X-Ray. Por ejemplo, el identificador de rastreo del W3C 4efaaf4d1e8720b39541901950019ee5 debe tener el mismo formato que 1-4efaaf4d-1e8720b39541901950019ee5 cuando se envía a X-Ray. Los ID de rastreo de rayos X incluyen la marca de tiempo original de la solicitud en Unix epoch Time, pero esto no es obligatorio cuando se envían los ID de rastreo del W3C en formato X-Ray.

  • parent_id: ID del segmento principal del subsegmento. Solo es necesario si el envío del subsegmento se realiza por separado. En el caso de subsegmentos anidados, un subsegmento puede tener un segmento o un subsegmento como padre.

  • type – subsegment. Solo es necesario si el envío del subsegmento se realiza por separado.

Los siguientes campos son opcionales para los subsegmentos.

Campos de subsegmentos opcionales

  • namespace: aws para las llamadas al SDK de AWS; remote para las demás llamadas posteriores.

  • http: objeto http con información sobre una llamada HTTP saliente.

  • aws— awsobjeto con información sobre el AWS recurso descendente al que ha llamado la aplicación.

  • error, throttle, fault y cause: campos de error que indican que se ha producido un error y que incluyen información sobre la excepción que ha causado el error.

  • annotations: objeto annotations con pares de clave-valor que X-Ray debe indexar para las búsquedas.

  • metadata: objeto metadata con los datos adicionales que desea almacenar en el segmento.

  • subsegments: matriz de objetos subsegment.

  • precursor_ids: matriz de identificadores de subsegmento que identifica los subsegmentos con el mismo segmento principal que se completó antes de este subsegmento.

Datos de solicitudes HTTP

Utilice un bloque HTTP para registrar los detalles de una solicitud HTTP que ha atendido su aplicación (en un segmento) o que ha realizado la aplicación en una API HTTP posterior (en un subsegmento). La mayoría de los campos de este objeto se asignan a la información proporcionada en una solicitud y respuesta HTTP.

http

Todos los campos son opcionales.

  • request: información sobre una solicitud.

    • method: el método de solicitud. Por ejemplo, GET.

    • url: la dirección URL completa, obtenida del protocolo, nombre de host y ruta de la solicitud.

    • user_agent: la cadena de agente de usuario del cliente del solicitante.

    • client_ip: la dirección IP del solicitante. Se puede recuperar del Source Address del paquete de direcciones IP o, en el caso de las solicitudes reenviadas, de un encabezado X-Forwarded-For.

    • x_forwarded_for: (solo segmentos) booleano que indica que se ha leído el client_ip desde un encabezado X-Forwarded-For y no es fiable, ya que podría haberse falsificado.

    • traced: (solo subsegmentos) booleano que indica que la llamada posterior es a otro servicio rastreado. Si este campo está establecido en true, X-Ray considera que el rastro se debe dividir hasta que el servicio posterior cargue el segmento con un parent_id que coincida con el id del subsegmento que contiene este bloque.

  • response: información sobre una respuesta.

    • status: entero que indica el estado HTTP de la respuesta.

    • content_length: entero que indica la longitud del cuerpo de la respuesta en bytes.

Cuando instrumente una llamada a una API web posterior, este campo registra un subsegmento con información sobre la solicitud HTTP y la respuesta. X-Ray utiliza el subsegmento para generar un segmento inferido de la API remota.

ejemplo Segmento para las llamadas HTTP atendidas por una aplicación en ejecución en Amazon EC2
{
  "id": "6b55dcc497934f1a",
  "start_time": 1484789387.126,
  "end_time": 1484789387.535,
  "trace_id": "1-5880168b-fd5158284b67678a3bb5a78c",
  "name": "www.example.com",
  "origin": "AWS::EC2::Instance",
  "aws": {
    "ec2": {
      "availability_zone": "us-west-2c",
      "instance_id": "i-0b5a4678fc325bg98"
    },
    "xray": {
        "sdk_version": "2.11.0 for Java"
    },
  },
  "http": {
    "request": {
      "method": "POST",
      "client_ip": "78.255.233.48",
      "url": "http://www.example.com/api/user",
      "user_agent": "Mozilla/5.0 (Windows NT 6.1; WOW64; rv:45.0) Gecko/20100101 Firefox/45.0",
      "x_forwarded_for": true
    },
    "response": {
      "status": 200
    }
  }
ejemplo 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
    }
  }
}
ejemplo 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
}

Annotations

Los segmentos y subsegmentos pueden incluir un objeto annotations con uno o varios campos que X-Ray indexa para su uso con expresiones de filtro. Los campos pueden tener valores de cadena, numéricos o booleanos (pero no objetos ni matrices). X-Ray indexa hasta 50 anotaciones por rastro.

ejemplo Segmento para llamadas HTTP con anotaciones
{
  "id": "6b55dcc497932f1a",
  "start_time": 1484789187.126,
  "end_time": 1484789187.535,
  "trace_id": "1-5880168b-fd515828bs07678a3bb5a78c",
  "name": "www.example.com",
  "origin": "AWS::EC2::Instance",
  "aws": {
    "ec2": {
      "availability_zone": "us-west-2c",
      "instance_id": "i-0b5a4678fc325bg98"
    },
    "xray": {
        "sdk_version": "2.11.0 for Java"
    },
  },
  "annotations": {
    "customer_category" : 124,
    "zip_code" : 98101,
    "country" : "United States",
    "internal" : false
  },
  "http": {
    "request": {
      "method": "POST",
      "client_ip": "78.255.233.48",
      "url": "http://www.example.com/api/user",
      "user_agent": "Mozilla/5.0 (Windows NT 6.1; WOW64; rv:45.0) Gecko/20100101 Firefox/45.0",
      "x_forwarded_for": true
    },
    "response": {
      "status": 200
    }
  }

Para que las claves funcionen con filtros, deben estar en orden alfanumérico. Se admite el guion bajo, pero no otros símbolos ni espacios en blanco.

Metadatos

Los segmentos y subsegmentos pueden incluir un objeto metadata que contenga uno o varios campos con valores de cualquier tipo, incluidos objetos y matrices. X-Ray no indexa los metadatos, y los valores pueden ser de cualquier tamaño siempre que el documento del segmento no supere el tamaño máximo (64 kB). Puede ver los metadatos en el documento del segmento completo devuelto por la API de BatchGetTraces. Las claves de campo (debugen el siguiente ejemplo) que comienzan por: AWS. están reservadas para que las utilicen los SDK y los clientes AWS proporcionados.

ejemplo Subsegmento personalizado con metadatos
{
  "id": "0e58d2918e9038e8",
  "start_time": 1484789387.502,
  "end_time": 1484789387.534,
  "name": "## UserModel.saveUser",
  "metadata": {
    "debug": {
      "test": "Metadata string from UserModel.saveUser"
    }
  },
  "subsegments": [
    {
      "id": "0f910026178b71eb",
      "start_time": 1484789387.502,
      "end_time": 1484789387.534,
      "name": "DynamoDB",
      "namespace": "aws",
      "http": {
        "response": {
          "content_length": 58,
          "status": 200
        }
      },
      "aws": {
        "table_name": "scorekeep-user",
        "operation": "UpdateItem",
        "request_id": "3AIENM5J4ELQ3SPODHKBIRVIC3VV4KQNSO5AEMVJF66Q9ASUAAJG",
        "resource_names": [
          "scorekeep-user"
        ]
      }
    }
  ]
}

AWS datos de recursos

Para los segmentos, el objeto aws contiene información sobre el recurso en el que se ejecuta la aplicación. Se pueden aplicar varios campos a un solo recurso. Por ejemplo, una aplicación que se ejecute en un entorno Docker multicontenedor en Elastic Beanstalk podría tener información sobre la instancia de Amazon EC2, el contenedor de Amazon ECS que se ejecuta en la instancia y el propio entorno de Elastic Beanstalk.

aws (Segmentos)

Todos los campos son opcionales.

  • account_id— Si su aplicación envía segmentos a otra Cuenta de AWS, registre el ID de la cuenta que ejecuta la aplicación.

  • cloudwatch_logs— Matriz de objetos que describen un único grupo de CloudWatch registros.

    • log_group— El nombre del grupo de CloudWatch registros.

    • arn— El ARN del grupo de CloudWatch registros.

  • ec2: información sobre una instancia de Amazon EC2.

    • instance_id: el ID de la instancia de EC2.

    • instance_size: el tipo de la instancia de EC2.

    • ami_id: el ID de imagen de máquina de Amazon.

    • availability_zone: la zona de disponibilidad en la que se ejecuta la instancia.

  • ecs: información sobre un contenedor de Amazon ECS.

    • container: el nombre de host de su contenedor.

    • container_id: el ID completo de su contenedor.

    • container_arn: el ARN de su instancia de contenedor.

  • eks: la información acerca de un clúster de Amazon EKS.

    • pod: el nombre de host de su pod de EKS.

    • cluster_name: el nombre del clúster de EKS.

    • container_id: el ID completo de su contenedor.

  • elastic_beanstalk: información sobre un entorno de Elastic Beanstalk. Puede encontrar esta información en un archivo denominado /var/elasticbeanstalk/xray/environment.conf en las plataformas más recientes de Elastic Beanstalk.

    • environment_name: el nombre del entorno.

    • version_label: el nombre de la versión de la aplicación que está implementada actualmente en la instancia que ha atendido la solicitud.

    • deployment_id: número que indica el ID de la última implementación satisfactoria en la instancia que ha atendido la solicitud.

  • xray: metadatos sobre el tipo y la versión de la instrumentación utilizada.

    • auto_instrumentation: booleano que indica si se utilizó la instrumentación automática (por ejemplo, el agente Java).

    • sdk_version. La versión del SDK o del agente que se está utilizando.

    • sdk: el tipo de SDK.

ejemplo AWS bloquear con complementos
"aws":{
   "elastic_beanstalk":{
      "version_label":"app-5a56-170119_190650-stage-170119_190650",
      "deployment_id":32,
      "environment_name":"scorekeep"
   },
   "ec2":{
      "availability_zone":"us-west-2c",
      "instance_id":"i-075ad396f12bc325a",
      "ami_id":
   },
   "cloudwatch_logs":[
      {
         "log_group":"my-cw-log-group",
         "arn":"arn:aws:logs:us-west-2:012345678912:log-group:my-cw-log-group"
      }
   ],
   "xray":{
      "auto_instrumentation":false,
      "sdk":"X-Ray for Java",
      "sdk_version":"2.8.0"
   }
}

En el caso de los subsegmentos, registre la información sobre Servicios de AWS los recursos a los que accede su aplicación. X-Ray utiliza esta información para crear segmentos inferidos que representan los servicios posteriores del mapa de servicio.

aws (subsegmentos)

Todos los campos son opcionales.

  • operation— El nombre de la acción de API invocada contra un recurso Servicio de AWS o.

  • account_id— Si su aplicación accede a los recursos de una cuenta diferente o envía segmentos a una cuenta diferente, registre el ID de la cuenta propietaria del AWS recurso al que accedió la aplicación.

  • region: si el recurso está en una región diferente a la de la aplicación, este campo registra la región. Por ejemplo, us-west-2.

  • request_id: un identificador único para la solicitud.

  • queue_url: para las operaciones incluidas en una cola de Amazon SQS, la dirección URL de la cola.

  • table_name: para las operaciones de una tabla de DynamoDB, el nombre de la tabla.

ejemplo 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",
  }
}

Errores y excepciones

Cuando se produzca un error, puede registrar información sobre el error y las excepciones que se generan. Registre los errores en los segmentos cuando la aplicación devuelva un error al usuario, y en los subsegmentos cuando una llamada posterior devuelva un error.

tipos de error

Establezca uno o varios de los campos siguientes en true para indicar que se ha producido un error. Se pueden aplicar varios tipos si se trata de errores compuestos. Por ejemplo, un error 429 Too Many Requests de una llamada posterior podría hacer que la aplicación devolviera un error 500 Internal Server Error, en cuyo caso se aplicarían los tres tipos.

  • error: booleano que indica que se ha producido un error del cliente (el código de estado de la respuesta fue 4XX Client Error).

  • throttle: booleano que indica que se ha limitado una solicitud (el código de estado de la respuesta fue 429 Too Many Requests).

  • fault: booleano que indica que se ha producido un error del servidor (el código de estado de la respuesta fue 5XX Server Error).

Indique la causa del error incluyendo un objeto cause en el segmento o subsegmento.

cause

Una causa puede ser un ID de excepción de 16 caracteres o un objeto con los siguientes campos:

  • working_directory: la ruta completa del directorio de trabajo donde se produjo la excepción.

  • paths: la matriz de rutas a las bibliotecas o módulos que se estaban usando cuando se produjo la excepción.

  • exceptions: la matriz de objetos exception.

Incluya información detallada sobre el error en uno o varios objetos exception.

exception

Todos los campos son opcionales.

  • id: un identificador de 64 bits para la excepción, único entre otros segmentos del mismo rastro, en 16 dígitos hexadecimales.

  • message: el mensaje de excepción.

  • type: el tipo de excepción.

  • remote: booleano que indica que la excepción se produjo por un error devuelto por un servicio posterior.

  • truncated: entero que indica el número de marcos de pila que se han omitido de stack.

  • skipped: entero que indica el número de excepciones que se omitieron entre esta excepción y su excepción secundaria, es decir, la excepción que la ha causado.

  • cause: ID de excepción del elemento principal de la excepción, es decir, la excepción que provocó esta excepción.

  • stack: matriz de objetos stackFrame.

Si está disponible, registre la información acerca de la pila de llamada en objetos stackFrame.

stackFrame

Todos los campos son opcionales.

  • path: la ruta relativa al archivo.

  • line: la línea dentro del archivo.

  • label: el nombre de la función o método.

Consultas SQL

Puede crear subsegmentos para las consultas que la aplicación realiza en una base de datos SQL.

sql

Todos los campos son opcionales.

  • connection_string: para SQL Server u otras conexiones de base de datos que no usen cadenas de conexión URL, este campo registra la cadena de conexión, sin incluir las contraseñas.

  • url: para una conexión a la base de datos que utilice una cadena de conexión URL, este campo registra la dirección URL, sin incluir las contraseñas.

  • sanitized_query: la consulta a la base de datos, con todos los valores proporcionados por el usuario eliminados o reemplazados con un marcador de posición.

  • database_type: el nombre del motor de base de datos.

  • database_version: el número de versión del motor de base de datos.

  • driver_version: el nombre y número de versión del controlador del motor de base de datos que usa la aplicación.

  • user: el nombre de usuario de la base de datos.

  • preparation: call si la consulta utiliza un PreparedCall; statement si la consulta utiliza un PreparedStatement.

ejemplo Subsegmento con una consulta SQL
{
  "id": "3fd8634e78ca9560",
  "start_time": 1484872218.696,
  "end_time": 1484872218.697,
  "name": "ebdb@aawijb5u25wdoy.cpamxznpdoq8.us-west-2.rds.amazonaws.com",
  "namespace": "remote",
  "sql" : {
    "url": "jdbc:postgresql://aawijb5u25wdoy.cpamxznpdoq8.us-west-2.rds.amazonaws.com:5432/ebdb",
    "preparation": "statement",
    "database_type": "PostgreSQL",
    "database_version": "9.5.4",
    "driver_version": "PostgreSQL 9.4.1211.jre7",
    "user" : "dbuser",
    "sanitized_query" : "SELECT  *  FROM  customers  WHERE  customer_id=?;"
  }
}