Campos de segmento Subsegmentos Dados HTTP de solicitação Anotações Metadados AWS dados de recursos Erros e exceções Consultas SQL

AWS X-Ray documentos do segmento

Um segmento de rastreamento é uma representação JSON de uma solicitação que seu aplicativo atende. Um segmento de rastreamento registra informações sobre a solicitação original, informações sobre o trabalho que seu aplicativo faz localmente e subsegmentos com informações sobre chamadas downstream que seu aplicativo faz para AWS recursos, APIs HTTP e bancos de dados SQL.

Um documento de segmentos transmite informações sobre um segmento ao X-Ray. Um documento de segmentos pode ser até 64 kB e conter um segmento inteiro com subsegmentos, um fragmento de um segmento que indica que uma solicitação está em andamento ou um único subsegmento enviado separadamente. Você pode enviar documentos de segmentos diretamente ao X-Ray usando a API PutTraceSegments.

O X-Ray compila e processa documentos de segmentos para gerar resumos de rastreamento e rastreamentos completos, os quais podem ser acessados usando as APIs GetTraceSummaries e BatchGetTraces, respectivamente. Além de segmentos e subsegmentos que você envia ao X-Ray, o serviço usa informações em subsegmentos para gerar segmentos inferidos e os adiciona ao rastreamento completo. Os segmentos inferidos representam serviços e recursos posteriores no mapa de rastreamento.

O X-Ray fornece um esquema JSON para documentos de segmentos. Você pode baixar o esquema aqui: xray-segmentdocument-schema-v1.0.0. Os campos e objetos listados no schema são descritos em mais detalhes nas seções a seguir.

Um subconjunto de campos de segmento é indexado pelo X-Ray para ser usado com expressões de filtro. Por exemplo, se você definir o campo user em um segmento para um identificador exclusivo, poderá pesquisar segmentos associados a usuários específicos no console do X-Ray ou usando a API GetTraceSummaries. Para ter mais informações, consulte Usar expressões de filtro.

Quando você instrumenta a aplicação com o X-Ray SDK, o SDK gera documentos de segmentos para você. Em vez de enviar documentos de segmentos diretamente ao X-Ray, o SDK transmite-os por meio de uma porta UDP local para o daemon do X-Ray. Para obter mais informações, consulte Enviar documentos de segmentos para o daemon do X-Ray.

Campos de segmento

Um segmento registra informações de rastreamento sobre uma solicitação que o seu aplicativo atende. No mínimo, um segmento registra nome, ID, horário de início, ID de rastreamento e horário de término da solicitação.

exemplo Segmento completo mínimo


{
  "name" : "example.com",
  "id" : "70de5b6f19ff9a0a",
  "start_time" : 1.478293361271E9,
  "trace_id" : "1-581cf771-a006649127e371903a2de979",
  "end_time" : 1.478293361449E9
}

Os seguintes campos são obrigatórios ou condicionalmente necessários, por segmento.

nota

Os valores devem ser strings (até 250 caracteres), a menos que indicado o contrário.

Campos obrigatórios de segmento

name: o nome lógico do serviço que processou a solicitação, com até 200 caracteres. Por exemplo, o nome do aplicativo ou o nome de domínio. Os nomes podem conter letras unicode, números e espaço em branco e os seguintes símbolos: _, ., :, /, %, &, #, =, +, \, -, @
id: um identificador de 64 bits para o segmento, exclusivo entre segmentos no mesmo rastreamento, em 16 dígitos hexadecimais.
trace_id: um identificador exclusivo que conecta todos os segmentos e subsegmentos provenientes de uma única solicitação do cliente.
Formato de identificação de rastreamento X-Ray

Um trace_id do X-Ray consiste em três números separados por hifens. Por exemplo, 1-58406520-a006649127e371903a2de979. Isso inclui:
- O número da versão, que é1.
- A hora da solicitação original no Unix epoch time usando 8 dígitos hexadecimais.
  
  Por exemplo, às 10h de 1º de dezembro de 2016 PST em tempo de época é de 1480615200 segundos ou 58406520 em dígitos hexadecimais.
