Hacktoberfest 2026: le issue che i maintainer hanno segnato per ottobre, aperte e adatte ai principianti. Sfoglia le issue Hacktoberfest

Feature: opt-in line-encoding options (marker prefix, base64, gzip, max line bytes) for the OTLP stdout exporter

Aperta
  • Qualcosa non va?
#8,976 2 commenti 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 2 giorni

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
5/5
Tempo stimato
Più di una settimana
Idoneità per principianti
44/100
Tipo di issue
Funzionalità
Chiarezza
Abbastanza chiara
Stato di attività
Attiva
Stack tecnologico
java
Ambito
observability

Direzione di ricerca

Start by locating the OtlpStdout*ExporterBuilder implementations and the experimental-otlp/stdout autoconfigure providers named in the issue. Read how they serialize and emit request batches, then inspect their tests before deciding how to cover marker framing, encoding, byte limits, and splitting. Done means all four options work for traces, metrics, and logs, configuration can set them, and defaults remain unchanged.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

Feature Request
Verify this is not already reported
  • I have verified that this issue is not already reported
Is this a request for a feature or an enhancement

Enhancement

Summary

The OtlpStdout*Exporter exporters already write the OTLP-JSON request envelope as compact JSON Lines — one Export{Trace,Metrics,Logs}ServiceRequest per line — toSystem.out or a supplied OutputStream. This request adds four opt-in, off-by-default options to the existing builders so the same output can be consumed
by line-based log agents: a per-line signal marker prefix, base64 encoding, gzip compression, and a per-line byte cap with batch splitting. The default output is unchanged.

Problem statement

The current compact JSON-Lines output is ideal for reading, but three things are missing when the stdout stream is ingested by a log agent rather than a human:

  • Signal routing. Traces, metrics, and logs interleave on one stream, and there is no per-line token an agent can key on to route a line by signal without parsing its JSON.
  • Single-line / size discipline. No encoding, compaction and byte limit per line for size-limited transports.
  • No splitting. A batch larger than a downstream event-size limit is emitted as one oversized line; there is no option to split it into conformant lines.

Everything above is opt-in — the existing default (plain compact JSON Lines, one request per line) must remain the default.

Proposed solution

Add four builder options to each OtlpStdout*ExporterBuilder (and the experimental-otlp/stdout autoconfigure component provider). All default to off, so existing behaviour is unchanged.

Option Effect Default
setMarkerPrefix(String) prefix each line with {PREFIX}_{SIGNAL} (TRACE / METRIC / LOG) so an agent can route by signal none (plain JSON Lines)
setBase64(boolean) base64-encode the payload (guarantees a single line, no embedded newlines) off
setGzip(boolean) gzip the payload (implies base64) off
setMaxLineBytes(int) cap the line's UTF-8 byte length, splitting oversized batches no cap

Line shape by option — {SIGNAL} is TRACE / METRIC / LOG:

Default (no options) — unchanged, one OTLP-JSON request per line:

<OTLP-JSON ExportTraceServiceRequest>
<OTLP-JSON ExportMetricsServiceRequest>
<OTLP-JSON ExportLogsServiceRequest>

setMarkerPrefix("OTEL_EXPORT").setBase64(true):

OTEL_EXPORT_TRACE  <base64( OTLP-JSON ExportTraceServiceRequest  )>
OTEL_EXPORT_METRIC <base64( OTLP-JSON ExportMetricsServiceRequest )>
OTEL_EXPORT_LOG    <base64( OTLP-JSON ExportLogsServiceRequest    )>

setMarkerPrefix("OTEL_EXPORT").setGzip(true):

OTEL_EXPORT_TRACE  <base64( gzip( OTLP-JSON ExportTraceServiceRequest  ) )>
OTEL_EXPORT_METRIC <base64( gzip( OTLP-JSON ExportMetricsServiceRequest ) )>
OTEL_EXPORT_LOG    <base64( gzip( OTLP-JSON ExportLogsServiceRequest    ) )>

