Add OTEL_TRACE_SAMPLER_ARG env variable definition. (#1202)

* Add OTEL_TRACE_SAMPLER_ARG env variable definition. * Update CHANGELOG. * Clarify sampling priority. * Update specification/sdk-environment-variables.md Co-authored-by: Christian Neumüller <christian+github@neumueller.me> * Update specification/sdk-environment-variables.md Co-authored-by: Tigran Najaryan <4194920+tigrannajaryan@users.noreply.github.com> Co-authored-by: Christian Neumüller <christian+github@neumueller.me> Co-authored-by: Tigran Najaryan <4194920+tigrannajaryan@users.noreply.github.com>
open-telemetry · Nov 9, 2020 · f5519f2 · f5519f2
1 parent 1954360
commit f5519f2
Show file tree

Hide file tree

Showing 3 changed files with 8 additions and 0 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -63,6 +63,8 @@ New:
   ([#1141](https://github.com/open-telemetry/opentelemetry-specification/pull/1141))
 - Add OTEL_TRACE_SAMPLER env variable definition
   ([#1136](https://github.com/open-telemetry/opentelemetry-specification/pull/1136/))
+- Add OTEL_TRACE_SAMPLER_ARG env variable definition
+  ([#1202](https://github.com/open-telemetry/opentelemetry-specification/pull/1202))
 
 Updates:
 

diff --git a/spec-compliance-matrix.md b/spec-compliance-matrix.md
@@ -128,6 +128,7 @@ status of the feature is not known.
 |OTEL_SPAN_EVENT_COUNT_LIMIT                   |   | +  |   |      |    |      |   |    |   |    |
 |OTEL_SPAN_LINK_COUNT_LIMIT                    |   | +  |   |      |    |      |   |    |   |    |
 |OTEL_TRACE_SAMPLER                            |   | -  |   |      |    |      |   |    |   |    |
+|OTEL_TRACE_SAMPLER_ARG                        |   |    |   |      |    |      |   |    |   |    |
 
 ## Exporters
 

diff --git a/specification/sdk-environment-variables.md b/specification/sdk-environment-variables.md
@@ -10,6 +10,7 @@ The goal of this specification is to unify the environment variable names betwee
 | OTEL_LOG_LEVEL           | Log level used by the SDK logger                  | "info"                            |                                     |
 | OTEL_PROPAGATORS         | Propagators to be used as a comma separated list  | "tracecontext,baggage"            | Values MUST be deduplicated in order to register a `Propagator` only once. Unrecognized values MUST generate a warning and be gracefully ignored. |
 | OTEL_TRACE_SAMPLER       | Sampler to be used for traces                     | "parentbased_always_on"                       | See [Sampling](./trace/sdk.md#sampling) |
+| OTEL_TRACE_SAMPLER_ARG   | String value to be used as the sampler argument   |                                   | The specified value will only be used if OTEL_TRACE_SAMPLER is set. Each Sampler type defines its own expected input, if any. Invalid or unrecognized input MUST be logged and MUST be otherwise ignored, i.e. the SDK MUST behave as if OTEL_TRACE_SAMPLER_ARG is not set.  |
 
 Known values for OTEL_PROPAGATORS are: "tracecontext", "baggage", "b3", "jaeger".
 Additional values can be specified in the respective SDK's documentation, in case third party `Propagator`s are supported, such as "xray" or "ottracer".
@@ -23,6 +24,10 @@ Known values for `OTEL_TRACE_SAMPLER` are:
 - `"parentbased_always_off"`: `ParentBased(root=AlwaysOffSampler)`
 - `"parentbased_traceidratio"`: `ParentBased(root=TraceIdRatioBased)`
 
+Depending on the value of `OTEL_TRACE_SAMPLER`, `OTEL_TRACE_SAMPLER_ARG` may be set as follows:
+
+- For `traceidratio` and `parentbased_traceidratio` samplers: Sampling probability, a number in the [0..1] range, e.g. "0.25".
+
 ## Batch Span Processor
 
 | Name                           | Description                                    | Default | Notes                                                 |