AWS X-Ray Tracer Configuration (proto)

Configuration for AWS X-Ray tracer

The X-Ray tracer will automatically attach custom_tags as annotations to the span. (See: Annotations.)

AWS X-Ray trace annotations are also created by the tracing subsystem automatically based on metadata provided during creation of a span.

An example X-Ray trace span that is generated by the envoy trace subsystem is as follows:

{
  "Id": "1-6698980d-e829ae270ab34b69b488b098",
  "Duration": 0.016,
  "LimitExceeded": false,
  "Segments":
  [
    {
      "Id": "15d65e5ced8dfe76",
      "Document":
      {
        "id": "15d65e5ced8dfe76",
        "name": "envoy-example",
        "start_time": 1721276429.410355,
        "trace_id": "1-6698980d-e829ae270ab34b69b488b098",
        "end_time": 1721276429.426068,
        "fault": true,
        "http":
        {
          "request":
          {
            "url": "http://example/path",
            "method": "GET",
            "user_agent": "curl/8.5.0",
            "client_ip": "127.0.0.1",
            "x_forwarded_for": false
          },
          "response":
          {
            "status": 503,
            "content_length": 216
          }
        },
        "aws": {},
        "annotations":
        {
          "response_flags": "UF",
          "component": "proxy",
          "upstream_cluster": "upstream_cluster",
          "annotation_from_custom_tag": "example",
          "http.protocol": "HTTP/1.1",
          "request_size": "0",
          "downstream_cluster": "-",
          "direction": "ingress",
          "upstream_cluster.name": "upstream_cluster"
        }
      }
    }
  ]
}

config.trace.v3.XRayConfig

[config.trace.v3.XRayConfig proto]

This extension has the qualified name envoy.tracers.xray

Note

This extension is intended to be robust against untrusted downstream traffic. It assumes that the upstream is trusted.

Tip

This extension extends and can be used with the following extension category:

envoy.tracers

This extension must be configured with one of the following type URLs:

type.googleapis.com/envoy.config.trace.v3.XRayConfig

{
  "daemon_endpoint": {...},
  "segment_name": ...,
  "sampling_rule_manifest": {...},
  "segment_fields": {...}
}

daemon_endpoint: (config.core.v3.SocketAddress) The UDP endpoint of the X-Ray Daemon where the spans will be sent. If this value is not set, the default value of 127.0.0.1:2000 will be used.

segment_name: (string, REQUIRED) The name of the X-Ray segment.

sampling_rule_manifest: (config.core.v3.DataSource) The location of a local custom sampling rules JSON file. For an example of the sampling rules see: X-Ray SDK documentation

segment_fields: (config.trace.v3.XRayConfig.SegmentFields) Optional custom fields to be added to each trace segment. see: X-Ray Segment Document documentation

config.trace.v3.XRayConfig.SegmentFields

[config.trace.v3.XRayConfig.SegmentFields proto]

{
  "origin": ...,
  "aws": {...}
}

origin: (string) The type of AWS resource, e.g. “AWS::AppMesh::Proxy”.

aws: (Struct) AWS resource metadata dictionary. See: X-Ray Segment Document documentation