Semantics:

  • The cap is enforced on UTF-8 byte length, not character count.
  • Spans and log records split at record granularity; metrics descend to individual data points for a single instrument that overflows on its own. A single record/data point that still exceeds the cap is dropped with a warning rather than emitted truncated.
  • A marker prefix containing whitespace or control characters is rejected with a warning (no prefix applied) so it cannot corrupt the line framing.

Beyond the builder, I also propose autoconfigure equivalents so the options can be driven entirely by configuration (no application code) — as Java system properties and their standard OTEL_* environment-variable forms. The exporter is already selectable by name as experimental-otlp/stdout; this adds four config keys for the new options. It requires extending the experimental-otlp/stdout exporter/component providers to read them — the current prototype wires the builders only:

System property Environment variable Example value
otel.exporter.otlp.stdout.marker.prefix OTEL_EXPORTER_OTLP_STDOUT_MARKER_PREFIX OTEL_EXPORT
otel.exporter.otlp.stdout.encoding OTEL_EXPORTER_OTLP_STDOUT_ENCODING base64
otel.exporter.otlp.stdout.compression OTEL_EXPORTER_OTLP_STDOUT_COMPRESSION gzip
otel.exporter.otlp.stdout.max.line.bytes OTEL_EXPORTER_OTLP_STDOUT_MAX_LINE_BYTES 245760
Example usage
In-code (builder) — the same options apply to all three exporters
// default: unchanged, compact JSON Lines to System.out
OtlpStdoutSpanExporter plain = OtlpStdoutSpanExporter.builder().build();

// opt-in: marker + base64 + 240 KiB line cap, splitting oversized batches
OtlpStdoutSpanExporter framed =
    OtlpStdoutSpanExporter.builder()
        .setMarkerPrefix("OTEL_EXPORT")
        .setBase64(true)
        .setMaxLineBytes(240 * 1024)
        .build();
Env-based config (no application code)

Selection by name already works today; the four OTEL_EXPORTER_OTLP_STDOUT_* vars are the proposed additions, so the marker + gzip output above is produced purely from configuration (e.g. with the OpenTelemetry Java agent / SDK autoconfigure):

export JAVA_TOOL_OPTIONS="-javaagent:/path/to/opentelemetry-javaagent.jar"
export OTEL_TRACES_EXPORTER=experimental-otlp/stdout
export OTEL_METRICS_EXPORTER=experimental-otlp/stdout
export OTEL_LOGS_EXPORTER=experimental-otlp/stdout
export OTEL_EXPORTER_OTLP_STDOUT_MARKER_PREFIX=OTEL_EXPORT
export OTEL_EXPORTER_OTLP_STDOUT_ENCODING=base64
export OTEL_EXPORTER_OTLP_STDOUT_COMPRESSION=gzip
export OTEL_EXPORTER_OTLP_STDOUT_MAX_LINE_BYTES=245760
java -jar app.jar
Alternatives considered
  • Post-processing stdout downstream: every consumer re-implements marker routing, base64/gzip, and size splitting, inconsistently.
  • The JUL OtlpJsonLogging* exporters: human-readable, multi-line, JUL-prefixed - not a clean single-line OTLP envelope for machine consumption.

Adding opt-in flags to the exporter that already produces the bytes keeps the default unchanged while covering the line-transport case in one place.

Additional context
  • The marker/base64/gzip framing and the config key names (the OTEL_EXPORTER_OTLP_STDOUT_* environment variables / otel.exporter.otlp.stdout.* properties) are not spec'd today; I'll raise a separate opentelemetry-specification issue to standardize the framing and the configuration names before finalizing them here.
  • I'm willing to implement this scoped strictly to these opt-in options with tests, pending maintainer agreement on the approach.
Lingua principale
Java
Stelle
2.5k
Fork
1k
Merge medio
3g 15h
PR unite (30g)
65

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di open-telemetry/opentelemetry-java

Tutte le issue di open-telemetry/opentelemetry-java

Issue simili

Altre issue su Java

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.