- Um identificador globalmente exclusivo de 96 bits para o rastreamento em 24 dígitos hexadecimais.
nota
O X-Ray agora suporta IDs de rastreamento que são criados usando OpenTelemetry qualquer outra estrutura que esteja em conformidade com a especificação W3C Trace Context. Um ID de rastreamento do W3C deve ser formatado no formato X-Ray trace ID ao ser enviado para o X-Ray. Por exemplo, o ID de rastreamento do W3C 4efaaf4d1e8720b39541901950019ee5 deve ser formatado como 1-4efaaf4d-1e8720b39541901950019ee5 quando enviado para o X-Ray. Os IDs de rastreamento do X-Ray incluem a data e hora da solicitação original no Unix epoch time, mas isso não é necessário ao enviar IDs de rastreamento do W3C no formato X-Ray.

Segurança de ID de Rastreamento
IDs de rastreamento são visíveis nos cabeçalhos de resposta. Gere IDs de rastreamento com um algoritmo aleatório seguro para garantir que invasores não possam calcular futuras IDs de rastreamento e enviar solicitações com aqueles IDs para seu aplicativo.
start_time: um número que representa o momento em que o segmento foi criado, em segundos de ponto flutuante na hora de época. Por exemplo, o 1480615200.010 ou o 1.480615200010E9. Use o máximo de casas decimais que precisar. A resolução em microssegundos é recomendada quando disponível.
end_time: um número que representa o momento em que o segmento foi encerrado. Por exemplo, o 1480615200.090 ou o 1.480615200090E9. Especifique um end_time ou in_progress.
in_progress: um valor booliano, definido como true, em vez de especificar um end_time para registrar que um segmento foi iniciado e não foi concluído. Envie um segmento em andamento quando seu aplicativo receber uma solicitação que levará muito tempo para atender, para rastrear o recebimento da solicitação. Quando a resposta é encaminhada, envie o segmento completo para substituir o segmento em andamento. Envie apenas um segmento completo e um ou nenhum segmento em andamento, por solicitação.

Nomes de serviço

O name de um segmento deve corresponder ao nome de domínio ou nome lógico do serviço que gera o segmento. No entanto, isso não é aplicado. Qualquer aplicação que tenha permissão para PutTraceSegments pode enviar segmentos com qualquer nome.

Os seguintes campos são opcionais para segmentos.

Campos opcionais de segmento

service: um objeto com informações sobre a aplicação.
- version: uma string que identifica a versão da aplicação que atendeu à solicitação.
user: uma string que identifica o usuário que enviou a solicitação.
origin— O tipo de AWS recurso que executa seu aplicativo.
Valores suportados
- AWS::EC2::Instance: uma instância do Amazon EC2.
- AWS::ECS::Container: um contêiner do Amazon ECS.
- AWS::ElasticBeanstalk::Environment: um ambiente do Elastic Beanstalk.
Quando vários valores são aplicáveis à sua aplicação, use o que é mais específico. Por exemplo, um ambiente do Docker de vários contêineres no Elastic Beanstalk executa a aplicação em um contêiner do Amazon ECS, que, por sua vez, é executado em uma instância do Amazon EC2. Neste caso, você define a origem para AWS::ElasticBeanstalk::Environment como o ambiente pai dos outros dois recursos.
parent_id: um ID de subsegmento que você especifica se a solicitação tiver se originado de uma aplicação instrumentada. O X-Ray SDK adiciona a ID do subsegmento principal ao cabeçalho de rastreamento para chamadas HTTP subsequentes. No caso de subsegmentos aninhados, um subsegmento pode ter um segmento ou um subsegmento como seu pai.
http: objetos http com informações sobre a solicitação HTTP original.
aws— awsobjeto com informações sobre o AWS recurso no qual seu aplicativo atendeu à solicitação.
error, throttle, fault e cause: campos de erro que indicam um erro ocorrido e que incluem informações sobre a exceção que causou o erro.
annotations: o objeto annotations com os pares de chave-valor que você deseja que o X-Ray indexe para pesquisa.
metadata: objeto metadata com qualquer dado adicional que você deseja armazenar no segmento.
subsegments: matriz de objetos subsegment.

Subsegmentos

Você pode criar subsegmentos para registrar chamadas Serviços da AWS e recursos que você faz com o AWS SDK, chamadas para APIs Web HTTP internas ou externas ou consultas ao banco de dados SQL. Você também pode criar subsegmentos para depurar ou anotar blocos de código em seu aplicativo. Subsegmentos podem conter outros subsegmentos, portanto, um subsegmento personalizado que registra metadados sobre uma chamada de função interna pode conter outros subsegmentos personalizados e subsegmentos para chamadas de downstream.

