Amazon X-Ray 分段文档 - Amazon X-Ray
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 Amazon Web Services 服务入门

本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。

Amazon X-Ray 分段文档

跟踪分段是应用程序提供服务的请求的 JSON 表示形式。跟踪分段将记录有关原始请求的信息、有关应用程序本地执行的工作的信息以及子分段,包含有关应用程序对Amazon资源、HTTP API 和 SQL 数据库。

A分段文档将有关分段的信息传递给 X-Ray。分段文档最多可为 64 kB,并且包含一个带子分段的完整分段、指示请求正在进行中的分段部分或一个单独发送的子分段。您可以 X-Ray 用PutTraceSegmentsAPI。

X-Ray 编译和处理区段文档以生成可查询跟踪摘要完整跟踪,您可以通过使用GetTraceSummariesBatchGetTraces,分别为。除了您发送到 X-Ray 的分段和子分段之外,服务还使用子分段中的信息生成推理分段并将其添加到完整跟踪中。推断的分段表示服务地图中的下游服务和资源。

X-Ray 提供JSON 架构对于分段文档。您可以在此处下载该架构:xray-segmentdocument-schema-v1.0.0。以下部分中更详细地描述了该架构中列出的字段和对象。

分段字段的子集由 X-Ray 编制索引以用于筛选表达式。例如,如果您将user字段设置为唯一标识符,则可在 X-Ray 控制台中搜索与特定用户关联的分段,或使用GetTraceSummariesAPI。有关更多信息,请参阅 使用筛选条件表达式在控制台中搜索跟踪

在使用 X-Ray 开发工具包检测应用程序时,此开发工具包将为您生成分段文档。此开发工具包通过本地 UDP 端口将分段文档传输到X-Ray 守护程序。有关更多信息,请参阅 将区段文档发送到 X-Ray 守护进程

分段字段

分段记录有关应用程序提供服务的请求的跟踪信息。分段至少会记录请求的名称、ID、开始时间、跟踪 ID 和结束时间。

例 最小完成分段

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

分段需要或有条件地需要以下字段。

注意

除非另行说明,否则值必须是字符串 (最多 250 个字符)。

