mirror of https://github.com/status-im/consul.git
391 lines
16 KiB
Plaintext
391 lines
16 KiB
Plaintext
---
|
||
layout: docs
|
||
page_title: OpenTelemetry Access Logging extension configuration reference
|
||
description: Learn how to configure the otel-access-logging Envoy extension, which is a builtin Consul extension that configures Envoy proxies to send access logs to OpenTelemetry collector service.
|
||
---
|
||
|
||
# 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](/consul/docs/connect/proxies/envoy-extensions/usage/otel-access-logging) 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](/consul/docs/connect/config-entries/proxy-defaults#envoyextensions)
|
||
- [`EnvoyExtensions` in service defaults](/consul/docs/connect/config-entries/service-defaults#envoyextensions)
|
||
- [Envoy OpenTelemetry Access Logging Configuration documentation](https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/access_loggers/open_telemetry/v3/logs_service.proto#extensions-access-loggers-open-telemetry-v3-opentelemetryaccesslogconfig)
|
||
|
||
Click on a property name to view additional details, including default values.
|
||
|
||
- [`Name`](#name): string | required | must be set to `builtin/otel-access-logging`
|
||
- [`Arguments`](#arguments): map | required
|
||
- [`ProxyType`](#arguments-proxytype): string | required | `connect-proxy`
|
||
- [`ListenerType`](#arguments-listenertype): string | required | `inbound`
|
||
- [`Config`](#arguments-config): map | required
|
||
- [`LogName`](#arguments-config-logname): string
|
||
- [`GrpcService`](#arguments-config-grpcservice): map
|
||
- [`Target`](#arguments-config-grpcservice-target): map | required
|
||
- [`Service`](#arguments-config-grpcservice-target-service): map
|
||
- [`Name`](#arguments-config-grpcservice-target-service): string
|
||
- [`Namespace`](#arguments-config-grpcservice-target-service): string | <EnterpriseAlert inline/>
|
||
- [`Partition`](#arguments-config-grpcservice-target-service): string | <EnterpriseAlert inline/>
|
||
- [`URI`](#arguments-config-grpcservice-target-uri): string
|
||
- [`Timeout`](#arguments-config-grpcservice-target-timeout): string | `1s`
|
||
- [`Authority`](#arguments-config-grpcservice-authority): string
|
||
- [`InitialMetadata`](#arguments-config-grpcservice-initialmetadata): list
|
||
- [`Key`](#arguments-config-grpcservice-initialmetadata): string
|
||
- [`Value`](#arguments-config-grpcservice-initialmetadata): string
|
||
- [`BufferFlushInterval`](#arguments-config-bufferflushinterval): string
|
||
- [`BufferSizeBytes`](#arguments-config-buffersizebytes): number
|
||
- [`FilterStateObjectsToLog`](#arguments-config-filterstateobjectstolog): list of strings
|
||
- [`RetryPolicy`](#arguments-config-retrypolicy): map
|
||
- [`RetryBackOff`](#arguments-config-retrypolicy-retrybackoff): map
|
||
- [`BaseInterval`](#arguments-config-retrypolicy-retrybackoff): string | `1s`
|
||
- [`MaxInterval`](#arguments-config-retrypolicy-retrybackoff): string | `30s`
|
||
- [`NumRetries`](#arguments-config-retrypolicy-numretries): number
|
||
- [`Body`](#arguments-config-body): string, number, boolean or list of bytes
|
||
- [`Attributes`](#arguments-config-attributes): map of string to string, number, boolean or list of bytes
|
||
- [`ResourceAttributes`](#arguments-config-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:
|
||
|
||
```hcl
|
||
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`](#arguments-config-grpcservice-target-service) or [`Uri`](#arguments-config-grpcservice-target-uri)
|
||
- [`Timeout`](#arguments-config-grpcservice-target-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`](#arguments-config-grpcservice-target-uri) field, but not both.
|
||
|
||
#### Values
|
||
|
||
- Default: None
|
||
- This field or [`Uri`](#arguments-config-grpcservice-target-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` | <EnterpriseAlert inline/> Specifies the Consul namespace that the upstream service belongs to. | String | `default` |
|
||
| `Partition` | <EnterpriseAlert inline/> 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`](#arguments-config-grpcservice-target-service) field, but not both.
|
||
|
||
#### Values
|
||
|
||
- Default: None
|
||
- This field or [`Service`](#arguments-config-grpcservice-target-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](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_conn_man/headers#config-http-conn-man-headers-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`](#pluginconfig-vmconfig-code-remote-retrypolicy)
|
||
- [`NumRetries`](#pluginconfig-vmconfig-code-remote-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:
|
||
|
||
| 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](https://github.com/open-telemetry/opentelemetry-proto/blob/main/opentelemetry/proto/logs/v1/logs.proto) fields, following [Envoy access logging formatting](https://www.envoyproxy.io/docs/envoy/latest/configuration/observability/access_log/usage). See ‘body’ in the LogResource proto for more details.
|
||
|
||
#### Values
|
||
|
||
- Default: None
|
||
- Data type: String
|
||
|
||
### `Arguments.Config.Attributes`
|
||
|
||
Specifies `attributes` in the [LogResource](https://github.com/open-telemetry/opentelemetry-proto/blob/main/opentelemetry/proto/logs/v1/logs.proto). Refer to `attributes` in the LogResource proto for more details.
|
||
|
||
#### Values
|
||
|
||
- Default: None
|
||
- Data type: Map
|
||
|
||
### `Arguments.Config.ResourceAttributes`
|
||
|
||
Specifies OpenTelemetry [Resource](https://github.com/open-telemetry/opentelemetry-proto/blob/main/opentelemetry/proto/logs/v1/logs.proto#L51) 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`:
|
||
|
||
```hcl
|
||
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`:
|
||
|
||
```hcl
|
||
Kind = "service-defaults"
|
||
Name = "api"
|
||
EnvoyExtensions = [
|
||
{
|
||
Name = "builtin/otel-access-logging"
|
||
Arguments = {
|
||
ProxyType = "connect-proxy"
|
||
Config = {
|
||
GrpcService = {
|
||
Target = {
|
||
Service = {
|
||
Name = "otel-collector"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
]
|
||
```
|