OpenTelemetry Access Logging extension configuration reference
This topic describes how to configure the OpenTelemetry access logging Envoy extension, which configures Envoy proxies to send access logs to OpenTelemetry collector service. Refer to Send access logs to OpenTelemetry collector service for usage information.
Configuration model
The following list outlines the field hierarchy, data types, and requirements for the OpenTelemetry access logging configuration. Place the configuration inside the EnvoyExtension.Arguments
field in the proxy defaults or service defaults configuration entry. Refer to the following documentation for additional information:
EnvoyExtensions
in proxy defaultsEnvoyExtensions
in service defaults- Envoy OpenTelemetry Access Logging Configuration documentation
Click on a property name to view additional details, including default values.
Name
: string | required | must be set tobuiltin/otel-access-logging
Arguments
: map | requiredProxyType
: string | required |connect-proxy
ListenerType
: string | required |inbound
Config
: map | requiredLogName
: stringGrpcService
: mapBufferFlushInterval
: stringBufferSizeBytes
: numberFilterStateObjectsToLog
: list of stringsRetryPolicy
: mapRetryBackOff
: mapBaseInterval
: string |1s
MaxInterval
: string |30s
NumRetries
: number
Body
: string, number, boolean or list of bytesAttributes
: map of string to string, number, boolean or list of bytesResourceAttributes
: map of string to string, number, boolean or list of bytes
Complete configuration
When each field is defined, an otel-access-logging
configuration has the following form:
Specification
This section provides details about the fields you can configure for the OpenTelemetry Access Logging extension.
Name
Specifies the name of the extension. Must be set to builtin/otel-access-logging
.
Values
- Default: None
- This field is required.
- Data type: String value set to
builtin/otel-access-logging
.
Arguments
Contains the global configuration for the extension.
Values
- Default: None
- This field is required.
- Data type: Map
Arguments.ProxyType
Specifies the type of Envoy proxy that this extension applies to. The extension only applies to proxies that match this type and is ignored for all other proxy types. The only supported value is connect-proxy
.
Values
- Default:
connect-proxy
- This field is required.
- Data type: String
Arguments.ListenerType
Specifies the type of listener the extension applies to. The listener type is either inbound
or outbound
. If the listener type is set to inbound
, Consul applies the extension so the access logging is enabled when other services in the mesh send messages to the service attached to the proxy. If the listener type is set to outbound
, Consul applies the extension so the access logging is enabled when the attached proxy sends messages to other services in the mesh.
Values
- Default:
inbound
- This field is required.
- Data type is one of the following string values:
Arguments.Config
Contains the configuration settings for the extension.
Values
- Default: None
- This field is required.
- Data type: Map
Arguments.Config.LogName
Specifies the user-readable name of the access log to be returned in StreamAccessLogsMessage.Identifier
. This allows the access log server to differentiate between different access logs coming from the same Envoy. If you leave it empty, it inherits the value from ListenerType
.
Values
- Default: None
- Data type: String
Arguments.Config.GrpcService
Specifies the OpenTelemetry Access Logging configuration for gRPC requests.
Values
- Default: None
- This field is required.
- Data type: Map
Arguments.Config.GrpcService.Target
Configuration for specifying the service to send gRPC access logging requests to. The Target
field may contain the following fields:
Values
- Default: None
- This field is required.
- Data type: Map
Arguments.Config.GrpcService.Target.Service
Specifies the upstream OpenTelemetry collector service. Configure this field when access logging requests are sent to an upstream service within the service mesh. The service must be configured as an upstream of the service that the filter is applied to.
Configure either the Service
field or the Uri
field, but not both.
Values
- Default: None
- This field or
Uri
is required. - Data type: Map
The following table describes how to configure parameters for the Service
field:
Parameter | Description | Data type | Default |
---|---|---|---|
Name | Specifies the name of the upstream service. | String | None |
Namespace | Enterprise Specifies the Consul namespace that the upstream service belongs to. | String | default |
Partition | Enterprise Specifies the Consul admin partition that the upstream service belongs to. | String | default |
Arguments.Config.GrpcService.Target.Uri
Specifies the URI of the OpenTelemetry collector service. Configure this field when you must provide an explicit URI to the OpenTelemetry collector service, such as cases in which the access logging service is running on the same host or pod. If set, the value of this field must be one of localhost:<port>
, 127.0.0.1:<port>
, or ::1:<port>
.
Configure either the Uri
field or the Service
field, but not both.
Values
- Default: None
- This field or
Service
is required. - Data type: String
Arguments.Config.GrpcService.Target.Timeout
Specifies the maximum duration that a response can take to arrive upon request.
Values
- Default:
1s
- Data type: String
Arguments.Config.GrpcService.Authority
Specifies the authority header to send in the gRPC request. If this field is not set, the authority field is set to the cluster name. This field does not override the SNI that Envoy sends to the OpenTelemetry collector service.
Values
- Default: Cluster name
- Data type: String
Arguments.Config.GrpcService.InitialMetadata
Specifies additional metadata to include in streams initiated to the GrpcService
. You can specify metadata for injecting additional ad-hoc authorization headers, for example, x-foo-bar: baz-key
. For more information, including details on header value syntax, refer to the Envoy documentation on custom request headers.
Values
Default: None
Data type: List of one or more key-value pairs:
- KEY: String
- VALUE: String
Arguments.Config.BufferFlushInterval
Specifies an interval for flushing access logs to the gRPC stream. The logger flushes requests at the end of every interval or when the log reaches the batch size limit, whichever comes first.
Values
- Default:
1s
- Data type: String
Arguments.Config.BufferSizeBytes
Specifies the soft size limit in bytes for the access log entries buffer. The logger buffers requests until it reaches this limit or every time the flush interval elapses, whichever comes first. Set this field to 0
to disable batching.
Values
- Default:
16384
- Data type: Integer
Arguments.Config.FilterStateObjectsToLog
Specifies additional filter state objects to log in filter_state_objects
. The logger calls FilterState::Object::serializeAsProto
to serialize the filter state object.
Values
- Default: None
- Data type: List of String
Arguments.Config.RetryPolicy
Defines a policy for retrying requests to the upstream service when fetching the plugin data. The RetryPolicy
field is a map containing the following parameters:
Values
- Default: None
- Data type: Map
Arguments.Config.RetryPolicy.RetryBackOff
Specifies parameters that control retry backoff strategy.
Values
- Default: None
- Data type: Map
The following table describes the fields you can specify in the RetryBackOff
map:
Parameter | Description | Data type | Default |
---|---|---|---|
BaseInterval | Specifies the base interval for determining the next backoff computation. Set a value greater than 0 and less than or equal to the MaxInterval value. | String | 1s |
MaxInterval | Specifies the maximum interval between retries. Set the value greater than or equal to the BaseInterval value. | String | 10s |
Arguments.Config.RetryPolicy.NumRetries
Specifies the number of times Envoy retries to fetch plugin data if the initial attempt is unsuccessful.
Values
- Default:
1
- Data type: Integer
Arguments.Config.Body
Specifies OpenTelemetry LogResource fields, following Envoy access logging formatting. See ‘body’ in the LogResource proto for more details.
Values
- Default: None
- Data type: String
Arguments.Config.Attributes
Specifies attributes
in the LogResource. Refer to attributes
in the LogResource proto for more details.
Values
- Default: None
- Data type: Map
Arguments.Config.ResourceAttributes
Specifies OpenTelemetry Resource attributes are filled with Envoy node information.
Values
- Default: None
- Data type: Map
Examples
The following examples demonstrate common configuration patterns for specific use cases.
OpenTelemetry Access Logging requests to URI
In the following example, a service defaults configuration entry contains an otel-access-logging
configuration. The configuration allows the api
service to make gRPC OpenTelemetry Access Logging requests to a service at localhost:9191
:
Upstream OpenTelemetry Access Logging
In the following example, a service defaults configuration entry contains an otel-access-logging
configuration. The configuration allows the api
service to make gRPC OpenTelemetry Access Logging requests to a service named otel-collector
: