.. _envoy_v3_api_file_envoy/config/trace/v3/xray.proto:

AWS X-Ray Tracer Configuration (proto)
======================================


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





.. _envoy_v3_api_msg_config.trace.v3.XRayConfig:

config.trace.v3.XRayConfig
--------------------------


:repo:`[config.trace.v3.XRayConfig proto] <api/envoy/config/trace/v3/xray.proto#L84>`


.. _extension_envoy.tracers.xray:

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:


  - :ref:`envoy.tracers <extension_category_envoy.tracers>`



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



  - :ref:`type.googleapis.com/envoy.config.trace.v3.XRayConfig <envoy_v3_api_msg_config.trace.v3.XRayConfig>`




.. code-block:: json
  :force:

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

.. _envoy_v3_api_field_config.trace.v3.XRayConfig.daemon_endpoint:


daemon_endpoint
  (:ref:`config.core.v3.SocketAddress <envoy_v3_api_msg_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.


.. _envoy_v3_api_field_config.trace.v3.XRayConfig.segment_name:


segment_name
  (`string <https://developers.google.com/protocol-buffers/docs/proto#scalar>`_, *REQUIRED*) The name of the X-Ray segment.


.. _envoy_v3_api_field_config.trace.v3.XRayConfig.sampling_rule_manifest:


sampling_rule_manifest
  (:ref:`config.core.v3.DataSource <envoy_v3_api_msg_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
  <https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-go-configuration.html#xray-sdk-go-configuration-sampling>`_


.. _envoy_v3_api_field_config.trace.v3.XRayConfig.segment_fields:


segment_fields
  (:ref:`config.trace.v3.XRayConfig.SegmentFields <envoy_v3_api_msg_config.trace.v3.XRayConfig.SegmentFields>`) Optional custom fields to be added to each trace segment.
  see: `X-Ray Segment Document documentation
  <https://docs.aws.amazon.com/xray/latest/devguide/xray-api-segmentdocuments.html>`__


.. _envoy_v3_api_msg_config.trace.v3.XRayConfig.SegmentFields:

config.trace.v3.XRayConfig.SegmentFields
----------------------------------------


:repo:`[config.trace.v3.XRayConfig.SegmentFields proto] <api/envoy/config/trace/v3/xray.proto#L88>`




.. code-block:: json
  :force:

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

.. _envoy_v3_api_field_config.trace.v3.XRayConfig.SegmentFields.origin:


origin
  (`string <https://developers.google.com/protocol-buffers/docs/proto#scalar>`_) The type of AWS resource, e.g. "AWS::AppMesh::Proxy".


.. _envoy_v3_api_field_config.trace.v3.XRayConfig.SegmentFields.aws:


aws
  (`Struct <https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#struct>`_) AWS resource metadata dictionary.
  See: `X-Ray Segment Document documentation <https://docs.aws.amazon.com/xray/latest/devguide/xray-api-segmentdocuments.html#api-segmentdocuments-aws>`__