[entities] Specifying entity information via an environment variable

[dmitryax]

Add a document on how to inject entity information into workloads using new environment variable OTEL_ENTITIES.

Related issue: #4140
Related OTEP: https://github.com/open-telemetry/opentelemetry-specification/blob/main/oteps/entities/0264-resource-and-entities.md

[marcalff]

I am really puzzled by this.

The declarative configuration project was done to declare all the configuration in a structured document, in yaml, because this could not fit into environment variables, which have limitations for complex objects.

And here, an environment variable is used, that contains a structured document with yet another internal syntax, to model an arbitrary complex object.

Complex resources can be already described, for example:

https://github.com/open-telemetry/opentelemetry-configuration/blob/8f5ba4824e60e3d15309412c19b35dac017b7e5e/examples/kitchen-sink.yaml#L783

resource:
  # Configure resource attributes. Entries have higher priority than entries from .resource.attributes_list.
  # Entries must contain .name and .value, and may optionally include .type. If an entry's .type omitted or null, string is used.
  # The .value's type must match the .type. Values for .type include: string, bool, int, double, string_array, bool_array, int_array, double_array.
  attributes:
    - name: service.name
      value: unknown_service
    - name: string_key
      value: value
      type: string
    - name: bool_key
      value: true
      type: bool
    - name: int_key
      value: 1
      type: int
    - name: double_key
      value: 1.1
      type: double
    - name: string_array_key
      value: [ "value1", "value2" ]
      type: string_array
    - name: bool_array_key
      value: [ true, false ]
      type: bool_array
    - name: int_array_key
      value: [ 1, 2 ]
      type: int_array
    - name: double_array_key
      value: [ 1.1, 2.2 ]
      type: double_array
  # Configure resource attributes. Entries have lower priority than entries from .resource.attributes.
  # The value is a list of comma separated key-value pairs matching the format of OTEL_RESOURCE_ATTRIBUTES. See https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/configuration/sdk-environment-variables.md#general-sdk-configuration for details.
  # If omitted or null, no resource attributes are added.
  attributes_list: "service.namespace=my-namespace,service.version=1.0.0"

Please clarify why we need OTEL_ENTITIES with a different complex format, and how this coexists with https://github.com/open-telemetry/opentelemetry-configuration

[dmitryax]

This implements the original OTEP https://github.com/open-telemetry/opentelemetry-specification/blob/main/oteps/entities/0264-resource-and-entities.md#environment-variable-detector

This doesn't mean that this is the only way to pass entities to the SDKs. We should definitely support defining entities in the config schema.

However, we still need to provide an alternative (read as replacement) for OTEL_RESOURCE_ATTRIBUTES env var. We could potentially decide that the entities can be only passed to SDK via the config yaml, but this has to be an explicit decision that goes again the OTEP.

Are we sure that the config interface can be used in any possible environment and for any SDK where the env vars are supported?

[dmitryax]

@open-telemetry/operator-approvers do you see any problems with passing this env var to the SDKs instead of OTEL_RESOURCE_ATTRIBUTES?

[pellared]

As far as I understand the current design decision is that in order to add a new env variable we need to be sure that it would interoperate well with declarative config:

• Deprecate environment variables which do not interoperate with file config when ready for stabilization #3967

I do not say that it means that ideas behind the OTEP is wrong.
Maybe the declarative config design should be improved to support better such scenarios?

Moreover, I think the idea is to also add configuration capabilities to declarative configuration first.

CC @open-telemetry/configuration-approvers

[marcalff]

This implements the original OTEP https://github.com/open-telemetry/opentelemetry-specification/blob/main/oteps/entities/0264-resource-and-entities.md#environment-variable-detector

This doesn't mean that this is the only way to pass entities to the SDKs. We should definitely support defining entities in the config schema.

However, we still need to provide an alternative (read as replacement) for OTEL_RESOURCE_ATTRIBUTES env var. We could potentially decide that the entities can be only passed to SDK via the config yaml, but this has to be an explicit decision that goes again the OTEP.

Are we sure that the config interface can be used in any possible environment and for any SDK where the env vars are supported?

If I understand correctly:

• Entities can be passed as an environment variable, OTEL_ENTITIES, this is one possibility
• We can also extend the declarative configuration spec to support entities
• Both ways are complementary, so this sounds ok.
  • [edit] or ok-ish, the migration from env var to yaml will be more difficult.

Now, from a project management perspective:

• It is correct that adoption of the declarative configuration in each SDK will most likely take some time
• Implementing an environment variable instead seem to be easier, and therefore is anticipated to be delivered sooner

However, the data provided by this new environment variable is not just a string.

It will take to implement a parser for the new document format, in every SIG SDK, to support it.

This is putting more load on each SIG, because now things have to be done twice, and differently.

[Edit 2025-07-24]

Options are:

• Implement an environment variable first, and a yaml syntax later, for each SIGs
  • More duplication of work, but less delay to have something delivered.
• Prioritize the yaml syntax, making the environment variable not needed, for each SIG.
  • Less duplication of work, but more delay to have something delivered for entities.

Something for the TC to discuss I guess.

IF the decision comes to have an environment variable added, then,
for the greater good, I -- cough -- will support the new environment variable OTEL_ENTITIES, because we need uniformity between all SIG SDKs: configuration is global to the opentelemetry project, not per SDK, and most SDK do not have declarative configuration implemented yet.

The sooner every SIG supports declarative configuration, the better, so we won't have this arbitration to do for each proposed change.

[End of Edit 2025-07-24]

Once this PR is merged in specs, it would be good to see a sibling PR to support entities in declarative configuration, because we can not afford to maintain two diverging branches about two diverging ways to provide configuration, and we can not afford to hinder adoption of declarative configuration because a new environment variable only feature is available, preventing migration.

[carlosalberto]

@marcalff From the Spec call last Tuesday (29/07/25): file configuration and environment variables are considered orthogonal for this specific Entity scenario, and thus this new variable should be supported (and specifically required by cloud vendors).

[github-actions]

This PR was marked stale due to lack of activity. It will be closed in 7 days.

[dyladan]

In general I think the format, parsing, and handling work well. What I wonder is why it is specified differently than other entity detectors? We have been moving as a SIG towards specifying entities more similar to other signals with a clear split between API and SDK, and "instrumentation-like" entity detectors which call API methods. Is there a reason for this ENV behavior to be built into the SDK outside of that paradigm? Can't this be just another entity detector, possibly enabled by default? Advantages of that approach would be that users can set precedence using the same mechanisms they do for other entity detectors and other SDKs may benefit from the same component.

[lmolkova]

/cc @RohitRanjanMS in case you're interested - this maybe relevant for Azure Functions as a future way to provide resource (entity) information along with declarative configuration.