.. _arch_overview_attributes:

Attributes

Attributes refer to contextual properties provided by Envoy during request and connection processing. They are named by a dot-separated path (e.g. request.path), have a fixed type (e.g. string or int), and may be absent or present depending on the context. Attributes are exposed to CEL runtime in :ref:RBAC filter <arch_overview_rbac>, as well as Wasm extensions via get_property ABI method.

Attribute value types are limited to:

string for UTF-8 strings
bytes for byte buffers
int for 64-bit signed integers
uint for 64-bit unsigned integers
bool for booleans
list for lists of values
map for associative arrays with string keys
timestamp for timestamps as specified by Timestamp <https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#timestamp>_
duration for durations as specified by Duration <https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#duration>_
Protocol buffer message types

CEL provides standard helper functions for operating on abstract types such as getMonth for timestamp values. Note that integer literals (e.g. 7) are of type int, which is distinct from uint (e.g. 7u), and the arithmetic conversion is not automatic (use uint(7) for explicit conversion).

Wasm extensions receive the attribute values as a serialized buffer according to the type of the attribute. Strings and bytes are passed as-is, integers are passed as 64 bits directly, timestamps and durations are approximated to nano-seconds, and structured values are converted to a sequence of pairs recursively.

.. _arch_overview_request_attributes:

Request attributes

The following request attributes are generally available upon initial request processing, which makes them suitable for RBAC policies.

request.* attributes are only available in http filters.

.. csv-table:: :header: Attribute, Type, Description :escape: ' :widths: 1, 1, 4

request.path, string, The path portion of the URL request.url_path, string, The path portion of the URL without the query string request.host, string, The host portion of the URL request.scheme, string, The scheme portion of the URL e.g. "http" request.method, string, Request method e.g. "GET" request.headers, "map<string, string>", All request headers indexed by the lower-cased header name request.headers_bytes, int, Total size of request headers in bytes request.referer, string, Referer request header request.useragent, string, User agent request header request.time, timestamp, Time of the first byte received request.id, string, Request ID corresponding to x-request-id header value request.protocol, string, "Request protocol ('"HTTP/1.0'", '"HTTP/1.1'", '"HTTP/2'", or '"HTTP/3'")" request.query, string, The query portion of the URL in the format of "name1=value1&name2=value2".

Header values in request.headers associative array are comma-concatenated in case of multiple values.

Additional attributes are available once the request completes:

.. csv-table:: :header: Attribute, Type, Description :widths: 1, 1, 4

request.duration, duration, Total duration of the request request.size, int, Size of the request body. Content length header is used if available. request.total_size, int, Total size of the request including the approximate uncompressed size of the headers

Response attributes

Response attributes are only available after the request completes.

response.* attributes are only available in http filters.

.. csv-table:: :header: Attribute, Type, Description :widths: 1, 1, 4

response.code, int, Response HTTP status code response.code_details, string, Internal response code details (subject to change) response.flags, int, Additional details about the response beyond the standard response code encoded as a bit-vector response.grpc_status, int, Response gRPC status code response.headers, "map<string, string>", All response headers indexed by the lower-cased header name response.headers_bytes, int, Total size of response headers in bytes response.trailers, "map<string, string>", All response trailers indexed by the lower-cased trailer name response.size, int, Size of the response body response.total_size, int, Total size of the response including the approximate uncompressed size of the headers and the trailers response.backend_latency, duration, Duration between the first byte sent to and the last byte received from the upstream backend

Connection attributes

The following attributes are available once the downstream connection is established (which also applies to HTTP requests making them suitable for RBAC):

.. csv-table:: :header: Attribute, Type, Description :widths: 1, 1, 4

source.address, string, Downstream connection remote address source.port, int, Downstream connection remote port destination.address, string, Downstream connection local address destination.port, int, Downstream connection local port connection.id, uint, Downstream connection ID connection.mtls, bool, Indicates whether TLS is applied to the downstream connection and the peer ceritificate is presented connection.requested_server_name, string, Requested server name in the downstream TLS connection connection.tls_version, string, TLS version of the downstream TLS connection connection.subject_local_certificate, string, The subject field of the local certificate in the downstream TLS connection connection.subject_peer_certificate, string, The subject field of the peer certificate in the downstream TLS connection connection.dns_san_local_certificate, string, The first DNS entry in the SAN field of the local certificate in the downstream TLS connection connection.dns_san_peer_certificate, string, The first DNS entry in the SAN field of the peer certificate in the downstream TLS connection connection.uri_san_local_certificate, string, The first URI entry in the SAN field of the local certificate in the downstream TLS connection connection.uri_san_peer_certificate, string, The first URI entry in the SAN field of the peer certificate in the downstream TLS connection connection.sha256_peer_certificate_digest, string, SHA256 digest of the peer certificate in the downstream TLS connection if present connection.peer_certificate, string, PEM-encoded peer certificate in the downstream TLS connection if present connection.transport_failure_reason, string, The transport failure reason e.g. certificate validation failed