Um subsegmento registra uma chamada subsequente do ponto de vista do serviço que faz a chamada. O X-Ray usa subsegmentos para identificar serviços subsequentes que não enviam segmentos e criam entradas para eles no gráfico de serviço.

Um subsegmento pode ser incorporado em um documento de segmento completo ou enviado de forma independente. Envie subsegmentos separadamente para chamadas downstream de rastreamento de forma assíncrona para solicitações de longo prazo, ou para evitar exceder o tamanho máximo do documento de segmento.

exemplo Segmento com subsegmento incorporado

Um subsegmento independente tem um type de subsegment e uma parent_id que identifica o segmento pai.


{
  "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
        }
      }
    }
  ]
}

Para solicitações de longa duração, você pode enviar um segmento em andamento para notificar o X-Ray de que a solicitação foi recebida e, em seguida, enviar subsegmentos separadamente para rastreá-los antes de concluir a solicitação original.

exemplo Segmento em andamento


{
  "name" : "example.com",
  "id" : "70de5b6f19ff9a0b",
  "start_time" : 1.478293361271E9,
  "trace_id" : "1-581cf771-a006649127e371903a2de979",
  "in_progress": true
}

exemplo Subsegmento independente

Um subsegmento independente tem um type de subsegment, um trace_id e um parent_id que identifica o segmento pai.


{
  "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
      }
  }
}

Quando a solicitação for concluída, feche o segmento reenviando-o com um end_time. O segmento completo substituirá o segmento em andamento.

Você também pode enviar subsegmentos separadamente para solicitações concluídas que acionaram fluxos de trabalho assíncronos. Por exemplo, uma API da Web pode retornar uma resposta OK 200 imediatamente antes de iniciar o trabalho que o usuário solicitou. Você pode enviar um segmento completo para o X-Ray assim que a resposta for enviada e, depois, subsegmentos para o trabalho concluído em um momento posterior. Assim como ocorre com segmentos, você também pode enviar um fragmento de subsegmento para registrar que o subsegmento foi iniciado e, em seguida, sobregravá-lo com um subsegmento completo assim que a chamada de downstream for concluída.

Os seguintes campos são obrigatórios ou condicionalmente necessários, por subsegmento.

nota

Os valores são strings de até 250 caracteres, a menos que indicado o contrário.

Campos obrigatórios de subsegmento

id: um identificador de 64 bits para o subsegmento, exclusivo entre segmentos no mesmo rastreamento, com 16 dígitos hexadecimais.
name: o nome lógico do subsegmento. Para chamadas de downstream, nomeie o subsegmento após o recurso ou serviço chamado. Para subsegmentos personalizados, nomeie o subsegmento depois do código que ele instrumenta (por exemplo, um nome de função).
start_time: um número que representa o momento em que o subsegmento foi criado, em segundos de ponto flutuante no horário de época, com precisão de milissegundos. Por exemplo, o 1480615200.010 ou o 1.480615200010E9.
end_time: um número que representa o momento em que o subsegmento foi encerrado. Por exemplo, o 1480615200.090 ou o 1.480615200090E9. Especifique um end_time ou in_progress.
in_progress: um valor booliano, definido como true, em vez de especificar um end_time para registrar que um subsegmento foi iniciado e não foi concluído. Envie apenas um subsegmento completo e um ou nenhum subsegmento em andamento, por solicitação de downstream.
trace_id: ID de rastreamento do segmento principal do subsegmento. Obrigatório apenas ao enviar um subsegmento separadamente.
Formato de identificação de rastreamento X-Ray

Um trace_id do X-Ray consiste em três números separados por hifens. Por exemplo, 1-58406520-a006649127e371903a2de979. Isso inclui:
- O número da versão, que é1.
- A hora da solicitação original no Unix epoch time usando 8 dígitos hexadecimais.
  
  Por exemplo, às 10h de 1º de dezembro de 2016 PST em tempo de época é de 1480615200 segundos ou 58406520 em dígitos hexadecimais.
