Skip to content

sdk-config: refactor .instrumentation processing - #2076

Merged
brettmc merged 18 commits into
open-telemetry:mainfrom
brettmc:decl-config-missing-file
Oct 21, 2026
Merged

brettmc merged 18 commits into
open-telemetry:mainfrom
brettmc:decl-config-missing-file

Conversation

@brettmc

@brettmc brettmc commented Oct 14, 2026 •

Copy link
Copy Markdown
Contributor

Closes: #2075

Parse the declarative config document once

A missing or unparseable OTEL_CONFIG_FILE no longer blows up.

Single parse, two roots

Configuration::parseFile() now loads the document once and processes the resulting arrays
against both configuration roots. The SDK root stays lazy behind create(); a new
getInstrumentationConfig() accessor serves the instrumentation root.

SdkAutoloader::autoload() was the other half of the problem: it built one Configuration
eagerly for instrumentation config and a second inside the deferred Globals initializer. It
now parses once and threads the instance into both consumers.

The two roots stay separate on purpose, and the reasoning is now recorded on
InstrumentationConfigurationRegistry rather than carried as a @todo to remove them.
/development is exempt from the file format's versioning guarantees, so it is the part of the
document most likely to disagree with what we can parse. Keeping it a separate root gives it
independent failure: a node that does not validate costs the caller its instrumentation config
and leaves the SDK configured. ignoreExtraKeys() and IgnoresUnknownProviders only tolerate
unknown keys and unregistered providers — not a known node that fails type validation.

Instrumentation config is resolved during autoload, under its own try/catch, because hooks must
be installed before the first instrumented call. An exception during processing is reported
verbatim, which provides more useful detail.

Deep copy between roots

Processing one document against two roots exposed a latent aliasing bug. Under ext-yaml,
YAML aliases materialise as genuine PHP references (symfony/yaml deep-copies instead), and
references survive the by-value copy Processor::process() makes. Environment substitution
writes back into the array it is given, so the first root processed would mutate what the second
sees:

without the copy:  shared.ca_file  "${MY_CA}" -> "/env/ca.pem"   (leaked)
with the copy:     shared.ca_file  "${MY_CA}"                    (intact)

Related fixes

  • ConfigProviderInterface::getInstrumentationConfig() takes a Context. Both
    implementations are updated. Config\SDK\ConfigProvider now logs through
    $context->logger instead of LogsMessagesTrait, so a caller-supplied logger is actually
    honoured — previously a warning was filtered by the global log level and could be discarded
    despite the caller asking for it.
  • Configuration::getList() narrowed to list<string>. It was declared : array, wider
    than the string|list<string> that parseFile() accepts, so both callers carried a
    @psalm-suppress ArgumentTypeCoercion. ListParser::parse() now satisfies list<string> on
    every branch; its is_array() branch previously passed maps and non-strings through
    untouched. All twelve getList() callers already assumed a list of names.
  • instrumentation/development schema is statically declared, adding general.http and
    semconv support (file format 1.0) and tolerating unknown php entries with a warning rather
    than a hard failure.
  • Config\SDK\ConfigProvider registered under SPI as the spec's entry point for
    instrumentations that read config without the SDK. It is deliberately not on the
    autoloader's path, where resolving it would cost a second parse.
  • String lists actually enforce strings: sensitive_query_parameters, request_captured_headers, response_captured_headers, known_methods — Symfony's scalarPrototype() let ints/floats/bools through to HttpConfig; now Validation::ensureString() on each

YAML alias security/robustness (ext-yaml only)