必填分段字段

  • name— 处理请求的服务的逻辑名称(最多为200 个字符。例如,您的应用程序的名称或域名。名称可以包含 Unicode 字母、数字、空格和以下符号:_.:/%&#=+\-@

  • id— 分段的 64 位标识符,在同一个跟踪中的分段之间唯一,在16 位十六进制数字

  • trace_id— 连接源自单个客户端请求的所有分段和子分段的唯一标识符。

    跟踪 ID 格式

    trace_id 由以连字符分隔的三组数字组成。例如:1-58406520-a006649127e371903a2de979。这包括:

    • 版本号,即 1

    • 原始请求的时间,采用 Unix 纪元时间,为 8 个十六进制数字

      例如,2016 年 12 月 1 日上午 10:00 (太平洋标准时间) 采用纪元时间为 1480615200,或者是十六进制数字 58406520

    • 跟踪的 96 位标识符,全局唯一,使用 24 个十六进制数字

    跟踪 ID 安全性

    跟踪 ID 在响应标头中可见。使用安全的随机算法生成跟踪 ID,确保攻击者无法计算未来的跟踪 ID 并使用这些 ID 向您的应用程序发送请求。

  • start_timenumber表示分段的创建时间的时间,采用浮点秒数的纪元时间。例如,1480615200.0101.480615200010E9。使用所需数量的小数位。建议使用微秒解析 (如果可用)。

  • end_timenumber也就是分段的关闭时间的时间。例如,1480615200.0901.480615200090E9。指定 end_timein_progress

  • in_progress布尔值,设置为true,而不是指定end_time以记录分段已经启动但未完成。在您的应用程序接收到需要长时间提供服务的请求时发送进行中的分段,用于跟踪请求接收。发送了响应之后,发送完成分段以覆盖进行中分段。仅为每个请求发送一个完整分段,以及一个或零个进行中分段。

服务名称

分段的name应与生成段的服务的域名或逻辑名称匹配。但是,这不是强制执行的。任何有权限的应用程序PutTraceSegments可以发送任何名称的段。

以下字段是分段的可选字段。

可选分段字段

  • service— 一个包含应用程序的相关信息的对象。

    • version— 一个标识为请求提供服务的应用程序版本的字符串。

  • user— 一个标识发送请求的用户的字符串。

  • origin— 类型Amazon资源运行您的应用程序。

    支持的值

    • AWS::EC2::Instance— Amazon EC2 实例。

    • AWS::ECS::Container— Amazon ECS 容器。

    • AWS::ElasticBeanstalk::Environment— Elastic Beanstalk 环境。

    如果您的应用程序适用多个值,请使用最具体的值。例如,一个多容器 Docker Elastic Beanstalk 环境在一个 Amazon ECS 容器上运行您的应用程序,该容器反过来又在 Amazon EC2 实例上运行。在这种情况下,您应将源设为 AWS::ElasticBeanstalk::Environment,因为环境是另外两种资源的父级。

  • parent_id— 您在请求源自检测的应用程序时指定的子分段 ID。X-Ray 开发工具包将父级分段 ID 添加到跟踪标头用于下游 HTTP 调用。对于嵌套子分段,一个子分段可以有一个分段或一个子分段作为其父级。

  • httphttp对象,包含原始 HTTP 请求的相关信息。

  • awsaws对象,包含有关Amazon资源,应用程序为请求提供服务的资源。

  • errorthrottlefault, 和causeerror字段,指示出现错误并且包含有关导致错误的异常的信息。

  • annotationsannotations对象,包含您希望 X-Ray 为其编制索引以进行搜索的键-值对。

  • metadatametadata对象,包含要存储在分段中的任何附加数据。

  • subsegments数组subsegment对象。

Subsegments

您可以创建子段来记录对Amazon服务和资源使用Amazon开发工具包、对内部或外部 HTTP Web API 的调用或 SQL 数据库查询。您也可以创建子分段来调试应用程序中的代码块或为其添加注释。由于子分段可以包含其他子分段,因此,记录有关内部函数调用的元数据的自定义子分段可以包含其他自定义子分段和下游调用的子分段。

子分段从调用它的服务的角度,记录下游调用。X-Ray 使用子分段来确定未发送分段的下游服务,并在服务图上为其创建条目。

子分段可以嵌入到完整分段文档或者单独发送。对于长时间运行的请求,单独发送子分段以异步跟踪下游调用,或者避免超过最大分段文档大小.

例 带有嵌入式子分段的分段

独立子分段具有 typesubsegment 以及标识父分段的 parent_id

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

对于长时间运行的请求,您可以发送进行中分段来告知 X-Ray 已收到请求,然后在完成原始请求之前单独发送子分段来跟踪这些请求。

例 进行中的分段

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

例 独立子分段

独立子分段具有 typesubsegment,一个 trace_id 和一个标识父分段的 parent_id

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

在请求完成时,请使用 end_time 重新发送分段来关闭分段。完成分段将覆盖进行中分段。

您也可以为触发了异步工作流的已完成请求单独发送子分段。例如,在开始用户请求的工作之前,Web API 可能立即返回 OK 200 响应。您可以在发送响应后立即将完整分段发送到 X-Ray,然后为稍后完成的工作发送子分段。与分段一样,您还可以发送子分段片段来记录子分段已开始,然后在下游调用完成后用一个完整子分段覆盖此子分段。

子分段需要或有条件地需要以下字段。

注意

除非另行说明,否则值是字符串 (最多 250 个字符)。

必填子分段字段

  • id— 子分段的 64 位标识符,在同一个跟踪中的分段之间唯一,在16 位十六进制数字

  • name— 子分段的逻辑名称。对于下游调用,命名调用的资源或服务后的子分段。对于自定义子分段,命名其检测的代码后的子分段 (例如,函数名称)。

  • start_timenumber这是创建子分段的时间,采用浮点秒数的纪元时间,精确到毫秒。例如,1480615200.0101.480615200010E9

  • end_timenumber也就是说子分段的关闭时间的时间。例如,1480615200.0901.480615200090E9。指定 end_timein_progress

  • in_progress布尔值设置为true,而不是指定end_time以记录子分段已经启动但未完成。仅为每个下游请求发送一个完整子分段,以及一个或零个进行中子分段。

  • trace_id— 子分段的父分段的跟踪 ID。仅在单独发送子分段时是必需的。

    跟踪 ID 格式

    trace_id 由以连字符分隔的三组数字组成。例如:1-58406520-a006649127e371903a2de979。这包括:

    • 版本号,即 1

    • 原始请求的时间,采用 Unix 纪元时间,为 8 个十六进制数字

      例如,2016 年 12 月 1 日上午 10:00 (太平洋标准时间) 采用纪元时间为 1480615200,或者是十六进制数字 58406520

    • 跟踪的 96 位标识符,全局唯一,使用 24 个十六进制数字

  • parent_id— 子分段的父分段的分段 ID。仅在单独发送子分段时是必需的。对于嵌套子分段,一个子分段可以有一个分段或一个子分段作为其父级。

  • typesubsegment。 仅在单独发送子分段时是必需的。

以下字段是子分段的可选字段。

可选子分段字段

  • namespaceaws对于 AWS 开发工具包调用,为;remote对于其他下游调用,为。

  • httphttp对象,包含有关传出 HTTP 调用的信息。

  • awsaws对象,包含有关下游信息Amazon资源。

  • errorthrottlefault, 和causeerror字段,指示出现错误并且包含有关导致错误的异常的信息。

  • annotationsannotations对象,包含您希望 X-Ray 为其编制索引以进行搜索的键-值对。

  • metadatametadata对象,包含要存储在分段中的任何附加数据。

  • subsegments数组的subsegment对象。

  • precursor_ids数组子分段 ID,标识在此子分段之前完成的具有相同父级的子分段。

HTTP 请求数据

使用 HTTP 数据块记录有关应用程序提供服务的 HTTP 请求 (在分段中) 或应用程序向下游 HTTP API 发出的 HTTP 请求 (在子分段中) 的详细信息。此对象中的大多数字段将映射到在 HTTP 请求和响应中找到的信息。

http

所有字段都是可选字段。

  • request— 有关请求的信息。

    • method— 请求方法。例如:GET

    • url— 从请求的协议、主机名和路径编译的完整 URL URL。

    • user_agent— 来自请求者客户端的用户代理字符串。

    • client_ip— 请求者的 IP 地址。可从 IP 数据包的 Source Address 或 (对于转发的请求) X-Forwarded-For 标头中检索。

    • x_forwarded_for—(仅限段)布尔值表示client_ip从中读取X-Forwarded-For标头,并且它不可靠,因为它可能是伪造的。

    • traced—(仅限子段)布尔值指示下游调用针对的是另一个跟踪的服务。如果此字段设置为true时,X-Ray 会将跟踪视为已中断,直至下游服务上传一个分段,此分段的时间为parent_id匹配的id包含此块的子段。

  • response— 有关响应的信息。

    • statusnumber指示响应的 HTTP 状态。

    • content_lengthnumber指示响应正文的长度(以字节为单位)。

在检测对下游 Web API 进行的调用时,记录包含有关 HTTP 请求和响应的信息的子分段。X-Ray 使用子分段为远程 API 生成推断分段。

例 由 Amazon EC2 上运行的应用程序提供服务的 HTTP 调用分段

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

例 下游 HTTP 调用的子分段

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

例 下游 HTTP 调用的推断段

{ "id": "168416dc2ea97781", "name": "names.example.com", "trace_id": "1-5880168b-fd5153bb58284b67678aa78c", "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

区段和子区段可以包括annotations对象,此对象包含一个或多个字段,X-Ray 为这些字段编制索引以便用于筛选 字段可以包含字符串、数字或布尔值 (无对象或数组)。每个跟踪最多为 50 个注释编制 X-Ray 索索引。

例 包含注释的 HTTP 调用的分段

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

键必须为字母数字才能用于筛选器。允许使用下划线。不允许使用其他符号和空格。

Metadata

区段和子区段可以包括metadata对象,此对象包含一个或多个字段,此对象包括对象和数组。X-Ray 不会为元数据编制索引,并且值可以是任何大小,前提是分段文档不会超出最大大小 (64 kB)。您可以查看由 BatchGetTraces API 返回的完整分段文档中的元数据。字段键 (debug)开始AWS.保留供Amazon-提供的 SDK 和客户端。

例 带元数据的自定义子段

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

Amazon资源数据

对于分段,aws 对象包含有关应用程序运行于的资源的信息。多个字段可应用于一个资源。例如,运行于 Elastic Beanstalk 上的多容器 Docker 环境中的应用程序包含有关 Amazon EC2 实例、该实例上运行的 Amazon ECS 容器和弹性 Beanstalk 环境本身的信息。

aws (分段)

所有字段都是可选字段。

  • account_id— 如果您的应用程序将数据段发送到其他Amazon帐户,记录运行应用程序的帐户 ID。

  • ecs— 有关 Amazon ECS 容器的信息。

    • container— 运行应用程序的容器 ID。

  • ec2— 有关 EC2 实例的信息。

    • instance_id— EC2 实例的实例 ID。

    • availability_zone— 实例在其中运行的可用区。

    例 Amazon使用插件执行的数据块

    "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" }, "xray": { "sdk": "2.9.0 for Java" } }
  • elastic_beanstalk— 有关 Elastic Beanstalk 环境的信息。您可以在名为/var/elasticbeanstalk/xray/environment.conf在最新的 Elastic Beanstalk 平台上。

    • environment_name – 环境名称。

    • version_label— 当前部署到为请求提供服务的实例的应用程序版本的名称。

    • deployment_idnumber指示针对为请求提供服务的实例的上次成功部署的 ID。

