tracing: xray annotation documentation and CODEOWNER (#35257)

Signed-off-by: Nigel Brittain <nbaws@amazon.com>
Signed-off-by: Nigel Brittain <108375408+nbaws@users.noreply.github.com>

Mirrored from https://github.com/envoyproxy/envoy @ bd2840815d6e8c7eafc17726c916a5d46660c738

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 {