Configuring a sampler from an environment variable

[mwear]

Sampler configuration

A comment on #666 expressed the desire to be able to configure a sampler by environment variable. I've opened this issue as a way to discuss how this should work.

A possible solution

Configuring a propagator via environment variable requires taking a string and looking up or creating a propagator instance. One way to accomplish this is by having a sampler registry. Since samplers are an extension point, users should be able to register custom types.

Other Solutions

Please discuss alternatives in the comments

Environment Variable Name

Name	Description	Notes	Default
OTEL_SAMPLER	The sampler to be used by the sdk	E.g. probability, always_on, always_off, my_custom_sampler	always_on

Note: We will need to define a canonical name for each sampler. Is lower snakecase a reasonable choice for built samplers, or should we choose something else?

Open Questions

How should we handle failure? What if an environment variable is set to an invalid name?

• Should we fail to start?
• Should we use the default AlwaysOn Sampler? If so, how should we indicate this to the user?

I'm open to any other proposals or suggestions. I just wanted to get the discussion going with this proposal.

[yurishkuro]

If user specifies OTEL_SAMPLER=probabilistic, where would the rate come from?

In Jaeger SDKs we used two vars, mirroring the span tags set after sampling decision was made: sampler.type and sampler.param, where param is a number whose interpretation depends on the sampler, e.g. type=const param=1 means always-on.

[mwear]

Additional information can be specified using sampler specific environment variables. Currently #666 proposes OTEL_SAMPLING_PROBABILITY as the way to configure the probabililty sampler. While I like the idea of sampler.param I think there might be cases where a sampler does not have any additional configuration (like AlwaysOnSampler, or AlwaysOffSampler). Similarly, there might be samplers that have more complicated configuration that isn't easy to fit into a single parameter. Is it reasonable to have sampler specific environment variables?

[yurishkuro]

yeah, sounds ok

[tigrannajaryan]

I think this is a nice-to-have, not a must-have for 1.0 GA. It can be added after GA in a non-breaking manner. I suggest to remove release:required-for-ga label.

[tigrannajaryan]

Since I don't see any objections I am moving this to after GA.

[iNikem]

We already have OTEL_TRACES_SAMPLER in https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/sdk-environment-variables.md. I think this issue can be closed now, @mwear