Support output_stream in declarative config of otlp_file/development by robintra · Pull Request #8676 · open-telemetry/opentelemetry-java

robintra · 2026-07-31T16:32:42Z

The OTLP file exporter builders already accept an arbitrary OutputStream and the generated config model already carries output_stream, but the declarative configuration component providers never read it so only stdout was reachable without writing code. The support table in opentelemetry-configuration reports Java as not_implemented for this option, while C++ and PHP report supported.

This wires the option through for spans, metrics and logs:

stdout sets System.out explicitly, rather than relying on the default installed by the static builder() factory. Matching is case-insensitive, like the sibling options parsed in the same create() call.
A file URI is resolved through java.net.URI, so both file:///path and the authority-less file:/path are accepted, with any scheme casing. Missing parent directories are created, the file is opened with CREATE + APPEND and the stream is wrapped in a BufferedOutputStream. StreamJsonWriter flushes after every record so buffering does not delay output.
Anything else fails with a ConfigurationException, distinguishing an unusable value from a file that could not be opened.

Two choices worth confirming:

Append rather than truncate follows the "Streaming appending" section of the file exporter spec, which does not state it outright.
Creating missing parent directories avoids taking the whole application down at startup when the directory is created by another process, but it is a behaviour the spec does not mention.

Tests are added to AbstractOtlpStdoutExporterTest so they run for all three signals: stdout, a plain file:// URI producing the expected JSON, the authority-less and upper case URI form, parent directory creation, an unrecognized value, and a path that cannot be opened.

DeclarativeConfigurationCreateTest.parseAndCreate_Examples needed one adjustment. The ExperimentalOtlpFile*_file.yaml snippets write to file:///var/log/*.jsonl, which is not writable in tests. The test already rewrites ca_file, key_file and cert_file to temp files for the same reason so output_stream is rewritten the same way.

Two limitations are left as-is, since addressing either would go beyond wiring up the option. I am happy to follow up if maintainers want them handled here:

Pointing several signals at the same path opens one stream per signal and StreamJsonWriter does not synchronize so concurrent writes can interleave.
The handle is held for the exporter's lifetime so external log rotation is not picked up.

Verification

./gradlew :exporters:logging-otlp:check and ./gradlew :sdk-extensions:declarative-config:check pass. jApiCmp reports no API change since the new class lives in an internal package so docs/apidiffs is unchanged.

Also verified end to end with a throwaway test that runs DeclarativeConfiguration.parseAndCreate on:

file_format: "1.0"
tracer_provider:
  processors:
    - simple:
        exporter:
          otlp_file/development:
            output_stream: file:///tmp/traces.jsonl

and confirms the span is written as one JSON line to the file with nothing on stdout.

linux-foundation-easycla · 2026-07-31T16:32:50Z

The committers listed above are authorized under a signed CLA.

✅ login: robintra / name: robintra (b3ab6ed)

codecov · 2026-07-31T16:59:07Z

Codecov Report

❌ Patch coverage is 96.42857% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 91.66%. Comparing base (d948e13) to head (6d92d47).

Files with missing lines	Patch %	Lines
.../logging/otlp/internal/OutputStreamConfigUtil.java	96.00%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@             Coverage Diff              @@
##               main    #8676      +/-   ##
============================================
+ Coverage     91.65%   91.66%   +0.01%     
- Complexity    10352    10358       +6     
============================================
  Files          1003     1004       +1     
  Lines         27210    27238      +28     
  Branches       3199     3203       +4     
============================================
+ Hits          24939    24968      +29     
+ Misses         1566     1564       -2     
- Partials        705      706       +1

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

opentelemetry-pr-dashboard · 2026-07-31T17:52:53Z

Pull request dashboard status

Waiting on the author · refreshed 2026-08-24 21:11 UTC

Resolve merge conflicts.

Respond to 5 review items (e.g. link a commit, explain why not, ask a follow-up):

Inline threads: 1, 2, 3, 4, 5

Status above doesn't look right?

Just replied or pushed? Anything around or after the refresh time above may not be picked up yet — give it a few minutes.
Should this be with reviewers? Comment /dashboard route:reviewers to route it to them.
Anything wrong — including the routing? Report it with what you expected; it helps us improve the dashboard.

jack-berg · 2026-08-20T22:02:53Z