对于子分段,记录有关Amazon服务和资源的应用程序访问。X-Ray 使用此信息来创建推断分段,这些分段表示服务地图中的下游服务。

aws (子分段)

所有字段都是可选字段。

  • operation— 针对一个调用的 API 操作的名称。Amazon服务或资源。

  • account_id— 如果应用程序访问其他账户中的资源,或将分段发送到其他帐户,则记录拥有Amazon应用程序访问的资源。

  • region— 如果资源所在的区域不同于应用程序所在的区域,则记录此区域。例如:us-west-2

  • request_id— 请求的唯一标识符。

  • queue_url— 对于 Amazon SQS 队列上的操作,为队列的 URL。

  • table_name— 对于 DynamoDB 表上的操作,为表的名称。

例 调用 DynamoDB 以保存项目的子段

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

错误和异常

出错时,您可以记录有关该错误及其生成的异常的详细信息。当应用程序将错误返回给用户时,在分段中记录错误;当下游调用返回错误时,在子分段中记录错误。

错误类型

将以下一个或多个字段设置为 true 可指示已发生错误。如果出现复合错误,则多个类型适用。例如,来自下游调用的 429 Too Many Requests 错误可能会导致应用程序返回 500 Internal Server Error,在此情况下,所有三种类型将适用。

  • error布尔值指示出现客户端错误(响应状态代码为 4XX 客户端错误)。

  • throttle布尔值指示请求已受限(响应状态代码为429 请求过多)。

  • fault布尔值指示出现服务器错误(响应状态代码为 5XX 服务器错误)。

