Enable to specify annotations property on segment_fields for type.googleapis.com/envoy.config.trace.v3.XRayConfig

[y-isono]

Title: Enable to specify annotations property on segment_fields for type.googleapis.com/envoy.config.trace.v3.XRayConfig

Description: It seems that only origin or aws property can be specified on segment_fields or type.googleapis.com/envoy.config.trace.v3.XRayConfig[1]-[2] now so we would be happy if we can specify annotations on segment_fields[3].

[1] https://github.com/envoyproxy/envoy/blob/3d4e92e2e9d11f3a2c62076bb44fc93e24f878b5/api/envoy/config/trace/v3/xray.proto#L30-L37 [2] https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/trace/v3/xray.proto#extension-envoy-tracers-xray

[3] Use the X-Ray API - Explore the X-Ray API - https://docs.aws.amazon.com/xray/latest/devguide/aws-xray-interface-api.html#xray-api

X-Ray segment documents
・・・
Annotations
・・・
  "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
  },

[nezdolik]

cc @suniltheta @mattklein123

[nbaws]

i'll take a look at this one

[nbaws]

@y-isono The xray tracer will add custom tags as annotations, as well as some other related metadata as annotations. Documentation for configuring custom tags can be found here https://www.envoyproxy.io/docs/envoy/latest/api-v3/type/tracing/v3/custom_tag.proto#envoy-v3-api-msg-type-tracing-v3-customtag

Here is an xray trace I generated, with a single custom tag added:

{
    "Id": "1-6698980d-e829ae270ab34b69b488b098",
    "Duration": 0.016,
    "LimitExceeded": false,
    "Segments": [
        {
            "Id": "15d65e5ced8dfe76",
            "Document": {
                "id": "15d65e5ced8dfe76",
                "name": "envoyfe-test",
                "start_time": 1721276429.410355,
                "trace_id": "1-6698980d-e829ae270ab34b69b488b098",
                "end_time": 1721276429.426068,
                "fault": true,
                "http": {
                    "request": {
                        "url": "http://app2.application.internal/app1",
                        "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": "outbound_proxy",
                    "custom1": "testing",
                    "http.protocol": "HTTP/1.1",
                    "request_size": "0",
                    "downstream_cluster": "-",
                    "direction": "ingress",
                    "upstream_cluster.name": "outbound_proxy"
                }
            }
        }
    ]
}

The custom tag is added using the following configuration (trimmed)

  - name: http_connect
    address:
      socket_address:
        protocol: TCP
        address: 0.0.0.0
        port_value: 8099
    filter_chains:
    - filters:
      - name: envoy.filters.network.http_connection_manager
        typed_config:
          "@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
          stat_prefix: ingress_http
          tracing:
            custom_tags:
              tag: custom1
              literal:
                value: testing
          route_config:
            name: local_route

Given that this took me scouring the source code to work out the behaviour, I think a documentation improvement is in order. I'll add some supporting documentation and you can see if that assists in configuration.

[nbaws]

Please see updated documentation https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/trace/v3/xray.proto.html