OTEL_ENTITIES var is part of the env var config interface spec and its format is described extensively in the entity propagation spec.
But the env var config interface spec is marked "stable except where otherwise specified", there is no call out that OTEL_ENTITIES is in development, and the entity propagation spec that described OTEL_ENTITIES in detail is marked "development".
Progressing through the maturity levels for env vars can be tricky business.
Previously, we did things like include a *_EXPERIMENTAL_* delimiter, and remove once ready to stable. For example, OTEL_CONFIG_FILE originated from the now deprecated OTEL_EXPERIMENTAL_CONFIG_FILE. This solution suffers from the issue that you have a potentially long tail deprecated experimental variant to be documented / supported.
It seems that OTEL_ENTITIES has not gone that route. I'm not sure if that was intentional or not, but we need to fix it and somehow demarcate / delimit that OTEL_ENTITIES is still experimental and breaking changes to its format / semantics are still allowed.
We could go the direction of OTEL_CONFIG_FILE and change it to OTEL_EXPERIMENTAL_ENTITIES until ready for maturity.
Alternatively, we could go the direction @jsuereth has gone in the java entities prototype and add a secondary OTEL_EXPERIMENTAL_ENTITIES_ENABLED env var. If OTEL_EXPERIMENTAL_ENTITIES_ENABLED=true, that prompts the SDK to parse OTEL_ENTITIES. The advantage of this approach is that its less churn if we manage to promote OTEL_ENTITIES to stable without breaking changes to the format. This is appealing and I favor this approach.
OTEL_ENTITIESvar is part of the env var config interface spec and its format is described extensively in the entity propagation spec.But the env var config interface spec is marked "stable except where otherwise specified", there is no call out that
OTEL_ENTITIESis in development, and the entity propagation spec that describedOTEL_ENTITIESin detail is marked "development".Progressing through the maturity levels for env vars can be tricky business.
Previously, we did things like include a
*_EXPERIMENTAL_*delimiter, and remove once ready to stable. For example,OTEL_CONFIG_FILEoriginated from the now deprecatedOTEL_EXPERIMENTAL_CONFIG_FILE. This solution suffers from the issue that you have a potentially long tail deprecated experimental variant to be documented / supported.It seems that
OTEL_ENTITIEShas not gone that route. I'm not sure if that was intentional or not, but we need to fix it and somehow demarcate / delimit thatOTEL_ENTITIESis still experimental and breaking changes to its format / semantics are still allowed.We could go the direction of
OTEL_CONFIG_FILEand change it toOTEL_EXPERIMENTAL_ENTITIESuntil ready for maturity.Alternatively, we could go the direction @jsuereth has gone in the java entities prototype and add a secondary
OTEL_EXPERIMENTAL_ENTITIES_ENABLEDenv var. IfOTEL_EXPERIMENTAL_ENTITIES_ENABLED=true, that prompts the SDK to parseOTEL_ENTITIES. The advantage of this approach is that its less churn if we manage to promoteOTEL_ENTITIESto stable without breaking changes to the format. This is appealing and I favor this approach.