docs: blob storage field groups, v2 observations trace_context

[niklassemmler]

Summary

Documentation follow-up for LFE-9456 (column selection for blob storage exports) and LFE-9688 (legacy source cutoff for new Cloud projects), plus the related PR #13620 (trace_context on /v2/observations).

New changelog entries

• 2026-05-15-blob-storage-export-field-groups.mdx — eleven togglable field groups, core always exported, pricing gated on usage.
• 2026-05-15-v2-observations-trace-context.mdx — trace_context (tags, release, traceName) available on /api/public/v2/observations; usagePricingTierName moved from trace_context to usage.
• 2026-05-20-blob-storage-enriched-default.mdx — Cloud projects created on or after the cutoff can no longer pick legacy traces/observations sources; existing projects and self-hosted unaffected. Dated for the cutoff itself; depends on langfuse PR #13627 actually shipping by then.

Docs updates

• export-to-blob-storage.mdx — new "Choose which columns are exported" section with the full group → columns table, pricing/usage callout, and REST API contract notes (exportSource / exportFieldGroups validation rules). Added an inline callout for the post-2026-05-20 Cloud restriction.
• blob-storage-export-fields.mdx — pointer to the new field-groups section from the Enriched observations table.
• observations-api.mdx — added trace_context row and usagePricingTierName to the v2 field-group table.

Author

• Added niklassemmler to data/authors.json and the avatar in public/images/people/.

Test plan

• Spot-checked all six affected pages on pnpm dev (HTTP 200, expected strings present in rendered HTML).
• Avatar renders in the changelog hover card.
• pnpm run link-check — started locally but cancelled before completion; please verify in CI.
• Confirm with feature owner that the 2026-05-20 cutoff date is still on track for the legacy-gate changelog.

🤖 Generated with Claude Code

Greptile Summary

This PR adds documentation for three related features: blob storage export field groups (eleven groups, core always required), trace_context field group on the /v2/observations endpoint, and an upcoming 2026-05-20 restriction that prevents new Cloud projects from selecting legacy export sources. It also registers the niklassemmler author profile.

• Field groups: A new table in export-to-blob-storage.mdx documents all eleven groups with their column lists, REST API contract (exportSource / exportFieldGroups), and pricing gating on the usage group; a callout in blob-storage-export-fields.mdx cross-links this section.
• v2 observations: observations-api.mdx adds trace_context (tags, release, traceName) and moves usagePricingTierName from trace_context to the usage group in the field groups table.
• Legacy gate: A future-dated (2026-05-20) changelog entry notes that new Cloud projects will no longer be able to select legacy sources; the PR description flags this as conditional on langfuse PR #13627 shipping on schedule.

Confidence Score: 4/5

Docs-only change; no executable code is modified. The content is accurate and internally consistent across all six changed pages.

All three changelog entries and both doc updates correctly describe the new field groups and the trace_context addition. The only gap is that the sample response in observations-api.mdx is still labeled "With all fields included" while omitting the new trace_context fields and usagePricingTierName — a minor labeling issue that won't mislead most readers but is worth fixing before the page is widely referenced.

content/docs/api-and-data-platform/features/observations-api.mdx — the sample response heading; content/changelog/2026-05-20-blob-storage-enriched-default.mdx — conditional on an external PR shipping by the stated date.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Blob Storage Integration] --> B{Export Source}
    B -->|LEGACY_TRACES_OBSERVATIONS| C[Legacy: traces/ + observations/ + scores/]
    B -->|OBSERVATIONS_V2| D[Enriched: observations_v2/ + scores/]
    B -->|LEGACY_TRACES_AND_ENRICHED_OBSERVATIONS| E[Both: all paths]

    D --> F{exportFieldGroups}
    E --> F

    F --> G[core - required always]
    F --> H[basic / time / io / metadata / model / prompt / metrics / tools / usage / trace_context - toggleable]

    C --> I[Fixed column set - ignores exportFieldGroups]

    subgraph trace_context group
        H --> J[tags / release / trace_name]
    end

    subgraph usage group
        H --> K[usage_details / cost_details / total_cost / input_price / output_price / total_price / usage_pricing_tier_name]
    end

Loading

Prompt To Fix All With AI

Fix the following 1 code review issue. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 1
content/docs/api-and-data-platform/features/observations-api.mdx:152-154
The heading "With all fields included" is now inaccurate after this PR: neither the new `trace_context` fields (`tags`, `release`, `traceName`) nor `usagePricingTierName` (just moved into `usage`) appear in the sample object. A reader cross-referencing the field groups table will notice the mismatch and may wonder whether the fields are actually returned. Updating the label to reflect a subset avoids that confusion.

```suggestion
### Sample Response

With `core`, `basic`, `time`, `io`, `model`, `usage`, `prompt`, and `metrics` fields included (`trace_context` fields omitted for brevity)
```

