docs(integrations): document all sessionId/userId OTel source attributes

[jorgehermo9]

Problem

The OTel attribute mapping table does not document gen_ai.conversation.id, even though Langfuse has mapped it to sessionId since v3.79.1 (added in langfuse/langfuse#7738, commit c2a0b381d). The same table also omits the langfuse.*.metadata.langfuse_{user,session}_id and ai.telemetry.metadata.{userId,sessionId} fallbacks that ingestion accepts.

extractSessionId in packages/shared/src/server/otel/OtelIngestionProcessor.ts resolves six keys, of which the table lists two:

const userIdKeys = [
  "langfuse.session.id",
  "session.id",
  "gen_ai.conversation.id",
  `${LangfuseOtelSpanAttributes.OBSERVATION_METADATA}.langfuse_session_id`,
  `${LangfuseOtelSpanAttributes.TRACE_METADATA}.langfuse_session_id`,
  `ai.telemetry.metadata.sessionId`,
];

extractUserId has the same shape for userId.

This is the one row where a GenAI semantic-convention attribute applies, and the section states that "Langfuse aims to be compliant with the OpenTelemetry GenAI semantic conventions" while the observation-level table lists gen_ai.* fallbacks generously. Frameworks that emit gen_ai.conversation.id and nothing else (Koog, Microsoft Agent Framework — both present in the repo's own trace fixtures) already get sessions for free, but users reading the docs will not know that and will add a redundant session.id.

Because content/** feeds the HTML page, the .md variant (scripts/copy_md_sources.js → public/md-src/**), llms.txt (scripts/generate_llms_txt.js), and the docs MCP corpus, the omission is currently reproduced on every surface an agent might read.

Changes

• Add the missing source attributes to the userId and sessionId rows of the trace-level mapping table, listed in the order ingestion resolves them.
• Note above the table that multiple source attributes resolve first-match-wins. The page already says the langfuse.* namespace takes precedence over generic OTel conventions, but not how two generic conventions rank against each other — relevant because session.id silently wins over gen_ai.conversation.id when both are present (asserted in otelMapping.servertest.ts).
• Mention gen_ai.conversation.id in the attribute-propagation list, which had the same two-key gap.

No behaviour change; this documents what already ships.

Notes

• Prettier re-padded the whole "Mapped from OTel Attribute" column because the new cells are wider. Output of prettier@3.8.3 with the repo's .prettierrc.json, so pnpm run format:check passes.
• Labels for the non-obvious keys ("Vercel AI SDK") follow the comments in OtelIngestionProcessor.ts.

Question for maintainers

Out of scope here, but worth a decision: should gen_ai.conversation.id rank above session.id now that the GenAI convention is stable, and should the Python/JS SDKs emit it alongside session.id? Currently neither SDK emits it (TRACE_SESSION_ID = "session.id" in both), so spans exported to a non-Langfuse backend carry no GenAI conversation attribute. Happy to open a discussion instead if you prefer.

🤖 Generated with Claude Code

Greptile Summary

Updates the OpenTelemetry integration documentation to:

• Document all supported userId and sessionId source attributes.
• Clarify first-match-wins precedence when multiple source attributes are present.
• Include gen_ai.conversation.id in the trace attribute-propagation guidance.

Confidence Score: 5/5

The documentation-only change appears safe to merge.

The updated MDX uses ordinary Markdown constructs supported by the existing content pipeline, and no incorrect, broken, or internally inconsistent changed behavior was established.

_{Reviews (1): Last reviewed commit: "docs(integrations): document all session..." | Re-trigger Greptile}

Context used:

• Knowledge Base — Content and MDX Build Pipeline

[claude]

Claude Code Review

This pull request is from a fork — automated review is disabled. A repository maintainer can comment @claude review to run a one-time review.

[vercel]

@jorgehermo9 is attempting to deploy a commit to the langfuse Team on Vercel.

A member of the Team first needs to authorize it.

[CLAassistant]

All committers have signed the CLA.