Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,8 @@ release.

### SDK Configuration

- Declarative configuration: add `Get distribution config` operation to the `Config Provider` specification.
([#4770](https://github.com/open-telemetry/opentelemetry-specification/issues/4770))
- Declarative configuration: clarify default behavior and validation
requirements of `create` and `parse`.
([#4780](https://github.com/open-telemetry/opentelemetry-specification/pull/4780))
Expand Down
24 changes: 19 additions & 5 deletions specification/configuration/api.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,7 @@ weight: 1
* [ConfigProvider](#configprovider)
+ [ConfigProvider operations](#configprovider-operations)
- [Get instrumentation config](#get-instrumentation-config)
- [Get distribution config](#get-distribution-config)
* [ConfigProperties](#configproperties)

<!-- tocstop -->
Expand All @@ -36,19 +37,20 @@ It consists of the following main components:
### ConfigProvider

`ConfigProvider` provides access to configuration properties relevant to
instrumentation.
instrumentation and distribution.

Instrumentation libraries access `ConfigProvider` during
initialization. `ConfigProvider` may be passed as an argument to the
instrumentation library, or the instrumentation library may access it from a
central place. Thus, the API SHOULD provide a way to access a global
Instrumentation libraries and vendor's custom code can access `ConfigProvider` during
and after initialization. `ConfigProvider` may be passed as an argument, or may be accessed from a
central place.
Thus, the API SHOULD provide a way to access a global
default `ConfigProvider`, and set/register it.

#### ConfigProvider operations

The `ConfigProvider` MUST provide the following functions:

* [Get instrumentation config](#get-instrumentation-config)
* [Get distribution config](#get-distribution-config)
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All instrumentation will have access to this. The original design of ConfigProvider intentionally limited the scope to the .instrumentation/development node, so as to avoid the questions about whether its appropriate / safe for instrumentation to have access to the SDK config model, including any secrets that may be present on the exporter nodes.

If we want to broaden scope, we need to have that conversation since its very reasonable that .distribution node will have the types of secrets that are in the SDK config model.

On a related note, why is this necessary?

The declarative config has separate parse and create methods that allow a distribution to access the .distribution node. For example in java:

OpenTelemetryConfigurationModel model = parse(new File(System.getEnv("OTEL_EXPERIMENTAL_CONFIG_FILE")));
DistributionModel distribution = model.getDistribution();
OpenTelemetrySdk sdk = create(model);

If there's not a strong need for this, the safe answer is to continue the status quo and not grant instrumentation access to more config than they need.

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm sorry for the delayed response—I was on vacation.

ConfigProvider exposes instrumentation configuration in a clear and consistent way for all languages. I wanted the distribution configuration to be exposed consistently among languages as well. I believe this would be very beneficial, which is why this PR was created.

Regarding the recommended alternative approach, I see some issues with it:

  1. It does not really improve security over the ConfigProvider extension. Extracting secrets from the declarative config file is still possible when calling the parse method, right? At the same time, it complicates life for honest developers.
  2. The Java example above is problematic for Otel Java Agent-based distributions that need distribution configuration settings in AgentListeners. The SDK is configured from AgentInstaller without any extension hooks that could be used, so the config file would have to be parsed again in each listener to extract DistributionModel. Of course, we could create a dedicated AgentListener that parses the config and stores it in some static variable, but in my opinion, that starts to get tricky.
  3. It will lead to inconsistent implementations among languages.

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ad 2 - instead of dedicated AgentListener we could use custom DeclarativeConfigurationCustomizerProvider that takes DistributionModel from OpenTelemetryConfigurationModel and then stores it in some static field, so it can be used later on. I still think that ConfigProvider solution is better in terms of clarity and standardization.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@robsunday I have implemented exactly what you suggested - and only saw your comment now.

My takeaway was also that it starts to get tricky with statics - see open-telemetry/opentelemetry-java-instrumentation#15822


TODO: decide if additional operations are needed to improve API ergonomics

Expand All @@ -64,6 +66,18 @@ If the `.instrumentation` node is not set, get instrumentation config MUST
return nil, null, undefined or another language-specific idiomatic pattern
denoting empty.

##### Get distribution config

Obtain configuration relevant to a distribution.

**Returns:** [`ConfigProperties`](#configproperties) representing
the [`.distribution`](https://github.com/open-telemetry/opentelemetry-configuration/blob/670901762dd5cce1eecee423b8660e69f71ef4be/examples/kitchen-sink.yaml#L438-L439)
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

the link points to the .instrumentation node

configuration mapping node.

If the `.distribution` node is not set, get distribution config MUST
return nil, null, undefined or another language-specific idiomatic pattern
denoting empty.

### ConfigProperties

`ConfigProperties` is a programmatic representation of a configuration mapping
Expand Down
5 changes: 3 additions & 2 deletions specification/configuration/sdk.md
Original file line number Diff line number Diff line change
Expand Up @@ -64,8 +64,9 @@ the name `Configuration` is RECOMMENDED.

The SDK implementation of [`ConfigProvider`](./api.md#configprovider) MUST be
created using a [`ConfigProperties`](./api.md#configproperties) representing
the [`.instrumentation`](https://github.com/open-telemetry/opentelemetry-configuration/blob/670901762dd5cce1eecee423b8660e69f71ef4be/examples/kitchen-sink.yaml#L438-L439)
mapping node of the [configuration model](./data-model.md).
the [`.instrumentation`](https://github.com/open-telemetry/opentelemetry-configuration/blob/41518147ca741d6ce811f143ce463630147c9986/examples/kitchen-sink.yaml#L378-L433)
and [`.distribution`](https://github.com/open-telemetry/opentelemetry-configuration/blob/41518147ca741d6ce811f143ce463630147c9986/examples/kitchen-sink.yaml#L434-L436)
mapping nodes of the [configuration model](./data-model.md).

### SDK extension components

Expand Down
Loading