_{Reviews (1): Last reviewed commit: "docs: blob storage field groups, v2 obse..." | Re-trigger Greptile}

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
langfuse-docs	Ready	Preview, Comment	May 15, 2026 3:55pm

[github-actions]

@claude review

[claude]

LGTM — docs-only PR (new changelog entries, blob storage field-groups section, observations v2 trace_context table row, author addition); two minor wording nits flagged inline.

Extended reasoning...

Overview

This PR is documentation-only across 8 files: three new changelog entries (2026-05-15 blob storage field groups, 2026-05-15 v2 observations trace_context, 2026-05-20 enriched-default cutoff), two updated docs pages (export-to-blob-storage.mdx gets a new "Choose which columns are exported" section with the full group→columns table, and blob-storage-export-fields.mdx gets a callout pointing to it), one row added to the v2 field-group table in observations-api.mdx, plus a new author entry in data/authors.json and avatar image.

Security risks

None. No code, no auth, no permissions, no user-input handling. The only "sensitive" artifact is the author avatar JPEG, which is a static asset.

Level of scrutiny

Low. This is all release-notes and reference docs for already-shipped or about-to-ship product changes; the docs site rebuilds via Vercel preview. The most consequential statement is the 2026-05-20 cutoff date, which the author has already flagged in the PR description as depending on langfuse PR #13627 shipping by then — that coordination question is already visible to the author and reviewers, so I don't need to surface it again.

Other factors

Two inline nits were flagged: (a) a wording inconsistency in the blob-storage-export-fields callout ("eleven togglable" vs. the next sentence which clarifies core is required and only ten are toggleable — the companion changelog already uses the precise "ten of which are toggleable" phrasing), and (b) the v2-observations-trace-context changelog tells readers to update queries that requested usagePricingTierName under the old trace_context group, but the same changelog introduces trace_context as new on /v2/observations, so no public reader could have been doing that. Both are pure copy polish, not correctness issues, and the inline comments give the author exactly enough to act on if they want to.

[claude]

🟡 The Available Field Groups table now lists usagePricingTierName under usage and a new trace_context row (tags, release, traceName), but the Sample Response further down this file (around line 152) labeled "With all fields included" still omits all four of those fields. A reader cross-referencing the table to the sample will see the mismatch. Either add the missing fields to the sample object or qualify the heading (e.g. "trace_context fields omitted for brevity").

Extended reasoning...

What the bug is

This PR modifies the "Available Field Groups" table at content/docs/api-and-data-platform/features/observations-api.mdx lines 51-54 to (a) append usagePricingTierName to the existing usage row, and (b) introduce a new trace_context row containing tags, release, and traceName. However, the Sample Response block further down the same file is left unchanged. Its heading still reads "With all fields included", but the JSON object that follows contains none of these four newly-listed fields.

How it manifests

A reader who lands on the page and uses it as authoritative documentation will likely (1) skim the field-groups table to see what is available, then (2) scroll to the sample response to see the wire shape. After this PR, those two cross-references no longer agree: the table promises four fields that the "all fields" sample omits. The reader may reasonably wonder whether usagePricingTierName, tags, release, and traceName are actually returned by the endpoint, or whether the table is aspirational.

Step-by-step proof

