langfuse_ai_logging mis-forwards usage_details

Problem/Motivation

LangFuseAiLoggingSubscriber::completeGeneration() forwards the AI module's raw provider usage array straight through to the SDK's usage_details field:

// web/modules/contrib/langfuse/modules/langfuse_ai_logging/src/EventSubscriber/LangFuseAiLoggingSubscriber.php:413
$outputData['usage_details'] = $raw['usage'];

When the upstream LLM response has no reasoning/thinking tokens, providers (confirmed with LiteLLM 1.88.1 proxying Vertex AI Gemini) return completion_tokens_details as an empty JSON object ({}). PHP's json_decode(..., true) collapses that into an empty PHP array ([]), and it stays that way through to the outbound Guzzle request, which re-encodes it as a JSON array (json_encode([]) → "[]", never "{}", without JSON_FORCE_OBJECT).

Langfuse's ingestion API expects an object there; receiving an array instead causes it to abandon structured input/output mapping for that generation entirely — the trace shows 0 prompt → 0 completion with everything dumped into an "Other usage" bucket, and the total is a naive sum of all the raw fields (e.g. prompt_tokens + completion_tokens + total_tokens) instead of the correct total.

Models where reasoning is always active (and thus completion_tokens_details is always non-empty) never trigger this — which made it look model-specific rather than a general shape bug.

Steps to reproduce

1. Configure langfuse_ai_logging against a LiteLLM-proxied model where reasoning/thinking is disabled or unsupported for a given call (e.g. vertex_ai/gemini-3.5-flash with no reasoning_effort applied).
2. Make a chat completion request.
3. Compare the resulting Langfuse trace's usage breakdown against a call to a model that does return reasoning tokens.

Proposed resolution

Don't forward the raw provider usage array unmodified. At minimum, strip empty arrays:

$usage = $raw['usage'];
foreach (['completion_tokens_details', 'prompt_tokens_details'] as $key) {
  if (isset($usage[$key]) && $usage[$key] === []) {
    unset($usage[$key]);
  }
}
$outputData['usage_details'] = $usage;

Longer-term, usage_details should be built via an explicit mapping (prompt_tokens→input, completion_tokens→output, completion_tokens_details.reasoning_tokens→output_reasoning_tokens, etc.) rather than trusting the raw provider shape to match Langfuse's schema.

Pointers

• web/modules/contrib/langfuse/modules/langfuse_ai_logging/src/EventSubscriber/LangFuseAiLoggingSubscriber.php:404-415
• vendor/dropsolid/langfuse-php-sdk/src/Observability/Generation.php:98-115 (toArray() passes usageDetails through unchanged to the API payload)
• vendor/dropsolid/langfuse-php-sdk/src/Client.php:106-135 (performHttpRequest where the array/object re-encoding actually happens)
• Related LiteLLM upstream behavior/issue: BerriAI/litellm#31759 — inconsistent completion_tokens_details across providers/models is the trigger condition, though the type-mismatch bug itself is on the Drupal SDK/module side.

Release-line note, 2026-08-14

The two-part resolution above maps onto two different releases, which is worth stating so the module-side strip does not look like the permanent answer.

The explicit field mapping belongs in dropsolid/langfuse-php-sdk, which should not emit empty detail maps as [] at all. That is scheduled for SDK 1.3.1. The 1.0.x line is pinned to ~1.2.0 and cannot consume it, so for 1.0 the module strips the empty maps itself, exactly as proposed above. The 1.1.x line runs on SDK 1.3 and can revisit the workaround once the SDK fix lands.

One note on verification: confirming that Langfuse accepts the ingestion is not enough on its own, because the reported failure mode is miscounted usage rather than a rejected request. The token breakdown has to be checked against a known-good call, the way the steps to reproduce already describe.