Skip to content

Commit 9efeb89

Browse files
dmitryaxdmitryax
committed
[entities] Specifying entity information via an environment variable
Add a document on how to inject entity information into workloads using new environment variable OTEL_ENTITIES.
1 parent 4b630d8 commit 9efeb89

3 files changed

Lines changed: 230 additions & 0 deletions

File tree

‎specification/configuration/sdk-environment-variables.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -172,6 +172,7 @@ representing it MUST be `"none"`.
172172
| Name | Description | Default | Type | Notes |
173173
|--------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
174174
| OTEL_SDK_DISABLED | Disable the SDK for all signals | false | [Boolean][] | If "true", a no-op SDK implementation will be used for all telemetry signals. Any other value or absence of the variable will have no effect and the SDK will remain enabled. This setting has no effect on propagators configured through the OTEL_PROPAGATORS variable. |
175+
| OTEL_ENTITIES | Entity information to be associated with the resource | | [String][] | See [Entities SDK](../entities/entity-propagation.md#specifying-entity-information-via-an-environment-variable) for more details. |
175176
| OTEL_RESOURCE_ATTRIBUTES | Key-value pairs to be used as resource attributes | See [Resource semantic conventions](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/resource/README.md#semantic-attributes-with-dedicated-environment-variable) for details. | [String][] | See [Resource SDK](../resource/sdk.md#specifying-resource-information-via-an-environment-variable) for more details. |
176177
| OTEL_SERVICE_NAME | Sets the value of the [`service.name`](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/resource/README.md#service) resource attribute | | [String][] | If `service.name` is also provided in `OTEL_RESOURCE_ATTRIBUTES`, then `OTEL_SERVICE_NAME` takes precedence. |
177178
| OTEL_LOG_LEVEL | Log level used by the [SDK internal logger](../error-handling.md#self-diagnostics) | "info" | [Enum][] | |

‎specification/entities/README.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,13 @@ path_base_for_github_subdir:
2323
Entity represents an object of interest associated with produced telemetry:
2424
traces, metrics, logs, profiles etc.
2525

26+
Entities can be instantiated through two complementary approaches:
27+
28+
1. **Pull-based Model**: Entities discover themselves from the current environment by examining the runtime context, system properties, metadata services, and other available sources of entity information.
29+
30+
2. **Push-based Model**: Entities are explicitly provided from external sources, typically through environment variables or configuration. This approach allows entity information to be propagated across process boundaries. See [Entity Propagation](./entity-propagation.md) for more details.
31+
2632
## Specifications
2733

2834
- [Data Model](./data-model.md)
35+
- [Entity Propagation](./entity-propagation.md) - Describes the push-based model for entity instantiation

‎specification/entities/entity-propagation.md‎

Lines changed: 222 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,222 @@
1+
<!--- Hugo front matter used to generate the website version of this page:
2+
linkTitle: Entity Propagation
3+
--->
4+
5+
# Entity Propagation
6+
7+
**Status**: [Development](../document-status.md)
8+
9+
<details>
10+
<summary>Table of Contents</summary>
11+
12+
<!-- toc -->
13+
14+
- [Overview](#overview)
15+
- [Specifying entity information via an environment variable](#specifying-entity-information-via-an-environment-variable)
16+
* [Format Specification](#format-specification)
17+
* [Grammar](#grammar)
18+
* [Examples](#examples)
19+
* [Parsing Algorithm](#parsing-algorithm)
20+
* [Character Encoding](#character-encoding)
21+
* [Validation Requirements](#validation-requirements)
22+
* [Error Handling](#error-handling)
23+
* [Environment Variable Conflict Resolution](#environment-variable-conflict-resolution)
24+
- [EntityDetector](#entitydetector)
25+
26+
<!-- tocstop -->
27+
28+
</details>
29+
30+
## Overview
31+
32+
Entity propagation provides a mechanism to pass entity information across
33+
process boundaries using environment variables. This allows entities to be
34+
shared between parent and child processes, similar to how trace context is
35+
propagated in distributed systems. This approach is particularly useful when
36+
the outside process knows more about the child entity than the child process
37+
can discover on its own.
38+
39+
Common scenarios where entity propagation is beneficial include:
40+
41+
- Container orchestration systems where the orchestrator knows container metadata
42+
- CI/CD pipelines where the build system knows job and environment details
43+
- Batch processing systems where the scheduler knows task context
44+
- Command-line tools spawned with specific entity context
45+
46+
Environment variables provide a reliable, cross-platform mechanism for this
47+
propagation since they are automatically inherited by child processes and
48+
available during process initialization.
49+
50+
## Specifying entity information via an environment variable
51+
52+
To enable standardized entity propagation across OpenTelemetry implementations,
53+
this specification defines the `OTEL_ENTITIES` environment variable format and
54+
processing requirements.
55+
56+
The SDK SHOULD provide an `EntityDetector` which will use the `OTEL_ENTITIES` environment
57+
variable to discover and associate defined entities with the resource.
58+
59+
The `OTEL_ENTITIES` environment variable contains a list of entities in a
60+
compact format designed for human readability and concise representation.
61+
62+
### Format Specification
63+
64+
Each entity follows this structure:
65+
66+
```
67+
type{id_key1=id_value1,id_key2=id_value2}[desc_key1=desc_value1,desc_key2=desc_value2]@schema_url
68+
```
69+
70+
Where:
71+
72+
- `type` is the entity type (required, e.g., "service", "host", "container")
73+
- `{...}` contains identifying attributes as comma-separated key=value pairs (required, at least one pair)
74+
- `[...]` contains descriptive attributes as comma-separated key=value pairs (optional)
75+
- `@schema_url` specifies the Schema URL for the entity (optional)
76+
77+
Multiple entities are separated by semicolons (`;`).
78+
79+
### Grammar
80+
81+
```
82+
entities := entity (";" entity)*
83+
entity := type id_attrs desc_attrs? schema_url? | ""
84+
type := [a-zA-Z][a-zA-Z0-9._-]*
85+
id_attrs := "{" key_value_list "}"
86+
desc_attrs := "[" key_value_list "]"
87+
schema_url := "@" url_string
88+
key_value_list := key_value ("," key_value)*
89+
key_value := key "=" value
90+
key := [a-zA-Z][a-zA-Z0-9._-]*
91+
value := [^{}[\]@;,=]*
92+
url_string := [^;]*
93+
```
94+
95+
### Examples
96+
97+
```bash
98+
# Single service entity
99+
OTEL_ENTITIES="service{service.name=my-app,service.instance.id=instance-1}[service.version=1.0.0]"
100+
101+
# Multiple entities with schema URL
102+
OTEL_ENTITIES="service{service.name=my-app,service.instance.id=instance-1}[service.version=1.0.0]@https://opentelemetry.io/schemas/1.21.0;host{host.id=host-123}[host.name=web-server-01]"
103+
104+
# Kubernetes pod entity
105+
OTEL_ENTITIES="k8s.pod{k8s.pod.uid=pod-abc123}[k8s.pod.name=my-pod,k8s.pod.label.app=my-app]"
106+
107+
# Container with host (minimal descriptive attributes)
108+
OTEL_ENTITIES="container{container.id=cont-456};host{host.id=host-789}[host.name=docker-host]"
109+
110+
# Minimal entity (only required fields)
111+
OTEL_ENTITIES="service{service.name=minimal-app}"
112+
113+
# Empty strings are allowed (leading, trailing, and consecutive semicolons are ignored)
114+
OTEL_ENTITIES=";service{service.name=app1};;host{host.id=host-123};"
115+
```
116+
117+
### Parsing Algorithm
118+
119+
1. Split the input string by semicolons (`;`) to get individual entity definitions
120+
2. For each entity definition:
121+
a. Skip if the entity definition is empty (allows consecutive semicolons and leading/trailing semicolons)
122+
b. Extract the entity type (everything before the first `{`)
123+
c. Extract identifying attributes from `{...}` block
124+
d. Extract descriptive attributes from `[...]` block (if present)
125+
e. Extract schema URL from `@...` portion (if present)
126+
3. Parse key-value lists using comma (`,`) as separator and equals (`=`) for assignment
127+
4. Validate that each entity has a non-empty type and at least one identifying attribute
128+
5. Create entity objects and associate them with the resource
129+
130+
### Character Encoding
131+
132+
All attribute values MUST be considered strings and characters outside the
133+
`baggage-octet` range MUST be percent-encoded following the [W3C Baggage](https://www.w3.org/TR/baggage/#header-content) specification.
134+
135+
The reserved characters `{}[]@;,=` MUST be percent-encoded when they appear literally in attribute values:
136+
137+
- `{` → `%7B`
138+
- `}` → `%7D`
139+
- `[` → `%5B`
140+
- `]` → `%5D`
141+
- `@` → `%40`
142+
- `;` → `%3B`
143+
- `,` → `%2C`
144+
- `=` → `%3D`
145+
146+
**Example:**
147+
148+
```bash
149+
# Entity with reserved characters in attribute values
150+
OTEL_ENTITIES="service{service.name=my%2Capp,service.instance.id=inst-1}[config=key%3Dvalue%5Bprod%5D]"
151+
# Resolves to: service.name="my,app", config="key=value[prod]"
152+
```
153+
154+
### Validation Requirements
155+
156+
- Entity type MUST NOT be empty and MUST match the pattern `[a-zA-Z][a-zA-Z0-9._-]*`
157+
- At least one identifying attribute MUST be present in the `{...}` block
158+
- Attribute keys MUST NOT be empty and SHOULD follow OpenTelemetry semantic conventions
159+
- Schema URL, if present, MUST be a valid URI
160+
- Entity types SHOULD follow existing OpenTelemetry entity naming conventions (e.g., "service", "host", "container", "k8s.pod")
161+
162+
### Error Handling
163+
164+
The SDK SHOULD be resilient to malformed input and follow these error handling rules:
165+
166+
1. **Invalid syntax**: If the environment variable contains invalid syntax, the SDK SHOULD log a warning and ignore the malformed portions while processing valid parts
167+
168+
Example: `OTEL_ENTITIES="service{service.name=app1};invalid{syntax;service{service.name=app2}"` processes the first valid entity and skips the malformed part
169+
170+
2. **Missing required fields**: If an entity is missing required fields (type or identifying attributes), the SDK SHOULD log a warning and skip that entity
171+
172+
Example: `OTEL_ENTITIES="service{};host{host.id=123}"` skips the service entity (no identifying attributes) and processes the host entity
173+
174+
3. **Duplicate entities**: If multiple entities of the same type with identical identifying attributes are defined, the SDK SHOULD use the last occurrence and SHOULD log a warning
175+
176+
Example: `OTEL_ENTITIES="service{service.name=app1}[version=1.0];service{service.name=app1}[version=2.0]"` uses `version=2.0`
177+
178+
4. **Schema URL validation**: If a schema URL is present but invalid, the SDK SHOULD log a warning and ignore the URL while processing the entity
179+
180+
Example: `OTEL_ENTITIES="service{service.name=app1}@invalid-url"` processes the entity but ignores the invalid URL
181+
182+
5. **Conflicting identifying attributes**: If two entities of the same type define different values for the same identifying attribute key, the SDK SHOULD treat them as separate entities. If this results in ambiguous entity identification, the SDK SHOULD log a warning and preserve only the last entity
183+
184+
Example: `OTEL_ENTITIES="service{service.name=app1};service{service.name=app2}"` creates only service.name=app2 entity
185+
186+
6. **Conflicting descriptive attributes**: If two entities define different values for the same descriptive attribute key, the SDK SHOULD use the value from the last entity definition and SHOULD log a warning. The conflicting attributes SHOULD NOT be recorded for entities other than the last one
187+
188+
Example: `OTEL_ENTITIES="service{service.name=app1}[version=1.0];service{service.name=app2}[version=2.0]"` results in app1 service without version attribute and app2 service with `version=2.0`
189+
190+
### Environment Variable Conflict Resolution
191+
192+
When multiple environment variables define overlapping configuration, a warning should be logged and the following precedence order applied (highest to lowest precedence):
193+
194+
1. **Programmatic configuration**: Entities configured via SDK API take highest precedence and override all environment variable configurations
195+
2. **OTEL_ENTITIES**: Entity definitions from this environment variable override resource attributes and other OTEL_* environment variables for the same attribute keys
196+
3. **OTEL_SERVICE_NAME**: Takes precedence over `service.name` in `OTEL_RESOURCE_ATTRIBUTES` but is overridden by `service.name` in `OTEL_ENTITIES`
197+
4. **Other specific OTEL_* variables**: Individual environment variables (when they exist) take precedence over equivalent attributes in `OTEL_RESOURCE_ATTRIBUTES`
198+
5. **OTEL_RESOURCE_ATTRIBUTES**: Lowest precedence for overlapping attribute keys
199+
200+
**Precedence rules within OTEL_ENTITIES:**
201+
202+
- When the same entity type appears multiple times with identical identifying attributes, the last occurrence takes precedence
203+
204+
**Example of conflict resolution:**
205+
206+
```bash
207+
# These environment variables:
208+
OTEL_SERVICE_NAME="old-service-name"
209+
OTEL_RESOURCE_ATTRIBUTES="service.name=resource-service,host.name=resource-host,custom.attr=resource-value"
210+
OTEL_ENTITIES="service{service.name=entity-service,service.instance.id=inst-1}[service.version=1.0.0];host{host.id=host-123}[host.name=entity-host]"
211+
212+
# Result in:
213+
# - Service entity with identifying attributes: {service.name=entity-service, service.instance.id=inst-1} (from OTEL_ENTITIES, overrides others)
214+
# and descriptive attributes: {service.version=1.0.0}
215+
# - Host entity with identifying attributes: {host.id=host-123}
216+
# and descriptive attributes: {host.name=entity-host} (from OTEL_ENTITIES, overrides OTEL_RESOURCE_ATTRIBUTES)
217+
# - Resource: remaining attributes from OTEL_RESOURCE_ATTRIBUTES that don't conflict: {custom.attr=resource-value}
218+
```
219+
220+
## EntityDetector
221+
222+
TODO: fill out

0 commit comments

Comments
 (0)