+* Logging: Support the `output_stream` option when declaratively configuring `otlp_file/development`
+  ([#8676](https://github.com/open-telemetry/opentelemetry-java/pull/8676))


Don't both adding a changelog entry. They're added as part of the release process. This is in the wrong section anyway.

jack-berg · 2026-08-20T22:02:53Z

+    if (outputStream == null) {
+      return;
+    }
+    if (STDOUT.equalsIgnoreCase(outputStream)) {


No need for ignoring case. Better to be more explicit and case sensitive. Can always expand if needed.

jack-berg · 2026-08-20T22:02:54Z

+    } catch (URISyntaxException e) {
+      throw new ConfigurationException("Unrecognized output_stream: " + outputStream, e);
+    }
+    if (!FILE_SCHEME.equalsIgnoreCase(uri.getScheme())) {


Same here: match the scheme case-sensitively against "file". The spec's example is lowercase and a well-formed URI's scheme is already lowercase, so equalsIgnoreCase only accepts ill-formed input. Can loosen later if needed.

jack-berg · 2026-08-20T22:02:54Z

+  static Stream<Arguments> outputStreamFileTestCases() {
+    return Stream.of(
+        Arguments.argumentSet("file uri", "test.jsonl", (UnaryOperator<String>) uri -> uri),
+        Arguments.argumentSet(
+            "authority-less file uri with upper case scheme",
+            "test.jsonl",
+            (UnaryOperator<String>) uri -> uri.replaceFirst("^file://", "FILE:")),
+        Arguments.argumentSet(
+            "missing parent directory", "missing/test.jsonl", (UnaryOperator<String>) uri -> uri));
+  }


Once matching is strict (see the OutputStreamConfigUtil threads), the only case here that actually mutates the URI ("authority-less file uri with upper case scheme") goes away. The remaining two both pass identity, so the UnaryOperator<String> parameter collapses to just String relativePath and the test body can use file.toUri().toString() directly. Worth simplifying at the same time.

jack-berg · 2026-08-20T22:02:54Z

+      throw new ConfigurationException("Unrecognized output_stream: " + outputStream, e);
+    }
+    if (!FILE_SCHEME.equalsIgnoreCase(uri.getScheme())) {
+      throw new ConfigurationException("Unrecognized output_stream: " + outputStream);


The "Unrecognized output_stream: <value>" message doesn't hint at what is expected. Consider "Unrecognized output_stream: <value>. Expected \"stdout\" or a file:// URI." so users get a pointer without having to consult the spec. Applies to all three ConfigurationException throw sites in filePath and the scheme-check.

robintra requested a review from a team as a code owner July 31, 2026 16:32

robintra force-pushed the declarative-config-output-stream branch from b3ab6ed to 3d94c71 Compare July 31, 2026 16:38

opentelemetry-pr-dashboard Bot mentioned this pull request Jul 31, 2026

Pull Request Dashboard #8439

Open

robintra mentioned this pull request Jul 31, 2026

File exporter: should an existing file be appended to or truncated? open-telemetry/opentelemetry-specification#5243

Open

robintra added 2 commits August 8, 2026 19:36

Support output_stream in declarative config of otlp_file/development

053fb2c

Cover the malformed file URI branch

6d92d47

robintra force-pushed the declarative-config-output-stream branch from 054525a to 6d92d47 Compare August 8, 2026 17:37

jack-berg reviewed Aug 20, 2026

View reviewed changes

Navigation Menu

Uh oh!

Support output_stream in declarative config of otlp_file/development - #8676

Support output_stream in declarative config of otlp_file/development#8676
robintra wants to merge 2 commits into
open-telemetry:mainfrom
robintra:declarative-config-output-stream

robintra commented Jul 31, 2026

Uh oh!

linux-foundation-easycla Bot commented Jul 31, 2026 •

edited

Loading

Uh oh!

codecov Bot commented Jul 31, 2026 •

edited

Loading

Uh oh!

opentelemetry-pr-dashboard Bot commented Jul 31, 2026 •

edited

Loading

Uh oh!

jack-berg Aug 20, 2026

Uh oh!

jack-berg Aug 20, 2026

Uh oh!

jack-berg Aug 20, 2026

Uh oh!

jack-berg Aug 20, 2026

Uh oh!

jack-berg Aug 20, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		* Logging: Support the `output_stream` option when declaratively configuring `otlp_file/development`
		([#8676](https://github.com/open-telemetry/opentelemetry-java/pull/8676))

Uh oh!

Conversation

robintra commented Jul 31, 2026

Verification

Uh oh!

linux-foundation-easycla Bot commented Jul 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codecov Bot commented Jul 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

opentelemetry-pr-dashboard Bot commented Jul 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pull request dashboard status

Uh oh!

jack-berg Aug 20, 2026

Choose a reason for hiding this comment

Uh oh!

jack-berg Aug 20, 2026

Choose a reason for hiding this comment

Uh oh!

jack-berg Aug 20, 2026

Choose a reason for hiding this comment

Uh oh!

jack-berg Aug 20, 2026

Choose a reason for hiding this comment

Uh oh!

jack-berg Aug 20, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

linux-foundation-easycla Bot commented Jul 31, 2026 •

edited

Loading

codecov Bot commented Jul 31, 2026 •

edited

Loading

opentelemetry-pr-dashboard Bot commented Jul 31, 2026 •

edited

Loading