Updated opentelemetry input plugin docs to reflect several enhancements for 4.2. Fixes #2209.

[eschabell]

Updated opentelemetry input plugin docs to reflect several enhancements for 4.2. Fixes #2209.

Summary by CodeRabbit

• Documentation
  • Updated OpenTelemetry trace handling documentation to reflect stable support status across all transport protocols.
  • Added detailed documentation on trace validation rules, error handling, and configuration options.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Warning

Rate limit exceeded

@eschabell has exceeded the limit for the number of commits or files that can be reviewed per hour. Please wait 5 minutes and 19 seconds before requesting another review.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

📥 Commits

Reviewing files that changed from the base of the PR and between 917747f and bb80f4f.

📒 Files selected for processing (1)

• pipeline/inputs/opentelemetry.md (4 hunks)

Walkthrough

Documentation update for OpenTelemetry input handling that expands the raw_traces parameter description, marks Traces support as Stable in the compatibility table, and introduces a comprehensive new section detailing the unified trace JSON parser, error status propagation, strict ID validation rules, and example payloads.

Changes

Cohort / File(s)	Summary
OpenTelemetry Documentation pipeline/inputs/opentelemetry.md	Expanded raw_traces parameter documentation to describe processing vs. forwarding behavior; updated Traces row in HTTP/JSON/Protobuf compatibility table from Unimplemented to Stable; added new "OpenTelemetry trace improvements" section covering unified trace JSON parser, error status propagation with specific error codes, strict ID decoding validation rules, and example JSON trace payload.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

• Verify compatibility table updates are accurate across all protocol variants (HTTP1/JSON, HTTP1/Protobuf, HTTP2/gRPC)
• Validate JSON parser description and error codes align with actual implementation
• Confirm ID validation rules and examples are correctly represented
• Check that the raw_traces behavior documentation accurately reflects feature functionality

Suggested labels

waiting-on-review

Suggested reviewers

• esmerel
• alexakreizinger

Poem

🐰 A tale of traces, now so clear,
JSON parsers drawing near,
Stable marks adorn the table,
Validation rules we're now able,
OpenTelemetry takes the stage,
Documentation writes the page! ✨

Pre-merge checks and finishing touches

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main change: updating OpenTelemetry input plugin documentation for version 4.2 enhancements.
Linked Issues check	✅ Passed	The PR documentation fully addresses all three objectives: unified trace JSON parser, error status propagation, and strict ID decoding for OpenTelemetry enhancements.
Out of Scope Changes check	✅ Passed	All changes are documentation updates directly related to OpenTelemetry enhancements for version 4.2, with no out-of-scope modifications detected.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (2)

pipeline/inputs/opentelemetry.md (2)

155-168: Clarify error handling behavior when validation fails.

The error codes are well-documented, but the documentation doesn't explain what happens when an error occurs—are traces dropped, retried, or logged and forwarded? Additionally, consider documenting what HTTP status code is returned to the client when validation fails (e.g., 400, 422, 500).

Consider adding a sentence like: "When validation fails, the trace is rejected and an HTTP 4xx error response is returned to the client."

---

218-219: Document valid span status codes.

The example shows "code": "OK" for span status, but the valid values per the OpenTelemetry specification are OK, ERROR, and UNSET. Documenting these explicitly would help users understand what status codes are acceptable and what triggers FLB_OTEL_TRACES_ERR_STATUS_FAILURE.

Add a clarification note after line 168 or within the "Strict ID decoding" section explaining valid status codes and that invalid codes will trigger an error.

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 48cbc51 and 917747f.

📒 Files selected for processing (1)

• pipeline/inputs/opentelemetry.md (4 hunks)

🔇 Additional comments (5)

pipeline/inputs/opentelemetry.md (5)

35-35: Clear documentation of raw_traces behavior.

The expanded description and supporting paragraph (lines 35 and 60) effectively explain both processing paths. The distinction between unified JSON parsing with validation (when false) versus raw log forwarding (when true) is well-articulated and helps users understand the impact of this setting.

Also applies to: 60-60

---

172-184: ID validation rules are clear and consistent.

The strict ID decoding section properly documents the validation rules (32 hex characters for trace IDs, 16 for span IDs) and walks through the validation process step-by-step. The example JSON payload (lines 212–213) correctly demonstrates IDs meeting these requirements (0123456789abcdef0123456789abcdef and 0123456789abcdef).

---

143-153: Unified trace JSON parser documentation is comprehensive.

The section clearly describes the parser's scope (resource spans, instrumentation scope, span data, events/links, ID validation) and explicitly calls out that the parser handles OpenTelemetry's type-specific JSON encoding (e.g., stringValue, intValue). This is helpful context for users sending JSON-encoded traces.

---

186-237: Example payload is valid and demonstrates the documented structure.

The JSON example includes all key elements mentioned in the documentation: resource attributes, instrumentation scope, span IDs with correct lengths, timestamps in Unix nano format, status, and attribute value containers. This is a helpful reference for users constructing trace payloads.

---

95-95: The Traces Stable claim is verified and accurate for Fluent Bit 4.2.0 OpenTelemetry input.

Fluent Bit v4.2.0 (released November 11, 2025) officially marks OpenTelemetry traces as Stable in the 4.x line documentation. The release includes significant improvements:

• Unified Trace JSON Parser for consistent OpenTelemetry trace handling
• Improved error status propagation for traces
• Strict ID decoding and enhanced validation for trace IDs

OTLP traces over protobuf (HTTP and gRPC transports) are production-ready and intended for stable use. However, note that OTLP over HTTP/JSON remains unimplemented, and some trace-related options (e.g., profiles_support) are still experimental. The documentation should clarify that the Stable designation applies to the protobuf-based OTLP transport methods, not all possible trace ingestion paths.

The feature is safe to document as Stable for the intended OTLP protobuf transports in the 4.2.0 release.

[eschabell]

AI review passed, merging.