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 defaults
• EnvoyExtensions 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 to builtin/otel-access-logging
• Arguments: map | required
  • ProxyType: string | required | connect-proxy
  • ListenerType: string | required | inbound
  • Config: map | required
    • LogName: string
    • GrpcService: map
      • Target: map | required
        • Service: map
          • Name: string
          • Namespace: string | EnterpriseEnterprise
          • Partition: string | EnterpriseEnterprise
        • URI: string
        • Timeout: string | 1s
      • Authority: string
      • InitialMetadata: list
        • Key: string
        • Value: string
    • BufferFlushInterval: string
    • BufferSizeBytes: number
    • FilterStateObjectsToLog: list of strings
    • RetryPolicy: map
      • RetryBackOff: map
        • BaseInterval: string | 1s
        • MaxInterval: string | 30s
      • NumRetries: number
    • Body: string, number, boolean or list of bytes
    • Attributes: map of string to string, number, boolean or list of bytes
    • ResourceAttributes: 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:

Name = "builtin/otel-access-logging" 
Arguments = {
   ProxyType = "connect-proxy"
   ListenerType = "<inbound or outbound>"
   Config = {
      LogName = "<user-readable name of the access log>"
      GrpcService = {
        Target = {
            Service = {
              Name = "<upstream service to send gRPC authorization requests to>"
              Namespace = "<namespace containing the upstream service>"
              Partition = "<partition containing the upstream service>"
            }
            URI = "<URI of the upstream service>"   
            Timeout = "1s"
        }
        Authority = "<authority header to send in the gRPC request>"     
        InitialMetadata = [
            "<Key>" : "<value>"
        ]
      }
      BufferFlushInterval = "1s"
      BufferSizeBytes = 16384
      FilterStateObjectsToLog = [
        "Additional filter state objects to log in filter_state_objects"
      ]
      RetryPolicy = {
        RetryBackOff = {
            BaseInterval = "1s"
            MaxInterval = "30s"
        }
        NumRetries = <uint32 value specifying the max number of retries>
      }
      Body = "Log Request Body"
      Attributes = {
         "<Key>" : "<value>"
      }
      ResourceAttributes = {
         "<Key>" : "<value>"
      }

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:
  • inbound
  • outbound

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:

• Service or Uri
• Timeout

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:

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:

• RetryBackoff
• NumRetries

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:

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:

Kind = "service-defaults"
Name = "api"
EnvoyExtensions = [
  {
    Name = "builtin/otel-access-logging"
    Arguments = {
      ProxyType = "connect-proxy"
      Config = {
        GrpcService = {
          Target = {
              URI = "127.0.0.1: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:

Kind = "service-defaults"
Name = "api"
EnvoyExtensions = [
  {
    Name = "builtin/otel-access-logging"
    Arguments = {
      ProxyType = "connect-proxy"
      Config = {
        GrpcService = {
          Target = {
            Service = {
              Name = "otel-collector"
            }
          }
        }
      }
    }
  }
]