- Um identificador globalmente exclusivo de 96 bits para o rastreamento em 24 dígitos hexadecimais.
nota
O X-Ray agora suporta IDs de rastreamento que são criados usando OpenTelemetry qualquer outra estrutura que esteja em conformidade com a especificação W3C Trace Context. Um ID de rastreamento do W3C deve ser formatado no formato X-Ray trace ID ao ser enviado para o X-Ray. Por exemplo, o ID de rastreamento do W3C 4efaaf4d1e8720b39541901950019ee5 deve ser formatado como 1-4efaaf4d-1e8720b39541901950019ee5 quando enviado para o X-Ray. Os IDs de rastreamento do X-Ray incluem a data e hora da solicitação original no Unix epoch time, mas isso não é necessário ao enviar IDs de rastreamento do W3C no formato X-Ray.
parent_id: ID do segmento principal do subsegmento. Obrigatório apenas ao enviar um subsegmento separadamente. No caso de subsegmentos aninhados, um subsegmento pode ter um segmento ou um subsegmento como seu pai.
type: subsegment. Obrigatório apenas ao enviar um subsegmento separadamente.

Os seguintes campos são opcionais para subsegmentos.

Campos opcionais de subsegmento

namespace: aws para chamadas de SDK da AWS; remote para outras chamadas subsequentes.
http: objeto http com informações sobre uma chamada HTTP de saída.
aws— awsobjeto com informações sobre o AWS recurso downstream que seu aplicativo chamou.
error, throttle, fault e cause: campos de erro que indicam um erro ocorrido e que incluem informações sobre a exceção que causou o erro.
annotations: o objeto annotations com os pares de chave-valor que você deseja que o X-Ray indexe para pesquisa.
metadata: objeto metadata com qualquer dado adicional que você deseja armazenar no segmento.
subsegments: matriz de objetos subsegment.
precursor_ids: matriz de IDs de subsegmentos que identifica subsegmentos com o mesmo pai que foram concluídos antes deste subsegmento.

Dados HTTP de solicitação

Use um bloco HTTP para registrar detalhes sobre uma solicitação HTTP que seu aplicativo atendeu (em um segmento) ou que seu aplicativo realizou para uma API HTTP downstream (em um subsegmento). A maioria dos campos deste objeto são mapeados para informações encontrados em uma solicitação e uma resposta HTTP.

`http`

Todos os campos são opcionais.

request: informações sobre uma solicitação.
- method: o método de solicitação. Por exemplo, GET.
- url: o URL completo da solicitação, compilado com base no protocolo, no nome do host e no caminho da solicitação.
- user_agent: a string do agente de usuário do cliente do solicitante.
- client_ip: o endereço IP do solicitante. Pode ser recuperado do Source Address do pacote IP ou, para solicitações encaminhadas, a partir de um X-Forwarded-For cabeçalho.
- x_forwarded_for: (apenas para segmentos) um booliano indicando que o client_ip foi lido de um cabeçalho X-Forwarded-For e não é confiável, pois ele pode ter sido falsificado.
- traced: (apenas para subsegmentos) um booliano indicando que a chamada subsequente é para outro serviço rastreado. Se este campo estiver definido como true, o X-Ray considerará o rastreamento como dividido até que o serviço subsequente carregue um segmento com um id que corresponda ao parent_id do subsegmento que contém esse bloco.
response: informações sobre uma resposta.
- status: número inteiro indicando o status HTTP da resposta.
- content_length: número inteiro indicando o tamanho do corpo da resposta em bytes.

Ao instrumentar uma chamada subsequente de API da web, registre um subsegmento com informações sobre a solicitação e a resposta HTTP. O X-Ray usa o subsegmento para gerar um segmento inferido para a API remota.

exemplo Segmento para chamada HTTP servido por um aplicativo em execução no 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
    }
  }

exemplo Subsegmento para uma chamada HTTP downstream


{
  "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
    }
  }
}

exemplo Segmento inferido para uma chamada HTTP de downstream


{
  "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
}

Anotações

Os segmentos e subsegmentos podem incluir um objeto annotations contendo um ou mais campos que o X-Ray indexa para serem usados com expressões de filtro. Os campos podem ter string, número ou valores booleanos (sem objetos ou matrizes). O X-Ray indexa até cinquenta anotações por rastreamento.

exemplo Segmento para chamada HTTP com anotações


{
  "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
    }
  }

As chaves devem ser alfanuméricas para funcionar com filtros. Sublinhado é permitido. Outros símbolos e espaço em branco não são permitidos.

Metadados