通过在分段或子分段中包含 cause 对象来指示错误原因。

cause

原因可以是 16 个字符的异常 ID 或带以下字段的对象:

  • working_directory— 发生异常时的工作目录的完整路径路径路径。

  • paths数组发生异常时所使用的库或模块的路径的数据库路径。

  • exceptions数组exception对象。

包含有关一个或多个 exception 对象中的错误的详细信息。

exception

所有字段均可选,但 id 除外。

  • id— 异常的 64 位标识符,在同一个跟踪中的分段之间唯一,在16 位十六进制数字

  • message— 异常消息。

  • type— 异常类型。

  • remote布尔值指示此异常是由下游服务返回的错误导致的异常。

  • truncatedinteger指示从中忽略的堆栈帧数数。stack

  • skippedinteger指示在此异常与其子异常(此异常导致的异常)之间跳过的异常数。

  • cause— 此异常的父级 (导致此异常的异常 ID)。

  • stack数组stackFrame对象。

如果可用,则记录有关 stackFrame 对象中的调用堆栈的信息。

stackFrame

所有字段都是可选字段。

  • path— 文件的相对路径。

  • line— 文件中的行。

  • label— 函数或方法名称。

SQL 查询

您可以为应用程序向 SQL 数据库发出的查询创建子分段。

sql

所有字段都是可选字段。

  • connection_string— 对于 SQL Server 连接或不使用 URL 连接字符串的其他数据库连接,记录连接字符串 (不包括密码)。

  • url— 对于使用 URL 连接字符串的数据库连接,记录 URL (不包括密码)。

  • sanitized_query— 数据库查询,其任何用户提供的值已删除或由占位符替换。

  • database_type— 数据库引擎的名称。

  • database_version— 数据库引擎的版本号。

  • driver_version— 应用程序使用的数据库引擎驱动程序的名称和版本号。

  • user— 数据库用户名。

  • preparationcall如果查询使用PreparedCallstatement如果查询使用PreparedStatement

例 具有 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=?;" } }