Skip to content

Commit dc4f31a

Browse files
kralickykralicky
committed
update environment variable docs
1 parent 433aa20 commit dc4f31a

File tree

1 file changed

+62
-31
lines changed

1 file changed

+62
-31
lines changed

‎content/docs/reference/tracing.mdx

+62-31
Original file line numberDiff line numberDiff line change
@@ -27,46 +27,46 @@ Pomerium has comprehensive support for OpenTelemetry (OTel) tracing, allowing de
2727

2828
The recommended way to configure tracing is by using the standard OpenTelemetry environment variables:
2929

30-
- [SDK environment variables](https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/#general-sdk-configuration)
31-
- [OTLP exporter environment variables](https://opentelemetry.io/docs/languages/sdk-configuration/otlp-exporter/)
30+
- [SDK environment variables][topic/general-sdk-cfg]
31+
- [OTLP exporter environment variables][topic/exp-env]
3232

33-
The main variables used to configure tracing in Pomerium are the following:
33+
The following environment variables are supported in Pomerium:
3434

3535
| Name | Description | Type | Default |
3636
| :-- | :-- | :-- | :-- |
37-
| [`OTEL_TRACES_EXPORTER`](https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/#exporter-selection) | Trace exporter to be used. <br/> Valid values are `"otlp"` or `"none"`. | `string` | `"none"` |
38-
| [`OTEL_EXPORTER_OTLP_ENDPOINT`](https://opentelemetry.io/docs/languages/sdk-configuration/otlp-exporter/#otel_exporter_otlp_endpoint) or <br/> [`OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`](https://opentelemetry.io/docs/languages/sdk-configuration/otlp-exporter/#otel_exporter_otlp_traces_endpoint) | See [Endpoint Configuration](https://opentelemetry.io/docs/languages/sdk-configuration/otlp-exporter/#endpoint-configuration). | `string` | |
39-
| [`OTEL_EXPORTER_OTLP_PROTOCOL`](https://opentelemetry.io/docs/languages/sdk-configuration/otlp-exporter/#otel_exporter_otlp_protocol) or <br/> [`OTEL_EXPORTER_OTLP_TRACES_PROTOCOL`](https://opentelemetry.io/docs/languages/sdk-configuration/otlp-exporter/#otel_exporter_otlp_traces_protocol) | See [Protocol Configuration](https://opentelemetry.io/docs/languages/sdk-configuration/otlp-exporter/#protocol-configuration). <br/> Valid values are `"grpc"` or `"http/protobuf"`. <br/>If unset, Pomerium will attempt to determine the protocol based on the endpoint port number (the standard ports are 4317 for GRPC, 4318 for HTTP), otherwise it will default to `"http/protobuf"`. | `string` | |
40-
| [`OTEL_EXPORTER_OTLP_HEADERS`](https://opentelemetry.io/docs/languages/sdk-configuration/otlp-exporter/#otel_exporter_otlp_headers) or <br/> [`OTEL_EXPORTER_OTLP_TRACES_HEADERS`](https://opentelemetry.io/docs/languages/sdk-configuration/otlp-exporter/#otel_exporter_otlp_traces_headers) | See [Header Configuration](https://opentelemetry.io/docs/languages/sdk-configuration/otlp-exporter/#header-configuration). | `[]string` | |
41-
| [`OTEL_EXPORTER_OTLP_TIMEOUT`](https://opentelemetry.io/docs/languages/sdk-configuration/otlp-exporter/#otel_exporter_otlp_timeout) or <br/> [`OTEL_EXPORTER_OTLP_TRACES_TIMEOUT`](https://opentelemetry.io/docs/languages/sdk-configuration/otlp-exporter/#otel_exporter_otlp_traces_timeout) | See [Timeout Configuration](https://opentelemetry.io/docs/languages/sdk-configuration/otlp-exporter/#timeout-configuration). | `int64` | `10000` (ms) |
42-
| [`OTEL_TRACES_SAMPLER_ARG`](https://opentelemetry.io/docs/languages/sdk-configuration/general/#otel_traces_sampler_arg) | Sampling probability, a number in the \[0..1\] range, e.g. `1.0` (sample all traces) or `0.25` (sample 25% of traces). | `float64` | `1.0` |
43-
| [`OTEL_RESOURCE_ATTRIBUTES`](https://opentelemetry.io/docs/languages/sdk-configuration/general/#otel_resource_attributes) | Key-value pairs of additional resource attributes. | `[]string` | |
44-
| [`OTEL_BSP_SCHEDULE_DELAY`](https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/#batch-span-processor) | Interval in milliseconds at which pending spans (if any) are exported. Minimum 100 (ms). | `int32` | `5000` (ms) |
45-
| [`OTEL_BSP_MAX_EXPORT_BATCH_SIZE`](https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/#batch-span-processor) | Number of pending spans needed to automatically trigger an export. Note that spans are still exported on a fixed interval, even if this limit is not reached. Minimum 1; maximum 2048. | `int32` | `512` |
46-
| [`OTEL_LOG_LEVEL`](https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/#general-sdk-configuration) | OTel SDK internal log level. | `string` | `"info"` |
47-
| [`OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT`](https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/#attribute-limits) | Maximum allowed attribute value size. <br/> Increase this to prevent long URLs in span attributes from being truncated. | `int32` | `256` |
37+
| [`OTEL_TRACES_EXPORTER`][env/otel_traces_exporter] | Trace exporter to be used. <br/> Valid values are `"otlp"` or `"none"`. | [Enum][topic/enum] | `"none"` |
38+
| [`OTEL_EXPORTER_OTLP_ENDPOINT`][env/otel_exporter_otlp_endpoint] or <br/> [`OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`][env/otel_exporter_otlp_traces_endpoint] | See [Endpoint Configuration][topic/exp-endpoint-cfg]. | [String][topic/string] | |
39+
| [`OTEL_EXPORTER_OTLP_PROTOCOL`][env/otel_exporter_otlp_protocol] or <br/> [`OTEL_EXPORTER_OTLP_TRACES_PROTOCOL`][env/otel_exporter_otlp_traces_protocol] | See [Protocol Configuration][topic/exp-protocol-cfg]. <br/> Valid values are `"grpc"` or `"http/protobuf"`. <br/>If unset, Pomerium will attempt to determine the protocol based on the endpoint port number (the standard ports are 4317 for GRPC, 4318 for HTTP), otherwise it will default to `"http/protobuf"`. | [String][topic/string] | |
40+
| [`OTEL_EXPORTER_OTLP_HEADERS`][env/otel_exporter_otlp_headers] or <br/> [`OTEL_EXPORTER_OTLP_TRACES_HEADERS`][env/otel_exporter_otlp_traces_headers] | Comma-separated `key=value` pairs containing HTTP headers to add when exporting trace data. <br/>Example: <code>Authentication=Bearer&nbsp;xxx,Foo=Bar</code><br/>See [Header Configuration][topic/exp-header-cfg]. | [String][topic/string] | |
41+
| [`OTEL_EXPORTER_OTLP_TIMEOUT`][env/otel_exporter_otlp_timeout] or <br/> [`OTEL_EXPORTER_OTLP_TRACES_TIMEOUT`][env/otel_exporter_otlp_traces_timeout] | Export request timeout duration in milliseconds.<br/> See [Timeout Configuration][topic/exp-timeout-cfg]. | [Duration][topic/duration] | `10000` (ms) |
42+
| [`OTEL_TRACES_SAMPLER_ARG`][env/otel_traces_sampler_arg] | Sampling probability, a number in the \[0..1\] range.<br/> Examples: `1.0` (sample all traces), `0.25` (sample 25% of traces). | Float | `1.0` |
43+
| [`OTEL_RESOURCE_ATTRIBUTES`][env/otel_resource_attributes] | Comma-separated `key=value` pairs of additional resource attributes. <br/> Example: `key1=value1,key2=value2` | [String][topic/string] | |
44+
| [`OTEL_BSP_SCHEDULE_DELAY`][env/otel_bsp_schedule_delay] | Interval in milliseconds at which pending spans (if any) are exported. Minimum 100 (ms). | [Duration][topic/duration] | `5000` (ms) |
45+
| [`OTEL_BSP_MAX_EXPORT_BATCH_SIZE`][env/otel_bsp_max_export_batch_size] | Number of pending spans needed to automatically trigger an export. Note that spans are still exported on a fixed interval, even if this limit is not reached. Minimum 1. | [Integer][topic/integer] | `512` |
46+
| [`OTEL_LOG_LEVEL`][env/otel_log_level] | OTel SDK internal log level. | [Enum][topic/enum] | `"info"` |
47+
| [`OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT`][env/otel_attribute_value_length_limit] | Maximum allowed attribute value size. <br/> Increase this to prevent long URLs in span attributes from being truncated. | [Integer][topic/integer] | `256` |
4848

4949
### Config file
5050

5151
Tracing can also be configured using the Pomerium config file if desired. The field names in the config file are identical to the environment variable names, but in lowercase.
5252

53-
| Config Key | Equivalent Environment Variable |
54-
| :-- | :-- |
55-
| `otel_traces_exporter` | [`OTEL_TRACES_EXPORTER`](https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/#exporter-selection) |
56-
| `otel_exporter_otlp_endpoint` | [`OTEL_EXPORTER_OTLP_ENDPOINT`](https://opentelemetry.io/docs/languages/sdk-configuration/otlp-exporter/#otel_exporter_otlp_endpoint) |
57-
| `otel_exporter_otlp_traces_endpoint` | [`OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`](https://opentelemetry.io/docs/languages/sdk-configuration/otlp-exporter/#otel_exporter_otlp_traces_endpoint) |
58-
| `otel_exporter_otlp_protocol` | [`OTEL_EXPORTER_OTLP_PROTOCOL`](https://opentelemetry.io/docs/languages/sdk-configuration/otlp-exporter/#otel_exporter_otlp_protocol) |
59-
| `otel_exporter_otlp_traces_protocol` | [`OTEL_EXPORTER_OTLP_TRACES_PROTOCOL`](https://opentelemetry.io/docs/languages/sdk-configuration/otlp-exporter/#otel_exporter_otlp_traces_protocol) |
60-
| `otel_exporter_otlp_headers` | [`OTEL_EXPORTER_OTLP_HEADERS`](https://opentelemetry.io/docs/languages/sdk-configuration/otlp-exporter/#otel_exporter_otlp_headers) |
61-
| `otel_exporter_otlp_traces_headers` | [`OTEL_EXPORTER_OTLP_TRACES_HEADERS`](https://opentelemetry.io/docs/languages/sdk-configuration/otlp-exporter/#otel_exporter_otlp_traces_headers) |
62-
| `otel_exporter_otlp_timeout` | [`OTEL_EXPORTER_OTLP_TIMEOUT`](https://opentelemetry.io/docs/languages/sdk-configuration/otlp-exporter/#otel_exporter_otlp_timeout) |
63-
| `otel_exporter_otlp_traces_timeout` | [`OTEL_EXPORTER_OTLP_TRACES_TIMEOUT`](https://opentelemetry.io/docs/languages/sdk-configuration/otlp-exporter/#otel_exporter_otlp_traces_timeout) |
64-
| `otel_traces_sampler_arg` | [`OTEL_TRACES_SAMPLER_ARG`](https://opentelemetry.io/docs/languages/sdk-configuration/general/#otel_traces_sampler_arg) |
65-
| `otel_resource_attributes` | [`OTEL_RESOURCE_ATTRIBUTES`](https://opentelemetry.io/docs/languages/sdk-configuration/general/#otel_resource_attributes) |
66-
| `otel_bsp_schedule_delay` | [`OTEL_BSP_SCHEDULE_DELAY`](https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/#batch-span-processor) |
67-
| `otel_bsp_max_export_batch_size` | [`OTEL_BSP_MAX_EXPORT_BATCH_SIZE`](https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/#batch-span-processor) |
68-
| `otel_log_level` | [`OTEL_LOG_LEVEL`](https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/#general-sdk-configuration) |
69-
| `otel_attribute_value_length_limit` | [`OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT`](https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/#attribute-limits) |
53+
| Config Key | Equivalent Environment Variable | Type |
54+
| :-- | :-- | :-- |
55+
| `otel_traces_exporter` | [`OTEL_TRACES_EXPORTER`][env/otel_traces_exporter] | `string` |
56+
| `otel_exporter_otlp_endpoint` | [`OTEL_EXPORTER_OTLP_ENDPOINT`][env/otel_exporter_otlp_endpoint] | `string` |
57+
| `otel_exporter_otlp_traces_endpoint` | [`OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`][env/otel_exporter_otlp_traces_endpoint] | `string` |
58+
| `otel_exporter_otlp_protocol` | [`OTEL_EXPORTER_OTLP_PROTOCOL`][env/otel_exporter_otlp_protocol] | `string` |
59+
| `otel_exporter_otlp_traces_protocol` | [`OTEL_EXPORTER_OTLP_TRACES_PROTOCOL`][env/otel_exporter_otlp_traces_protocol] | `string` |
60+
| `otel_exporter_otlp_headers` | [`OTEL_EXPORTER_OTLP_HEADERS`][env/otel_exporter_otlp_headers] | `[]string` |
61+
| `otel_exporter_otlp_traces_headers` | [`OTEL_EXPORTER_OTLP_TRACES_HEADERS`][env/otel_exporter_otlp_traces_headers] | `[]string` |
62+
| `otel_exporter_otlp_timeout` | [`OTEL_EXPORTER_OTLP_TIMEOUT`][env/otel_exporter_otlp_timeout] | `int64` |
63+
| `otel_exporter_otlp_traces_timeout` | [`OTEL_EXPORTER_OTLP_TRACES_TIMEOUT`][env/otel_exporter_otlp_traces_timeout] | `int64` |
64+
| `otel_traces_sampler_arg` | [`OTEL_TRACES_SAMPLER_ARG`][env/otel_traces_sampler_arg] | `float64` |
65+
| `otel_resource_attributes` | [`OTEL_RESOURCE_ATTRIBUTES`][env/otel_resource_attributes] | `[]string` |
66+
| `otel_bsp_schedule_delay` | [`OTEL_BSP_SCHEDULE_DELAY`][env/otel_bsp_schedule_delay] | `int64` |
67+
| `otel_bsp_max_export_batch_size` | [`OTEL_BSP_MAX_EXPORT_BATCH_SIZE`][env/otel_bsp_max_export_batch_size] | `int32` |
68+
| `otel_log_level` | [`OTEL_LOG_LEVEL`][env/otel_log_level] | `string` |
69+
| `otel_attribute_value_length_limit` | [`OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT`][env/otel_attribute_value_length_limit] | `int32` |
7070

7171
</TabItem>
7272
<TabItem value="Enterprise" label="Enterprise">
@@ -180,3 +180,34 @@ The trace above ends with a final redirect to repeat the original request, but t
180180
![Auth flow 2](./img/tracing/auth-flow-2.png)
181181
182182
This trace ends with the proxied request to the upstream server.
183+
184+
{/* prettier-ignore-start */}
185+
186+
[topic/duration]: https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/#duration
187+
[topic/integer]: https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/#integer
188+
[topic/string]: https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/#string
189+
[topic/enum]: https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/#enum
190+
[topic/exp-env]: https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables
191+
[topic/general-sdk-cfg]: https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/#general-sdk-configuration
192+
[topic/exp-endpoint-cfg]: https://opentelemetry.io/docs/languages/sdk-configuration/otlp-exporter/#endpoint-configuration
193+
[topic/exp-header-cfg]: https://opentelemetry.io/docs/languages/sdk-configuration/otlp-exporter/#header-configuration
194+
[topic/exp-protocol-cfg]: https://opentelemetry.io/docs/languages/sdk-configuration/otlp-exporter/#protocol-configuration
195+
[topic/exp-timeout-cfg]: https://opentelemetry.io/docs/languages/sdk-configuration/otlp-exporter/#timeout-configuration
196+
197+
[env/otel_attribute_value_length_limit]: https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/#:~:text=OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT
198+
[env/otel_bsp_max_export_batch_size]: https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/#:~:text=OTEL_BSP_MAX_EXPORT_BATCH_SIZE
199+
[env/otel_bsp_schedule_delay]: https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/#:~:text=OTEL_BSP_SCHEDULE_DELAY
200+
[env/otel_log_level]: https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/#:~:text=OTEL_LOG_LEVEL
201+
[env/otel_traces_exporter]: https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/#:~:text=OTEL_TRACES_EXPORTER
202+
[env/otel_exporter_otlp_endpoint]: https://opentelemetry.io/docs/languages/sdk-configuration/otlp-exporter/#otel_exporter_otlp_endpoint
203+
[env/otel_exporter_otlp_headers]: https://opentelemetry.io/docs/languages/sdk-configuration/otlp-exporter/#otel_exporter_otlp_headers
204+
[env/otel_exporter_otlp_protocol]: https://opentelemetry.io/docs/languages/sdk-configuration/otlp-exporter/#otel_exporter_otlp_protocol
205+
[env/otel_exporter_otlp_timeout]: https://opentelemetry.io/docs/languages/sdk-configuration/otlp-exporter/#otel_exporter_otlp_timeout
206+
[env/otel_exporter_otlp_traces_endpoint]: https://opentelemetry.io/docs/languages/sdk-configuration/otlp-exporter/#otel_exporter_otlp_traces_endpoint
207+
[env/otel_exporter_otlp_traces_headers]: https://opentelemetry.io/docs/languages/sdk-configuration/otlp-exporter/#otel_exporter_otlp_traces_headers
208+
[env/otel_exporter_otlp_traces_protocol]: https://opentelemetry.io/docs/languages/sdk-configuration/otlp-exporter/#otel_exporter_otlp_traces_protocol
209+
[env/otel_exporter_otlp_traces_timeout]: https://opentelemetry.io/docs/languages/sdk-configuration/otlp-exporter/#otel_exporter_otlp_traces_timeout
210+
[env/otel_resource_attributes]: https://opentelemetry.io/docs/languages/sdk-configuration/general/#otel_resource_attributes
211+
[env/otel_traces_sampler_arg]: https://opentelemetry.io/docs/languages/sdk-configuration/general/#otel_traces_sampler_arg
212+
213+
{/* prettier-ignore-end */}

0 commit comments

Comments
 (0)