Os segmentos e subsegmentos podem incluir um objeto metadata contendo um ou mais campos com valores de qualquer tipo, incluindo objetos e matrizes. O X-Ray não indexa metadados, e os valores podem ser de qualquer tamanho, desde que o documento de segmentos não ultrapasse o tamanho máximo (64 kB). Você pode visualizar os metadados no documento de segmento completo retornado pela API BatchGetTraces. As chaves de campo (debugno exemplo a seguir) que começam com AWS. são reservadas para uso por SDKs e clientes AWS fornecidos.

exemplo Subsegmento personalizado com metadados


{
  "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 dados de recursos

Para segmentos, o objeto aws contém informações sobre o recurso no qual seu aplicativo é executado. Vários campos podem ser aplicados a um único recurso. Por exemplo, uma aplicação em execução em um ambiente do Docker de vários contêineres no Elastic Beanstalk poderia ter informações sobre a instância do Amazon EC2, o contêiner do Amazon ECS em execução na instância e o próprio ambiente do Elastic Beanstalk.

`aws` (Segmentos)

Todos os campos são opcionais.

account_id— Se seu aplicativo enviar segmentos para outro Conta da AWS, registre o ID da conta que executa seu aplicativo.
cloudwatch_logs— Matriz de objetos que descrevem um único grupo de CloudWatch registros.
- log_group— O nome do grupo de CloudWatch registros.
- arn— O ARN do grupo de CloudWatch registros.
ec2: informações sobre uma instância do EC2.
- instance_id: o ID da instância do EC2.
- instance_size: o tipo da instância do EC2.
- ami_id: o ID da imagem de máquina da Amazon.
- availability_zone: a zona de disponibilidade na qual a instância está sendo executada.
ecs: informações sobre um contêiner do Amazon ECS.
- container: o nome do host do contêiner.
- container_id: o ID completo do contêiner.
- container_arn: o ARN da instância de contêiner.
eks: informações sobre um cluster do Amazon EKS.
- pod: o nome do host do pod do EKS.
- cluster_name: o nome do cluster do EKS.
- container_id: o ID completo do contêiner.
elastic_beanstalk: informações sobre um ambiente do Elastic Beanstalk. Você encontra essas informações em um arquivo chamado /var/elasticbeanstalk/xray/environment.conf nas plataformas mais recentes do Elastic Beanstalk.
- environment_name: o nome do ambiente.
- version_label: o nome da versão da aplicação que está implantada no momento na instância que atendeu à solicitação.
- deployment_id: um número que indica o ID da última implantação bem-sucedida na instância que atendeu à solicitação.
xray: metadados sobre o tipo e a versão da instrumentação usada.
- auto_instrumentation: booliano que indica se a instrumentação automática foi usada (por exemplo, o agente do Java).
- sdk_version: a versão do SDK ou do agente que está sendo usada.
- sdk: o tipo de SDK.

exemplo AWS bloquear com plug-ins


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

Para subsegmentos, registre as informações sobre os recursos Serviços da AWS e os quais seu aplicativo acessa. O X-Ray usa essas informações para criar segmentos inferidos que representam os serviços subsequentes no mapa de serviço.

`aws` (Subsegmentos)

Todos os campos são opcionais.

operation— O nome da ação da API invocada em relação a um recurso AWS service (Serviço da AWS) ou.
account_id— Se seu aplicativo acessar recursos em uma conta diferente ou enviar segmentos para uma conta diferente, registre o ID da conta que possui o AWS recurso que seu aplicativo acessou.
region: se o recurso estiver em uma região diferente da aplicação, registre a região. Por exemplo, us-west-2.
request_id: identificador exclusivo da solicitação.
queue_url: para operações em uma fila do Amazon SQS, o URL da fila.
table_name: para operações em uma tabela do DynamoDB, o nome da tabela.

exemplo Subsegmento para uma chamada ao DynamoDB para salvar um item


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

Erros e exceções

Quando ocorrer um erro, você pode registrar detalhes sobre o erro e as exceções que foram gerados. Registre erros em segmentos quando o seu aplicativo retornar um erro para o usuário e em subsegmentos quando uma chamada de downstream retornar um erro.

tipos de erro

Defina um ou mais dos seguintes campos do true para indicar que ocorreu um erro. Vários tipos podem ser aplicados se erros ocorrerem. Por exemplo, um 429 Too Many Requests erro de uma chamada de downstream pode fazer com que seu aplicativo retorne 500 Internal Server Error, caso em que os três tipos são aplicáveis.

error: um booliano indicando a ocorrência de um erro de cliente (o código de status de resposta foi 4XX Erro de cliente).
throttle: um booliano indicando que uma solicitação foi suspensa (o código de status de resposta foi 429 Solicitações em excesso).
fault: um booliano indicando a ocorrência de um erro de servidor (o código de status de resposta foi 5XX Erro de servidor).

Indique a causa do erro, incluindo o objeto da causa no segmento ou subsegmento.

`cause`

Uma causa pode ser um ID de exceção de 16 caracteres ou um objeto com os seguintes campos:

working_directory: o caminho completo do diretório de trabalho quando a exceção ocorreu.
paths: a matriz de caminhos para bibliotecas ou módulos em uso quando a exceção ocorreu.
exceptions: a matriz de objetos de exceção.

Incluir informações detalhadas sobre o erro em um ou mais objetos de exceção.

`exception`

Todos os campos são opcionais.

id: um identificador de 64 bits para a exceção, exclusivo entre segmentos no mesmo rastreamento, com 16 dígitos hexadecimais.
message: a mensagem de exceção.
type: o tipo de exceção.
remote: um booliano indicando que a exceção foi causada por um erro retornado por um serviço subsequente.
truncated: um inteiro indicando o número de estruturas de pilhas que são omitidas da stack.
skipped: um inteiro indicando o número de exceções que foram ignoradas entre essa exceção e a exceção secundária, ou seja, a exceção que ela causou.
cause: o ID da exceção principal, ou seja, a exceção que causou essa exceção.
stack: a matriz de objetos stackFrame.

Se disponíveis, registre informações sobre a pilha de chamadas nos objetos stackFrame.

`stackFrame`

Todos os campos são opcionais.

path: o caminho relativo para o arquivo.
line: a linha no arquivo.
label: a função ou o nome do método.

Consultas SQL

Você pode criar subsegmentos para consultas que seu aplicativo faz em um banco de dados SQL.

`sql`

Todos os campos são opcionais.

connection_string: para o SQL Server ou outras conexões de banco de dados que não usam strings de conexão de URL, registre a string de conexão sem as senhas.
url: para uma conexão de banco de dados que usa uma string de conexão, registre o URL sem as senhas.
sanitized_query: a consulta de banco de dados, com os valores fornecidos pelo usuário removidos ou substituídos por um espaço reservado.
database_type: o nome do mecanismo de banco de dados.
database_version: o número da versão do mecanismo de banco de dados.
driver_version: o nome e o número da versão do driver do mecanismo de banco de dados que a aplicação utiliza.
user: o nome de usuário do banco de dados.
preparation: call se a consulta usou uma PreparedCall; statement se a consulta usou uma PreparedStatement.

exemplo Subsegmento com uma 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=?;"
  }
}