1. Read observations-api.mdx line 51: the usage row now includes usagePricingTierName (added by this PR's diff: | \usage` | usageDetails, costDetails, totalCost, usagePricingTierName |`).
2. Read line 54: a new row | \trace_context` | tags, release, traceName |` is added by this PR.
3. Read lines 152-154: heading is "### Sample Response" / "With all fields included".
4. Read the JSON body at lines 156-216: searching for usagePricingTierName, tags, release, or traceName yields no matches. The object contains totalCost, inputPrice, outputPrice, totalPrice, etc., but not the four new field names.
5. The label "With all fields included" is therefore inaccurate after the PR — the four new fields are documented as available but are missing from the "all fields" sample.

Why existing content doesn't prevent it

The sample response was authored before this PR's table edits. Nothing in the PR's diff touches the sample block, so the heading silently becomes wrong the moment the table gains new entries. Greptile's own PR-description review (Confidence Score 4/5 section) independently flagged this same labeling inconsistency.

Impact

Pure docs accuracy — no functional impact and no incorrect API contract. But the page is referenced from the new 2026-05-15-v2-observations-trace-context.mdx changelog entry ("The full table is in the Observations API v2 docs"), so the inconsistency is on the landing page that new trace_context users will hit.

How to fix

Either:

• Add the four missing fields (usagePricingTierName, tags, release, traceName) to the sample JSON, or
• Qualify the heading, e.g. "With most field groups included; `trace_context` omitted for brevity" (matching the suggestion already in the PR-description review).

The label-qualifying option is smaller and lower-risk.

_{🔬 also observed by greptile}

[claude]

LGTM — docs-only PR with new changelog entries and field-group documentation; the remaining bug is a wording nit posted inline.

Extended reasoning...

Overview

This PR is documentation-only, touching three new changelog entries (blob storage field groups, v2 observations trace_context, enriched-observations default for new Cloud projects), updates to two existing docs pages (export-to-blob-storage.mdx and blob-storage-export-fields.mdx), a new field-group row in observations-api.mdx, and an author profile addition (niklassemmler) with the corresponding avatar image. No executable code is modified.

Security risks

None. All changes are MDX/JSON content and a static image. There is no auth, crypto, permission, or input-handling code in scope.

Level of scrutiny

Low. Docs PRs of this size are well within the threshold for automated approval. The content has been iterated on across multiple review rounds — earlier inline comments about a contradictory toggleable-count claim, a self-contradictory migration sentence on the v2 changelog, a duplicated 'field groups field groups' phrase, and a stale 'all fields included' sample heading were all flagged in prior runs and are marked resolved or have been addressed in the latest commits.

Other factors

The single outstanding bug from this run is a pure wording nit about whether the changelogs use the verbatim UI label 'Traces and observations (legacy)' vs. the shortened 'Traces and observations'. It has no functional impact and is posted inline for the author. The author also flagged two manual follow-ups in the PR description (link-check, confirming the 2026-05-20 cutoff date with the feature owner) — both are non-blocking owner tasks, not approval gates.

[claude]

🟡 The new changelog at line 12 refers to the deprecated sources as "Traces and observations" and "Traces and observations + Enriched observations", but the canonical UI/REST labels used everywhere else in the docs are "Traces and observations (legacy)" and "Traces and observations (legacy) and enriched observations". The 2026-05-15-blob-storage-export-field-groups.mdx line 24 has the same drift ("the legacy Traces and observations source"). Using the verbatim UI labels here would let readers cross-reference the changelog against Project Settings → Integrations → Blob Storage without having to mentally translate.

Extended reasoning...

What the bug is

The new 2026-05-20-blob-storage-enriched-default.mdx changelog at line 12 uses the bolded identifiers "Traces and observations" and "Traces and observations + Enriched observations" for the two sources being deprecated for new Cloud projects. Neither name matches the canonical product label used everywhere else in the docs:

• The first drops the (legacy) parenthetical suffix.
• The second rewrites the canonical phrase entirely — substitutes + for "and", capitalizes "Enriched", and drops (legacy).

The same drift appears in the sibling changelog 2026-05-15-blob-storage-export-field-groups.mdx at line 24: "the legacy Traces and observations source" (the word "legacy" appears as prose preceding the bold, rather than baked into the bolded label).

Why this is worth flagging

Every other docs page consistently uses the verbatim UI labels: content/docs/api-and-data-platform/features/export-to-blob-storage.mdx line 56 lists the three options exactly as Traces and observations (legacy), Traces and observations (legacy) and enriched observations, and Enriched observations (recommended). blob-storage-export-fields.mdx does the same in its export-sources table. The new 2026-05-20 callout in the same PR (line 56-58 of export-to-blob-storage.mdx) also uses the verbatim labels. Only the two new changelog entries diverge.

Step-by-step proof

1. Open content/changelog/2026-05-20-blob-storage-enriched-default.mdx line 12. The bolded source names are "Traces and observations" and "Traces and observations + Enriched observations".
2. Open content/docs/api-and-data-platform/features/export-to-blob-storage.mdx line 56. The three canonical option labels are Traces and observations (legacy), Traces and observations (legacy) and enriched observations, and Enriched observations (recommended).
3. Open content/docs/api-and-data-platform/features/blob-storage-export-fields.mdx lines 19-21. The same three labels appear in the export-sources table verbatim.
4. The changelog labels don't match any of the three on either substring or punctuation: "Traces and observations" is a prefix-match only, and "Traces and observations + Enriched observations" doesn't appear in any other docs page at all.

Impact

Pure wording polish, no functional impact — this is a nit. Mitigating factors keep it minor: (a) both changelogs include the word "legacy" as a prose qualifier preceding the bolded name, so the meaning carries through; (b) a reader who pops open the UI to find these options will see only one entry beginning "Traces and observations (legacy)" and one combined entry, so confusion is bounded.

Addressing the refutation

One verifier argued this is too subjective to report and that the prose context ("legacy" preceding the bolded name) disambiguates. That's fair for line 12 in isolation, but the second label ("Traces and observations + Enriched observations") rewrites the canonical phrase enough that someone searching for it verbatim in the docs or the UI won't get an exact match. And a doc-only PR — where the only artifact is wording — is exactly where this kind of consistency polish is most appropriate to flag, even if non-blocking.

How to fix

Use the verbatim UI labels in the bolded positions:

• Line 12 of 2026-05-20-blob-storage-enriched-default.mdx: change to "The Traces and observations (legacy) and Traces and observations (legacy) and enriched observations sources are no longer selectable…"
• Line 24 of 2026-05-15-blob-storage-export-field-groups.mdx: change to "The Traces and observations (legacy) source still uses its fixed column set."