Pre-existing bugs that copilot identified during review, fixed here for convenience.

  • Env-var leak via direct aliases fixed. ext-yaml turns b: *a into a PHP reference; substitution wrote back through it, so $${FOO} escaped-literal resolved to FOO's value and placeholder-looking values got re-expanded — violating the spec's "env vars MUST NOT be injectable via env vars". Loader now copies by value; Configuration::copy() removed as redundant. New alias-escaped-substitution.yaml fixture. (35cbc59)
  • Recursive aliases (a: &x [*x]) no longer exhaust memory. Was an uncatchable fatal during synchronous autoload; now depth-bounded and reported as an invalid file. (Copilot review on sdk-config: refactor .instrumentation processing #2076) (8765e72)
  • YamlBackendParityTest: both backends must parse all 54 fixtures identically.
  • ext-yaml installed in CI (php.yml) The yaml-gated guards silently skipped. Improve test coverage of both ext-yaml and symfony/yaml
  • ext-yaml added to base developer image: local testing (make test etc) now exercises ext-yaml

sdk-configuration constraints bumped to what should be the next versions released:
open-telemetry/api ^1.11, open-telemetry/sdk ^1.16.

Breaking changes

ConfigProviderInterface::getInstrumentationConfig() gains an optional Context parameter.
Source-compatible for callers; implementors outside this repo must update their signature. The
interface is marked @experimental.

Assisted-By: Claude Code

`instrumentation/development` is a sibling of `tracer_provider` etc in the same
document, so parsing it through a separate entry point read and
env-substituted the file twice.

Configuration::parseFile() now loads the file once and processes the
arrays against both roots. The SDK root stays lazy behind create(); the
new getInstrumentationConfig() accessor processes the instrumentation
root on demand, so a file whose instrumentation block we cannot parse
does not stop the SDK from being configured. Each processor gets a deep
copy, since YAML aliases can materialise as PHP references that survive
the by-value copy Processor::process() makes.

Config\SDK\Instrumentation becomes a deprecated thin delegate, and
SdkAutoloader resolves instrumentation config through an SPI
ConfigProviderInterface rather than calling it directly — `sdk` only
suggests `sdk-configuration`, so the indirection degrades to the API's
noop provider when the package is absent.

Folds in the `semconv` and `general` schema nodes, which empties
knownInstrumentationParseFailures(). `general` becomes a fixed node
rather than a component map, since a scalar sibling such as
`stability_opt_in_list` cannot resolve to a provider; its values are
validated but not yet exposed, as nothing in-tree reads them. Unknown
keys under `instrumentation/development` are dropped rather than
rejected, matching Java.

Removing the second parse is what makes the eager path guardable, so a
missing or unparseable OTEL_CONFIG_FILE now logs an initialization error
and degrades to a noop SDK instead of killing the process with exit 255.

ConfigProviderInterface gains an optional Context parameter, which is
technically breaking for external implementors — see the PR for why that
is acceptable now rather than later.

Fixes open-telemetry#2075

Co-Authored-By: Claude Code
300724d made Configuration::parseFile() serve both configuration roots from
one document, but SdkAutoloader built one Configuration eagerly for
instrumentation config and a second inside the deferred Globals initializer,
reading and env-substituting the file twice.

autoload() now parses once and threads the instance into both consumers.
Instrumentation config is resolved under its own try/catch, so a document
whose instrumentation/development node does not validate still leaves the SDK
configured; an Error there is reported as a version mismatch instead, since
`sdk` can only suggest sdk-configuration and the two release separately.
Covered by a new fixture and test.

SdkAutoloader no longer resolves ConfigProviderInterface over SPI, which
would cost the second parse; Config\SDK\ConfigProvider stays as the spec's
entry point for instrumentations that read configuration without the SDK.

Bumps sdk-configuration's constraints to the releases carrying the API it now
uses: sdk ^1.16 and api ^1.11.

Also rewrites the comments that treated the eager/deferred split and the
separate instrumentation root as costs to be removed. Both are deliberate:
hooks must be installed before the first instrumented call, and the separate
root is what gives that node independent failure while /development remains
exempt from the file format's versioning guarantees.
getList() was declared `: array`, which is wider than the `string|list<string>`
that Config\SDK\Configuration::parseFile() accepts, so both of its callers
carried a @psalm-suppress ArgumentTypeCoercion rather than the type being
provable.

ListParser::parse() now satisfies list<string> on every branch. The empty and
comma-separated branches already did; the is_array() branch returned its input
unchanged, so a map or a list of non-strings passed straight through. It now
discards keys and stringifies values, which is what all twelve getList()
callers already assumed — they feed the result to things expecting a list of
names (exporters, propagators, detectors, config file paths).
note this is a BC break for implementors, but ok given the 0.x stability of the package
@codecov

codecov Bot commented Oct 14, 2026 •

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 14.93506% with 131 lines in your changes missing coverage. Please review.
✅ Project coverage is 66.29%. Comparing base (fa9ce32) to head (7010090).
⚠️ Report is 2 commits behind head on main.

Files with missing lines Patch % Lines
...tProvider/InstrumentationConfigurationRegistry.php 0.00% 66 Missing ⚠️
src/Config/SDK/Configuration.php 0.00% 24 Missing ⚠️
...Provider/Instrumentation/General/SemconvConfig.php 0.00% 11 Missing ⚠️
...Configuration/Internal/ConfigurationFileLoader.php 0.00% 11 Missing ⚠️
...K/Configuration/Loader/YamlExtensionFileLoader.php 0.00% 10 Missing ⚠️
...der/Instrumentation/General/HttpConfigProvider.php 0.00% 6 Missing ⚠️
src/Config/SDK/Instrumentation.php 0.00% 2 Missing ⚠️
src/SDK/SdkAutoloader.php 92.85% 1 Missing ⚠️
Additional details and impacted files

Impacted file tree graph

@@             Coverage Diff              @@
##               main    #2076      +/-   ##
============================================
- Coverage     66.98%   66.29%   -0.70%     
- Complexity     3130     3146      +16     
============================================
  Files           456      459       +3     
  Lines          9212     9306      +94     
============================================
- Hits           6171     6169       -2     
- Misses         3041     3137      +96     
Flag Coverage Δ
8.1 66.08% <14.93%> (-0.68%) ⬇️
8.2 66.19% <14.93%> (-0.67%) ⬇️
8.3 66.21% <14.93%> (-0.68%) ⬇️
8.4 66.19% <14.93%> (-0.68%) ⬇️
8.5 66.22% <14.93%> (-0.65%) ⬇️
8.6 66.25% <14.93%> (-0.59%) ⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines Coverage Δ
...rc/API/Configuration/Noop/NoopConfigProperties.php 100.00% <ø> (ø)
src/API/Configuration/Noop/NoopConfigProvider.php 100.00% <ø> (ø)
src/Config/SDK/ConfigProvider.php 100.00% <100.00%> (ø)
.../Config/SDK/Configuration/ConfigurationFactory.php 100.00% <100.00%> (ø)
src/SDK/Common/Configuration/Configuration.php 96.47% <ø> (ø)
src/SDK/Common/Configuration/Parser/ListParser.php 100.00% <100.00%> (+12.50%) ⬆️
src/SDK/SdkAutoloader.php 92.20% <92.85%> (+0.10%) ⬆️
src/Config/SDK/Instrumentation.php 0.00% <0.00%> (ø)
...der/Instrumentation/General/HttpConfigProvider.php 0.00% <0.00%> (ø)
...K/Configuration/Loader/YamlExtensionFileLoader.php 0.00% <0.00%> (ø)
... and 4 more

... and 3 files with indirect coverage changes


Continue to review full report in Codecov by Harness.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update fa9ce32...7010090. Read the comment docs.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

🟡 Changes recommended

The public API removal, misleading error classification, nested schema strictness, and ineffective aliasing regression test remain unresolved.

4 open findings
What changed in this PR

Refactors declarative SDK and instrumentation configuration to share one parsed document while retaining independent validation.

Changes:

  • Adds instrumentation access through Configuration and SPI.
  • Expands the development instrumentation schema.
  • Improves list parsing, context-aware logging, and failure handling.
File Description
composer.json Registers the configuration SPI provider.
examples/​instrumentation/​configure_instrumentation.php Uses the unified configuration API.
src/​API/​Configuration/​ConfigProviderInterface.php Adds context-aware retrieval.
src/​API/​Configuration/​Noop/​NoopConfigProperties.php Marks the noop implementation experimental.
src/​API/​Configuration/​Noop/​NoopConfigProvider.php Accepts configuration context.
src/​Config/​SDK/​ComponentProvider/​Instrumentation/​General/​HttpConfigProvider.php Adds HTTP semantic-convention schema.
src/​Config/​SDK/​ComponentProvider/​Instrumentation/​General/​SemconvConfig.php Defines semantic-convention settings.
src/​Config/​SDK/​ComponentProvider/​InstrumentationConfigurationRegistry.php Statically defines instrumentation configuration.
src/​Config/​SDK/​composer.json Updates constraints and SPI registration.
src/​Config/​SDK/​ConfigProvider.php Implements file-backed SPI configuration.
src/​Config/​SDK/​Configuration.php Shares parsed documents across configuration roots.
src/​Config/​SDK/​Configuration/​ConfigurationFactory.php Extracts file-loading logic.
src/​Config/​SDK/​Configuration/​IgnoresUnknownProviders.php Updates provider-skipping documentation.
src/​Config/​SDK/​Configuration/​Internal/​ConfigurationFileLoader.php Centralizes YAML loading.
src/​Config/​SDK/​Instrumentation.php Removes the former instrumentation entry point.
src/​SDK/​Common/​Configuration/​Configuration.php Narrows list return documentation.
src/​SDK/​Common/​Configuration/​Parser/​ListParser.php Normalizes arrays into string lists.
src/​SDK/​SdkAutoloader.php Reuses parsed configuration during autoload.
tests/​Integration/​Config/​ConfigurationTest.php Tests unified roots and schema handling.
tests/​Unit/​API/​Configuration/​Noop/​NoopConfigProviderTest.php Tests context-compatible noop behavior.
tests/​Unit/​Config/​SDK/​ConfigProviderTest.php Tests SPI loading and logging.
tests/​Unit/​SDK/​fixtures/​otel-sdk-invalid-instrumentation.yaml Adds invalid instrumentation fixture.
tests/​Unit/​SDK/​fixtures/​otel-sdk-invalid.yaml Adds invalid SDK fixture.
tests/​Unit/​SDK/​fixtures/​otel-sdk-malformed.yaml Adds malformed YAML fixture.
tests/​Unit/​SDK/​SdkAutoloaderTest.php Tests configuration failure isolation.

🧠 Review effort: Balanced


💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

Comment thread src/Config/SDK/Configuration.php Resolved
Comment thread src/SDK/SdkAutoloader.php Resolved
Catching Error around getInstrumentationConfig() to blame an outdated
sdk-configuration also caught faults raised by the configuration itself, so
a TypeError from a plugin's createPlugin() was logged as "requires a newer
open-telemetry/sdk-configuration". Let the generic Throwable path report it;
PHP's own message already names the missing method in the skew case.
ext-yaml turns a direct alias (`b: *a`) into a PHP reference, where
symfony/yaml yields independent copies. Environment substitution writes its
result back into the array it normalises, so through a reference the alias
partner received already-substituted text and was substituted a second time.
That is not a no-op: an escaped `$${FOO}` resolved to the value of FOO
instead of staying the literal `${FOO}`, and a value that itself looked like
a placeholder was expanded again — defeating the spec requirement that
environment variables MUST NOT be injectable via environment variables.

Copy by value in the loader so references never enter the pipeline. This
also covers the cacheFile and direct process() paths, which
Configuration::copy() did not, so that method is now redundant and removed.

Predates this PR; affects ext-yaml installs without symfony/yaml.

Install ext-yaml in CI, which never had it: the regression guard above is
gated on the extension, so without this it would silently skip — as would
the two existing yaml-gated tests. Coverage in the config unit tests goes
from 45 tests (4 skipped) to 99.

Add YamlBackendParityTest, asserting both backends parse all 54 fixtures
identically, so a future divergence fails a test rather than reaching users
as a parsing bug.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

🟡 Changes recommended

The ext-yaml alias-copy traversal can recurse indefinitely on cyclic aliases and exhaust the process.

3 open findings
3 resolved since last review
Previously missed (1)

In code that hasn't changed since last review

Medium severity Add array-input coverage for list normalization

src/​SDK/​Common/​Configuration/​Parser/​ListParser.php:18

The new array normalization is not exercised by ListParserTest: its data provider only passes strings, and the arrays there are expected outputs. Add array-input cases covering associative keys and non-string scalar values so the promised reindexing and string coercion cannot regress.

🧠 Review effort: Balanced

Comment thread src/SDK/SdkAutoloader.php Resolved
…memory

ext-yaml resolves a recursive alias (`a: &x [*x]`) into a genuinely
self-referential array, which has no finite by-value copy, so the alias
copying added in 35cbc59 recursed until the memory limit — an uncatchable
fatal, during synchronous autoload, where callers otherwise degrade to a
noop configuration.

Bound the traversal depth and report anything past it as an invalid file.
Identity comparison cannot be used to spot the cycle instead: comparing a
self-referential array raises its own fatal. The deepest configuration this
repository parses, upstream fixtures included, is 9 levels.

Reported by Copilot review on open-telemetry#2076

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

🔵 Needs a closer look

The new schema accepts invalid non-string values, and key normalization and root-isolation behavior lack effective regression coverage.

0 open findings

3 resolved since last review
Previously missed (2)

In code that hasn't changed since last review

Medium severity Enforce string validation for sensitive query parameters

src/​Config/​SDK/​ComponentProvider/​InstrumentationConfigurationRegistry.php:159

The file-format schema requires every sensitive_query_parameters item to be a string, but Symfony's scalarPrototype() also accepts integers, floats, and booleans. As written, schema-invalid input such as [123] is accepted even though this new tree is intended to validate known nodes. Apply the repository's Validation::ensureString() validator to the prototype.

Low severity Cover array key removal and non-string conversion

src/​SDK/​Common/​Configuration/​Parser/​ListParser.php:18

The changed array branch has no unit coverage: ListParserTest only supplies string inputs, so neither associative-key removal nor conversion of non-string values is verified. Add array cases for both behaviors, since they are the reason this branch now guarantees list<string>.

🧠 Review effort: Balanced

The file format declares sensitive_query_parameters, request_captured_headers,
response_captured_headers and known_methods as `items: type: string`, but
Symfony's scalarPrototype() accepts any scalar, so ints, floats and booleans
reached HttpConfig unconverted.

Attach Validation::ensureString() to each prototype, as the SDK schema already
does elsewhere. Covered in both directions: non-string items are rejected, and
environment placeholders still resolve, including values that look numeric.

Also cover ListParser's array branch, which no test reached — the provider
supplied only strings, so neither the key reindexing nor the string coercion
behind its `list<string>` guarantee was exercised.
@brettmc
brettmc requested a balanced review from Copilot October 14, 2026 22:19

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

@brettmc
brettmc marked this pull request as ready for review October 14, 2026 23:41
@brettmc
brettmc requested a review from a team as a code owner October 14, 2026 23:41
namespace OpenTelemetry\API\Configuration;

/**
* @experimental

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

It's late to be marking this experimental now, in a released API, but it's required for correct logging during initialization

*
* @throws InvalidArgumentException if $value nests deeper than {@see self::MAX_DEPTH}
*/
private static function unreference(mixed $value, string $path, int $depth = 0): mixed

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

This resolves a live bug unrelated to this PR, but noted by copilot review and fixed here

Comment thread src/Config/SDK/Configuration.php Resolved
@brettmc
brettmc merged commit 3c4c58f into open-telemetry:main Oct 21, 2026
19 of 20 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

declarative config: rework .instrumentation

3 participants