Atenção O Javascript está desativado ou não está disponível no seu navegador.

Para usar a documentação da AWS, o Javascript deve estar ativado. Consulte as páginas de Ajuda do navegador para obter instruções.

Convenções do documento

Amostragem

Conceitos

AWS X-Ray documentos do segmento

Seções

Campos de segmento

exemplo Segmento completo mínimo

nota

Campos obrigatórios de segmento

Formato de identificação de rastreamento X-Ray

nota

Segurança de ID de Rastreamento

Nomes de serviço

Campos opcionais de segmento

Valores suportados

Subsegmentos

exemplo Segmento com subsegmento incorporado

exemplo Segmento em andamento

exemplo Subsegmento independente

nota

Campos obrigatórios de subsegmento

Formato de identificação de rastreamento X-Ray

nota

Campos opcionais de subsegmento

Dados HTTP de solicitação

http

exemplo Segmento para chamada HTTP servido por um aplicativo em execução no Amazon EC2

exemplo Subsegmento para uma chamada HTTP downstream

exemplo Segmento inferido para uma chamada HTTP de downstream

Anotações

exemplo Segmento para chamada HTTP com anotações

Metadados

exemplo Subsegmento personalizado com metadados

AWS dados de recursos

aws (Segmentos)

exemplo AWS bloquear com plug-ins

aws (Subsegmentos)

exemplo Subsegmento para uma chamada ao DynamoDB para salvar um item

Erros e exceções

tipos de erro

cause

exception

stackFrame

Consultas SQL

sql

exemplo Subsegmento com uma consulta SQL

`http`

`aws` (Segmentos)

`aws` (Subsegmentos)

`cause`

`exception`

`stackFrame`

`sql`