adds otel spec compatible metrics (backward compatible)

[akshaydeo]

Summary

Aligns tracing attributes with the OpenTelemetry GenAI semantic conventions by introducing spec-compliant attribute keys alongside the existing legacy ones, ensuring backward compatibility while moving toward standardized observability.

Changes

• Added AttrTimeToFirstChunk (gen_ai.response.time_to_first_chunk) emitted in seconds (float64) alongside the existing AttrTimeToFirstToken which remains in nanoseconds for backward compatibility.
• Added AttrUsageReasoningOutputTokens (gen_ai.usage.reasoning.output_tokens) emitted alongside the legacy nested AttrCompletionTokenDetailsReason and AttrOutputTokenDetailsReason keys for both Chat and Responses API spans.
• Fixed gen_ai.response.finish_reasons (string array) to be set directly on the GenAI span per spec, while still exposing the scalar gen_ai.response.finish_reason (first element only) for backward compatibility.
• Annotated all legacy attribute constants and usages with comments clarifying their deprecated status and their spec-compliant replacements.

Type of change

• Bug fix
• Feature
• Refactor
• Documentation
• Chore/CI

Affected areas

• Core (Go)
• Transports (HTTP)
• Providers/Integrations
• Plugins
• UI (React)
• Docs

How to test

go test ./...

Verify that traces emitted for streaming responses include both gen_ai.response.time_to_first_token (nanoseconds) and gen_ai.response.time_to_first_chunk (seconds). Verify that reasoning token usage emits both the legacy nested key and gen_ai.usage.reasoning.output_tokens. Verify that gen_ai.response.finish_reasons is present as a string array on the GenAI span.

Breaking changes

• Yes
• No

Related issues

Security considerations

None.

Checklist

• I read docs/contributing/README.md and followed the guidelines
• I added/updated tests where appropriate
• I updated documentation where needed
• I verified builds succeed (Go and UI)
• I verified the CI pipeline passes locally if applicable

Summary by CodeRabbit

• New Features
  • Expanded GenAI operation tracing with new metrics: time-to-first-chunk measurement and reasoning output tokens tracking for enhanced observability.
  • Introduced structured finish reasons attribute on GenAI spans, providing clearer insights into completion behaviors.
  • All new tracing attributes maintain full backward compatibility, allowing existing implementations to continue working without modifications.

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[akshaydeo]

• adds otel spec compatible metrics (backward compatible) #3865 👈 (View in Graphite)
• dev

This stack of pull requests is managed by Graphite. Learn more about stacking.

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR extends GenAI tracing semantics by adding new span attributes (time_to_first_chunk, reasoning.output_tokens, and finish_reasons array) while maintaining backward compatibility with legacy singular attributes across the tracing framework and provider utilities.

Changes

GenAI Semantic Attributes and Tracing

Layer / File(s)	Summary
Semantic attribute schema definitions core/schemas/trace.go	Adds AttrTimeToFirstChunk and AttrUsageReasoningOutputTokens constants; marks AttrTimeToFirstToken as legacy.
Time-to-first-chunk tracing emission core/providers/utils/utils.go	Converts nanosecond ttftNs to seconds and emits AttrTimeToFirstChunk while retaining legacy AttrTimeToFirstToken.
Reasoning output tokens tracing emissions framework/tracing/llmspan.go	Adds AttrUsageReasoningOutputTokens emission in chat completion and responses API handlers alongside legacy nested reason attributes.
Finish reasons array tracing emission framework/tracing/tracer.go	Sets full AttrFinishReasons array on span while preserving legacy singular AttrFinishReason from first element.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Suggested reviewers

• danpiths

Poem

🐰 Tracing gets sharper with each new token,
From first-chunk whispers to reasoning spoken,
Legacy paths stay—no breakage in sight,
GenAI semantics now shining more bright! ✨

🚥 Pre-merge checks | ✅ 2 | ❌ 3

❌ Failed checks (2 warnings, 1 inconclusive)

Check name	Status	Explanation	Resolution
Linked Issues check	⚠️ Warning	The PR changes are not related to the linked issue #123 (Files API Support). The PR implements OpenTelemetry semantic convention attributes for tracing, while #123 requires File API support for uploads.	Either link the correct related issues for the OpenTelemetry changes or clarify if #123 is the intended issue and update the PR accordingly.
Out of Scope Changes check	⚠️ Warning	The PR implements OpenTelemetry semantic convention attributes, which is entirely out of scope relative to the linked issue #123 that requires Files API support for uploads.	Remove the incorrect issue link #123 and either identify the correct related issues for OpenTelemetry changes or proceed without linked issues if none exist.
Title check	❓ Inconclusive	The title 'adds otel spec compatible metrics (backward compatible)' is vague and generic, using non-descriptive terms that don't clearly convey what OpenTelemetry metrics or specific changes are involved.	Revise the title to be more specific about the actual changes, e.g., 'Add OpenTelemetry GenAI semantic convention attributes' or similar that better describes the concrete implementation.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Description check	✅ Passed	The PR description comprehensively covers all required template sections with detailed explanations of changes, testing instructions, and proper checkbox selections.

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

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch 05-29-adds_otel_spec_compatible_metrics_backward_compatible_

---

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

[greptile-apps]

Confidence Score: 5/5

All changes are purely additive attribute emissions with no modification to existing values or control flow; backward compatibility is fully preserved.

Every change follows the same pattern: emit the new spec-named attribute in addition to (not instead of) the legacy one. No branching logic, no shared-state mutations, no concurrent access paths are touched. The float64 seconds conversion for TTFT is arithmetically correct, and the switch-based dispatch in PopulateResponseAttributes already guarantees only one response-type branch fires, so there is no double-write concern for the reasoning-tokens attribute.

No files require special attention.

Important Files Changed

Filename	Overview
core/schemas/trace.go	Adds two new OTel-spec constant names: AttrTimeToFirstChunk (seconds) and AttrUsageReasoningOutputTokens, alongside existing legacy constants.
core/providers/utils/utils.go	Emits both legacy time_to_first_token (nanoseconds int64) and new time_to_first_chunk (seconds float64) attributes when ttftNs > 0; conversion is correct.
framework/tracing/llmspan.go	Adds AttrUsageReasoningOutputTokens alongside the legacy nested key in both PopulateChatResponseAttributes and PopulateResponsesResponseAttributes; the switch-based dispatch in PopulateResponseAttributes ensures no double-write.
framework/tracing/tracer.go	PopulateLLMResponseAttributes now emits AttrFinishReasons (string[]) on the llm.call span in addition to the existing scalar AttrFinishReason; the continue guard prevents a redundant second write.

_{Reviews (1): Last reviewed commit: "adds otel spec compatible metrics (backw..." | Re-trigger Greptile}

[akshaydeo]

Merge activity

• May 29, 5:17 AM UTC: A user started a stack merge that includes this pull request via Graphite.
• May 29, 5:18 AM UTC: @akshaydeo merged this pull request with Graphite.