docs(rfc-0018): OTLP log-spec compliance amendments

[jensholdgaard]

RFC 0018 — OTLP log-spec compliance amendments

One compliance push closing the six OTLP-fidelity gaps from the 2026-06-20 audit (three areas: receiver, schema, DSL/querier), each graded against the spec's own MUST/SHOULD via the OpenTelemetry knowledge base.

#	Gap	Spec level	Amends
1	scope.attributes + resource/scope schema_url dropped at ingest	MUST (AnyValue must be stored; scope = name/version/schema_url/attributes)	RFC 0003 + 0005
2	transient WAL/storage failure → non-retryable INTERNAL/500 (clients drop data)	retry table (SHOULD, real data-loss)	RFC 0003
3	event_name stored + returnable but not a DSL filter	top-level field	RFC 0002
4	non-finite doubles (NaN/±Inf) → null, don't round-trip	lossy	RFC 0005
5	SeverityNumber not range-validated (u8 0..255 vs 1..24/0)	normalized values	RFC 0003
6	body column doc says "raw bytes" but holds UTF-8 JSON for Structured	doc only	RFC 0005

Refuted by the spec check (not in scope): the audit's "structured AnyValue body is type-erased" — the stored canonical JSON is the OTLP protobuf→JSON mapping and preserves the discriminator.

Invariants / hazards touched

• §3.5 schema migration — the three new columns are OPTIONAL; readers tolerate their absence in historical files (RFC0018.2). Additive, no breaking schema change.
• §3.7 multi-tenancy — new columns are per-tenant like all data.
• H6 — the new event_name DSL field leaks no DataFusion/SQL surface (RFC0018.4).
• §3.3/§3.4 durability — the retry-mapping fix (docs: apply RFC maturity-model amendments #2) protects WAL-before-ack: a transient failure must not be reported as non-retryable.

status: specified — §5 scenarios RFC0018.1–.6. Held for maintainer sign-off: amends accepted RFC 0003/0005 and green RFC 0002. Per the standing directive, spec fidelity outranks downstream API stability (pre-release), so the implementation will take the resulting type/schema changes.

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation
  • Added RFC 0018 documenting OTLP log-spec compliance amendments addressing multiple fidelity gaps, including improvements to instrumentation scope handling, error code mapping for transient failures, filtering capabilities, JSON numeric value handling, severity number preservation, and body column documentation clarification.

[coderabbitai]

Warning

Review limit reached

@jensholdgaard, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 25 minutes and 12 seconds. Learn how PR review limits work.

Your organization has used up its prepaid credits, and credit purchases are no longer available. Enable the review add-on in the billing tab to keep reviews running — you're only billed for reviews past your plan's rate limits ($0.25/file).

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based credits.

🚦 How do rate limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan refill rate.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, the refill rate gradually slows as usage increases. The highest same-day bursts are limited more strictly.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 4319a85a-1f48-41cc-80b9-868fdf92fc89

📥 Commits

Reviewing files that changed from the base of the PR and between 7cb2b06 and 9b37160.

📒 Files selected for processing (2)

• docs/SUMMARY.md
• docs/rfcs/0018-otlp-log-spec-compliance.md

📝 Walkthrough

Walkthrough

Adds docs/rfcs/0018-otlp-log-spec-compliance.md, a 384-line RFC specifying six OTLP compliance fixes across receiver error mapping, schema (scope attributes and schema_url persistence), DSL filtering, AnyValue non-finite double encoding, and severity out-of-range handling. Registers the new RFC in docs/SUMMARY.md.

Changes

RFC 0018 — OTLP Log-Spec Compliance Amendments

Layer / File(s)	Summary
RFC metadata, motivation, and governing principle docs/SUMMARY.md, docs/rfcs/0018-otlp-log-spec-compliance.md	Adds RFC header/metadata, registers the document in the table of contents, establishes motivation from a 2026-06-20 compliance audit, and defines the "faithful witness, not corrector" principle governing all six amendments.
Scope attributes, schema_url persistence, and DSL filter extensions docs/rfcs/0018-otlp-log-spec-compliance.md	Specifies OPTIONAL additive Parquet columns for InstrumentationScope.attributes, ResourceLogs.schema_url, and ScopeLogs.schema_url with explicit NULL-vs-empty semantics; extends DSL to add event_name, scope_version bare fields, and scope_attributes filtering.
Receiver retryable vs permanent error-code amendments docs/rfcs/0018-otlp-log-spec-compliance.md	Amends receiver error mapping to route transient ingest/storage failures to UNAVAILABLE/RESOURCE_EXHAUSTED with RetryInfo (gRPC) and 503/429 with Retry-After (HTTP), while keeping malformed/tenant errors as INVALID_ARGUMENT/400.
AnyValue non-finite double encoding and severity out-of-range handling docs/rfcs/0018-otlp-log-spec-compliance.md	Updates canonical AnyValue JSON encoding for non-finite doubles to use OTLP/proto3 string forms ("NaN", "Infinity", "-Infinity"); changes severity contract to preserve out-of-range SeverityNumber values verbatim within u8 bounds, increment ingest.severity_out_of_range, and retain severity_text; clarifies body column semantics.
Alternatives, acceptance criteria, testing strategy, open questions, and references docs/rfcs/0018-otlp-log-spec-compliance.md	Documents dismissed alternatives, six scenario-based acceptance criteria, per-scenario testing strategy (integration, unit, property-based tests), open questions, resolved decisions (severity clamp vs preserve, scope attribute keying), and updated spec/RFC references.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~15 minutes

Possibly related PRs

• jensholdgaard/ourios#166: Both PRs modify RFC/spec documentation around the body column's canonical JSON encoding semantics; RFC 0018 further amends the UTF-8 vs raw retained bytes distinction introduced in earlier body-column work.

Poem

🐇 Six gaps to close, the spec said "MUST,"
The witness faithful, correct we distrust.
Scope attributes saved, schema URLs too,
Non-finite doubles round-trip brand new.
Severity preserved, retries made right —
RFC 0018 hops into the light! ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately and concisely summarizes the main change: documentation of RFC 0018 addressing OTLP log-spec compliance amendments as identified in the audit.
Description check	✅ Passed	The description provides comprehensive context for the RFC including gap analysis, specification compliance levels, affected RFCs, invariants, and status—exceeding template minimums despite missing standard checklist items.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/rfc-0018-otlp-compliance

---

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.}

[Copilot]

Pull request overview

Adds a new RFC documenting amendments needed to close OTLP log-spec compliance gaps, and exposes it in the mdBook table of contents so it becomes part of the published RFC set.

Changes:

• Adds RFC 0018 describing six OTLP-fidelity amendments spanning receiver, schema, and DSL/querier.
• Updates the mdBook SUMMARY to include RFC 0018 in the RFC list.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 4 comments.

File	Description
docs/SUMMARY.md	Adds RFC 0018 to the mdBook RFC index.
docs/rfcs/0018-otlp-log-spec-compliance.md	Introduces the new “specified” RFC detailing the OTLP compliance amendments, scenarios, and references.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.