Reasoning parameters missing from OTel span attributes

[turisanapo]

Summary

The reasoning and reasoning_effort request parameters are accepted and correctly forwarded to upstream providers, but they are not emitted as OpenTelemetry span attributes in getChatRequestAttributes. This makes reasoning configuration invisible in observability dashboards.

Steps to Reproduce

1. Send a chat completion request with reasoning configuration:

curl -X POST https://gateway.example.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/gemini-3-flash-preview",
    "stream": true,
    "messages": [{"role": "user", "content": "Hello"}],
    "reasoning": {"effort": "minimal"}
  }'

2. Open the observability dashboard (or inspect the OTel span attributes directly)
3. Look for reasoning-related attributes in the span

Expected Behavior

The span attributes should include reasoning configuration, e.g.:

• gen_ai.request.reasoning_effort: "minimal"
• gen_ai.request.reasoning.enabled: true
• gen_ai.request.reasoning.max_tokens: (if provided)

These should appear in the Raw JSON / trace detail view of any OTel-consuming dashboard.

Actual Behavior

No reasoning-related attributes are emitted on the span. The reasoning configuration is invisible in observability tools despite being correctly processed and forwarded to the upstream provider.

Root Cause

In endpoints/chat-completions/otel.js, the getChatRequestAttributes function emits various request attributes (stream, service_tier, temperature, top_p, etc.) but does not include body.reasoning or body.reasoning_effort.

Environment

• @hebo-ai/gateway: 0.8.0
• Model tested: google/gemini-3-flash-preview (via alias)
• The request processing pipeline (schema validation → parseReasoningOptions → middleware → Vertex thinkingConfig) works correctly — this is purely a telemetry gap.

[heiwen]

@claude is this a bug or a missing feature?

[hebo-agent]

Claude finished @heiwen's task in 1m 0s —— View job

---

Analyzing: Bug or Missing Feature?

• Gather context — examine the relevant code
• Classify the issue and provide answer

---

This is a missing feature, not a bug.

In src/endpoints/chat-completions/otel.ts:138, there's an explicit comment:

// FUTURE: add reasoning info

This shows the omission was intentional/known — the reasoning parameters were added to the request pipeline (schema validation, parseReasoningOptions, provider converters) but the OTel instrumentation was deferred as a follow-up task.

The fix itself is straightforward: add attributes like gen_ai.request.reasoning_effort, gen_ai.request.reasoning.enabled, and gen_ai.request.reasoning.max_tokens in getChatRequestAttributes, replacing that // FUTURE comment. The response side already captures reasoning tokens (gen_ai.usage.reasoning.output_tokens), so it's just the request side that's missing.

Let me know if you'd like me to implement this.

---

[heiwen]

@claude any official opentelemetry convention we can use? Alternatively, langfuse / helicone / other observability solutions?

[hebo-agent]

Claude finished @heiwen's task in 4m 3s —— View job

---

Researching OTel Conventions for Reasoning Parameters

• Review existing OTel code in this repo
• Research official OpenTelemetry GenAI semantic conventions
• Research Langfuse / Helicone / other observability platforms
• Provide recommendation

---

Findings

Official OpenTelemetry GenAI Semantic Conventions

Response side (reasoning tokens): There is no merged attribute yet, but PR #3383 ("genai: define reasoning tokens attribute") proposes:

• gen_ai.usage.reasoning.output_tokens — int, recommended, development stability
• Reasoning tokens are defined as a subset of gen_ai.usage.output_tokens (not additive)

This is the naming convention hebo-gateway already uses at otel.ts:198 — so we're aligned with the likely future standard.

Request side (reasoning_effort, reasoning config): There is no proposal at all in the OTel spec for reasoning_effort or any request-side reasoning configuration attributes. Searching the semantic-conventions repo for "reasoning_effort" returns zero results.

Observability Platforms

Platform	Reasoning token tracking	Reasoning config (request)
Langfuse	Maps completion_tokens_details.reasoning_tokens from the OpenAI response format. Internally prefixed as output reasoning tokens.	No specific support for request-side reasoning config.
Helicone	No public documentation found for reasoning token tracking specifically.	No specific support.

Neither platform has established conventions for request-side reasoning attributes.

Recommendation

Since there's no official or de facto standard for request-side reasoning attributes, I'd suggest we follow the existing naming patterns already used in this codebase and align with the hierarchical style from the OTel proposals:

gen_ai.request.reasoning_effort      → body.reasoning_effort (top-level, OpenAI-style)
gen_ai.request.reasoning.effort      → body.reasoning.effort (from reasoning config object)
gen_ai.request.reasoning.enabled     → body.reasoning.enabled
gen_ai.request.reasoning.max_tokens  → body.reasoning.max_tokens

Rationale:

• gen_ai.request.reasoning_effort mirrors the existing pattern of gen_ai.request.temperature, gen_ai.request.max_tokens, etc.
• gen_ai.request.reasoning.* uses the same hierarchical namespace as the already-adopted gen_ai.usage.reasoning.output_tokens on the response side
• Both reasoning_effort (OpenAI-style top-level param) and reasoning.effort (extension config) should be emitted, since they can be set independently

If the OTel spec later standardizes different names, we can alias them — but for now this is the most consistent approach with both the spec direction and existing codebase patterns.

Want me to go ahead and implement this?

---

View job

[heiwen]

@claude got it. let's do this:

1/ Implement gen_ai.request.reasoning.enabled, gen_ai.request.reasoning.effort, gen_ai.request.reasoning.max_tokens
2/ we can skip gen_ai.request.reasoning_effort, because the code always synchronizes it to gen_ai.request.reasoning.effort
3/ gen_ai.usage.reasoning.output_tokens is already implemented, no changes needed

[hebo-agent]

Claude finished @heiwen's task in 3m 0s —— View job • claude-issue-84-20260331-0255 • Create PR ➔

---

Implementing Reasoning OTel Span Attributes

• Read relevant source files and understand the current implementation
• Add reasoning attributes to getChatRequestAttributes in otel.ts
• Add tests for the new reasoning attributes
• Run tests and ensure they pass (11/11 pass, typecheck clean)
• Commit and push changes

---

Changes made:

• src/endpoints/chat-completions/otel.ts — Added gen_ai.request.reasoning.enabled, gen_ai.request.reasoning.effort, and gen_ai.request.reasoning.max_tokens attributes in getChatRequestAttributes (replacing the // FUTURE: add reasoning info comment). These are emitted at recommended signal level alongside other request attributes.

• src/endpoints/chat-completions/otel.test.ts — Added two tests: one verifying attributes are correctly mapped from the reasoning config, and one verifying they're undefined when no reasoning config is present.

[heiwen]

Implemented in 0.8.2 release: https://github.com/8monkey-ai/hebo-gateway/releases/tag/0.8.2