Opentelemetry-specification: Standardize environment variables between SDK implementations

Created on 21 Apr 2020 · 15Comments · Source: open-telemetry/opentelemetry-specification

Currently environment variables are being defined individually by SIGs on a one off basis. We should coordinate this effort and come up with a list of standardized environment variable names, values, and behavior.

As a starting point, we should document the environment variables that already exist, and move on to additional definitions from there.

Here are some environment variable definitions that have been discussed in spec issues. If SIGs can add environment variables that they are using, or would like to define in the comments, I can update this list.

| Name | Description | Language | Link |
| ------------------------ | --------------------------------------------------- | ---------- | -------------------------------------------------------------------------------------------------------- |
| OTEL_RESOURCE_LABELS | Key values pairs to be used as resource labels | Javascript | issue |
| OTEL_RESOURCE_ATTRIBUTES | Key values pairs to be used as resource labels | Java | issue |
| OTEL_SAMPLING_RATE | Sampling rate to be used by the probability sampler | Javascript | issue |
| OTEL_LOG_LEVEL | Log level used by the SDK logger | Javascript | issue |

Another important consideration we need to address, is the value format. Here is a related issue: https://github.com/open-telemetry/opentelemetry-specification/pull/505.

sdk enhancement p2 required-for-ga

Source

mwear

👍2

All 15 comments

Just to update everybody on the Python side:

The Python implementation currently reads any environment variable prefixed with OPENTELEMETRY_PYTHON_. The idea behind this is to avoid conflicting with other OpenTelemetry implementations.

The API currently uses OPENTELEMETRY_PYTHON_TRACER_PROVIDER and OPENTELEMETRY_PYTHON_METER_PROVIDER. The configuration object is made to read any other OPENTELEMETRY_PYTHON_ prefixed environment variables so that they can be accesses by any other OpenTelemetry Python components, like instrumentations for third party libraries or frameworks.

ocelotl on 21 Apr 2020

Erlang is also using OTEL_RESOURCE_LABELS for resource labels.

tsloughter on 23 Apr 2020

FYI OTEL_SAMPLING_RATE has not been implemented in JS yet (nor has OTEL_LOG_LEVEL for that matter, but that name is pretty solid).

re: OTEL_SAMPLING_RATE, seeing that it sets the probability of the probability sampler, would OTEL_SAMPLING_PROBABILITY be a better name, or are rate and probability considered synonymous (enough) ?

naseemkullah on 1 May 2020

JAEGER_AGENT_HOST in JS is used for the Jaeger Exporter's host option same way as it is used today in the Jaeger clients.

JAEGER_AGENT_HOST defines hostname for reporting spans over UDP/Thrift.

worth noting: in code configuration of the exporter's host value is more authoritative than the env var.

Not sure if this is what we want for all env vars or not.

We would probably want consistent authority (in code > env var or vice-versa) across env vars.

naseemkullah on 1 May 2020

If I recall correctly, we didn't want to name things "OTEL" because there was already another technical concept that was called that.

That said, a google search for "otel" pops up nothing, so maybe it's ok?

toumorokoshi on 8 May 2020

Java uses the following environment variables:

thisthat on 11 May 2020

👍1

@mwear do you have enough information to pick up a proposal? We are rapidly adding functionality to Python's auto-instrumentation which heavily utilizes environment variables.

toumorokoshi on 16 May 2020

👍1

@toumorokoshi I'll draft up a specification this week. The goal will be to capture the environment variables that make sense to be standardized between languages. For language specific environment variables, it might be a good idea of us to decide on conventions each language can use, rather than specific environment variable names. We can have that conversation as part of this spec as well.

mwear on 18 May 2020

👍1

@mwear please make sure https://github.com/open-telemetry/opentelemetry-specification/issues/567 is also covered :)

bogdandrutu on 19 May 2020

In no way tied to these 😄, just reporting the current state for Java auto-instrumentation. Looking forward to using the standardized env vars.

| environment variable | default value |
|----------------------------------|--------------------------------------|
| OTA_EXPORTER_OTLP_ENDPOINT | <exception on missing> |
| OTA_EXPORTER_JAEGER_ENDPOINT | "localhost:14250" |
| OTA_EXPORTER_JAEGER_SERVICE_NAME | "(unknown service)" |
| OTA_EXPORTER_ZIPKIN_ENDPOINT | "http://localhost:9411/api/v2/spans" |
| OTA_EXPORTER_ZIPKIN_SERVICE_NAME | "(unknown service)" |

trask on 20 May 2020

Oh, also:

| environment variable | default value | notes |
|----------------------|----------------|---|
| OTA_PROPAGATORS | "tracecontext" | comma-separated list, currently supporting "tracecontext" and "b3" |

trask on 20 May 2020

@toumorokoshi I'll draft up a specification this week. The goal will be to capture the environment variables that make sense to be standardized between languages. For language specific environment variables, it might be a good idea of us to decide on conventions each language can use, rather than specific environment variable names. We can have that conversation as part of this spec as well.

+1 to standardize the namespacing for language-specific environment variables.

toumorokoshi on 20 May 2020

👍1

FYI OTEL_SAMPLING_RATE has not been implemented in JS yet (nor has OTEL_LOG_LEVEL for that matter, but that name is pretty solid).

re: OTEL_SAMPLING_RATE, seeing that it sets the probability of the probability sampler, would OTEL_SAMPLING_PROBABILITY be a better name, or are rate and probability considered synonymous (enough) ?

@naseemkullah No, I believe that rate and probability are inverses of each other. I believe the reason we use "rate" to describe inverse probability is that if you see one sampled item using probability p over a unit of time, then you should count that as representing 1/p individuals over the same unit of time. Thus, rate is a multiplier >= 1 while probability is <= 1.

jmacd on 4 Jun 2020

FYI OTEL_SAMPLING_RATE has not been implemented in JS yet (nor has OTEL_LOG_LEVEL for that matter, but that name is pretty solid).
re: OTEL_SAMPLING_RATE, seeing that it sets the probability of the probability sampler, would OTEL_SAMPLING_PROBABILITY be a better name, or are rate and probability considered synonymous (enough) ?

@naseemkullah No, I believe that rate and probability are inverses of each other. I believe the reason we use "rate" to describe inverse probability is that if you see one sampled item using probability p over a unit of time, then you should count that as representing 1/p individuals over the same unit of time. Thus, rate is a multiplier >= 1 while probability is <= 1.

🤯 Thanks @jmacd , while I don't quite get why probability and rate are inverses of each other, I am leaning more towards OTEL_SAMPLING_PROBABILITY being the correct name for setting the probability sampler's sampling probability.

naseemkullah on 4 Jun 2020

rate and probability are not actually inverses of each other. rate describes a ratio between an independent and a dependent variable, while probability is the chance of some occurrence.

You could technically say "sample at a rate of 0.1 sampled traces per trace" (sampled traces dependent on total traces) and that would seem to equal a 10% probability. But, if you sampled every 10th trace, that would still be a 1 in 10 rate. In that scenario, each trace would _not_ have a 10% probability of being sampled.