The following additional attributes are available upon the downstream connection termination:

.. csv-table:: :header: Attribute, Type, Description :widths: 1, 1, 4

connection.termination_details, string, Internal termination details of the connection (subject to change)

Upstream attributes

The following attributes are available once the upstream connection is established:

.. csv-table:: :header: Attribute, Type, Description :widths: 1, 1, 4

upstream.address, string, Upstream connection remote address upstream.num_endpoints, uint64, the number of endpoints of the upstream cluster. upstream.port, int, Upstream connection remote port upstream.tls_version, string, TLS version of the upstream TLS connection upstream.subject_local_certificate, string, The subject field of the local certificate in the upstream TLS connection upstream.subject_peer_certificate, string, The subject field of the peer certificate in the upstream TLS connection upstream.dns_san_local_certificate, string, The first DNS entry in the SAN field of the local certificate in the upstream TLS connection upstream.dns_san_peer_certificate, string, The first DNS entry in the SAN field of the peer certificate in the upstream TLS connection upstream.uri_san_local_certificate, string, The first URI entry in the SAN field of the local certificate in the upstream TLS connection upstream.uri_san_peer_certificate, string, The first URI entry in the SAN field of the peer certificate in the upstream TLS connection upstream.sha256_peer_certificate_digest, string, SHA256 digest of the peer certificate in the upstream TLS connection if present upstream.peer_certificate, string, PEM-encoded peer certificate in the upstream TLS connection if present upstream.local_address, string, The local address of the upstream connection upstream.transport_failure_reason, string, The upstream transport failure reason e.g. certificate validation failed upstream.request_attempt_count, uint, The count of upstream request attempts. A value of ‘0’ indicates that the request was never attempted upstream upstream.cx_pool_ready_duration, duration, Total duration from when the upstream request was created to when the upstream connection pool is ready upstream.locality, :ref:Locality<envoy_v3_api_msg_config.core.v3.locality>, Locality information of upstream host

Metadata and filter state

Data exchanged between filters is available as the following attributes:

.. csv-table:: :header: Attribute, Type, Description :widths: 1, 1, 4

metadata, :ref:Metadata<envoy_v3_api_msg_config.core.v3.metadata>, Dynamic request metadata filter_state, "map<string, Value>", Mapping from the filter state name to the object value upstream_filter_state, "map<string, Value>", Mapping from the upstream filter state name to the object value

Filter state value representation is determined based on the filter state declaration in the following order:

If the value is represented as a dynamic CelValue wrapper, CelValue is returned verbatim.
If the key is well-known and has a field reflection enabled, then it is returned as a map from the field names to the field values.
Otherwise, the value is returned as the serialized bytes.

Note that these attributes may change during the life of a request as the data can be updated by filters at any point.

Configuration attributes

Configuration identifiers and metadata related to the handling of the request or the connection is available as the following attributes:

.. csv-table:: :header: Attribute, Type, Description :widths: 1, 1, 4

xds.node, :ref:Node<envoy_v3_api_msg_config.core.v3.node>, Local node description xds.cluster_name, string, Upstream cluster name xds.cluster_metadata, :ref:Metadata<envoy_v3_api_msg_config.core.v3.metadata>, Upstream cluster metadata xds.listener_direction, int, Enumeration value of the :ref:listener traffic direction<envoy_v3_api_field_config.listener.v3.Listener.traffic_direction> xds.listener_metadata, :ref:Metadata<envoy_v3_api_msg_config.core.v3.metadata>, Listener metadata xds.route_name, string, Route name xds.route_metadata, :ref:Metadata<envoy_v3_api_msg_config.core.v3.metadata>, Route metadata xds.virtual_host_name, string, Virtual host name. xds.virtual_host_metadata, :ref:Metadata<envoy_v3_api_msg_config.core.v3.metadata>, Virtual host metadata xds.upstream_host_metadata, :ref:Metadata<envoy_v3_api_msg_config.core.v3.metadata>, Upstream host metadata xds.upstream_host_locality_metadata, :ref:Metadata<envoy_v3_api_msg_config.core.v3.metadata>, Upstream host locality metadata xds.filter_chain_name, string, Listener filter chain name

Wasm attributes

In addition to all above, the following extra attributes are available to Wasm extensions:

.. csv-table:: :header: Attribute, Type, Description :widths: 1, 1, 4

plugin_name, string, Plugin name plugin_root_id, string, Plugin root ID plugin_vm_id, string, Plugin VM ID

Path expressions

Path expressions allow access to inner fields in structured attributes via a sequence of field names, map, and list indexes following an attribute name. For example, get_property({"node", "id"}) in Wasm ABI extracts the value of id field in node message attribute, while get_property({"request", "headers", "my-header"}) refers to the comma-concatenated value of a particular request header.