tracing: xray annotation documentation and CODEOWNER (envoyproxy#35257)

Signed-off-by: Nigel Brittain <[email protected]> Signed-off-by: Nigel Brittain <[email protected]> Signed-off-by: asingh-g <[email protected]>
asingh-g · Aug 20, 2024 · 0295a14 · 0295a14
1 parent 32edb07
commit 0295a14
Show file tree

Hide file tree

Showing 2 changed files with 60 additions and 1 deletion.
diff --git a/CODEOWNERS b/CODEOWNERS
@@ -62,7 +62,7 @@ extensions/filters/common/original_src @klarose @mattklein123
 # tracers.datadog extension
 /*/extensions/tracers/datadog @dmehala @mattklein123
 # tracers.xray extension
-/*/extensions/tracers/xray @suniltheta @mattklein123
+/*/extensions/tracers/xray @suniltheta @mattklein123 @nbaws
 # tracers.skywalking extension
 /*/extensions/tracers/skywalking @wbpcode @Shikugawa
 # tracers.opentelemetry extension

diff --git a/api/envoy/config/trace/v3/xray.proto b/api/envoy/config/trace/v3/xray.proto
@@ -21,6 +21,65 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE;
 
 // [#protodoc-title: AWS X-Ray Tracer Configuration]
 // Configuration for AWS X-Ray tracer
+//
+// The X-Ray tracer will automatically attach :ref:`custom_tags <envoy_v3_api_field_extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.Tracing.custom_tags>` as annotations to the span. (See: `Annotations <https://docs.aws.amazon.com/xray/latest/devguide/xray-concepts.html#xray-concepts-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:
+//
+// .. code-block:: json
+//
+//   {
+//     "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"
+//           }
+//         }
+//       }
+//     ]
+//   }
+//
 
 // [#extension: envoy.tracers.xray]
 message XRayConfig {