Skip to content

feat(server,do,ai): post-hoc span attributes + traced rag embed cost - #170

Merged
prisis merged 2 commits into
alphafrom
feat/post-hoc-span-attributes
Jul 22, 2026
Merged

prisis merged 2 commits into
alphafrom
feat/post-hoc-span-attributes

Conversation

@prisis

@prisis prisis commented Jul 22, 2026 •

Copy link
Copy Markdown
Member

Trace-fusion, piece 1 — post-hoc span attributes (the shippable, portable piece)

ctx.trace(name, fn, attributes?) captured attributes only at span start. This lets the wrapped body set attributes that are only known after it resolves (an AI call's token usage / dollar cost). Additive and backward-compatible.

  • New SpanHandle (shared/span-event.ts): setAttribute(key, value) / setAttributes(fields), exported from @lunora/server + @lunora/do.
  • LunoraTracer gains a second body arg — (trace, span) => … — mirrored as ContextTracer in @lunora/do, kept in lockstep by the ctx-telemetry-contract drift guard. Start attributes still normalize up front (invariant preserved); post-hoc attrs merge at record time (post-hoc wins on key clash), emitted only when non-empty.
  • Backward-compatible: existing (trace) => … bodies stay assignable (trailing-optional-param rule). Only one call site changed — the @lunora/testing passthroughTrace stub (it assigns to LunoraTracer, so needs the param). All ctx.trace(...) bodies compile unchanged.

First consumer — RAG embed cost: define-rag.ts (already traced since #160/#162) now attaches post-hoc gen_ai.usage.input_tokens (from the embed usage) and gen_ai.usage.cost (defensive providerMetadata probe — a no-op until AI-Gateway cost routing from #165 lands). Untraced path unchanged.

Verify: do 1186 / ai 94 / testing 81 / server 419 tests pass; tsc clean across server/do/ai/testing (+ agent/runtime consumers); eslint clean.

Follow-up: trace-fusion piece 2 (fuse ctx.trace into Cloudflare's now-GA Workers custom-spans tree via tracing.enterSpan) is deferred behind a ShardDO prototype — double-export risk + async-context-in-DO unverified. otlpSink stays the portable default.

🤖 Generated with Claude Code

Summary by CodeRabbit

  • New Features

    • Enhanced tracing for embedding operations with model, token usage, and cost details when available.
    • Added support for attaching attributes to spans after a traced operation completes.
    • Exposed span handling types through the public APIs.
  • Documentation

    • Clarified tracing behavior and recorded embedding metadata in API documentation.

Let a ctx.trace body attach attributes only known after it resolves via a
new SpanHandle second callback arg (setAttribute/setAttributes), merged over
the start attributes at record time (post-hoc wins on a key clash). Additive
and backward-compatible — the handle is a trailing parameter, so every
existing (trace) => ... body still compiles and behaves unchanged.

Wire it through @lunora/ai/rag: the embed span now carries gen_ai.usage
.input_tokens (from the AI SDK embed result usage) and gen_ai.usage.cost
(defensively probed from providerMetadata / AI Gateway, omitted when absent).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0197KjhmBDB3PXAc6TXiPqZ9
@netlify

netlify Bot commented Jul 22, 2026 •

Copy link
Copy Markdown

✅ Deploy Preview for lunorash ready!

Name Link
🔨 Latest commit 1de1b33
🔍 Latest deploy log https://app.netlify.com/projects/lunorash/deploys/6a60c2806f3c1d000868dff4
😎 Deploy Preview https://deploy-preview-170--lunorash.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.
🤖 Make changes Run an agent on this branch

To edit notification comments on pull requests, go to your Netlify project configuration.

@coderabbitai

coderabbitai Bot commented Jul 22, 2026 •

Copy link
Copy Markdown

Review Change Stack

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 1b3cf777-a259-4998-ab9b-762b1eb48a98

📥 Commits

Reviewing files that changed from the base of the PR and between d71f8f1 and 1de1b33.

⛔ Files ignored due to path filters (7)
  • api-snapshots/do.api.md is excluded by none and included by none
  • api-snapshots/lunora.api.md is excluded by none and included by none
  • api-snapshots/server.api.md is excluded by none and included by none
  • packages/ai/__tests__/rag.test.ts is excluded by !**/__tests__/**, !**/*.test.ts and included by packages/**
  • packages/do/__tests__/tracing.test.ts is excluded by !**/__tests__/**, !**/*.test.ts and included by packages/**
  • packages/testing/__tests__/ctx-telemetry-contract.test.ts is excluded by !**/__tests__/**, !**/*.test.ts and included by packages/**
  • shared/span-event.ts is excluded by none and included by none
📒 Files selected for processing (7)
  • packages/ai/src/rag/define-rag.ts
  • packages/ai/src/rag/types.ts
  • packages/do/src/context-telemetry.ts
  • packages/do/src/index.ts
  • packages/server/src/index.ts
  • packages/server/src/types.ts
  • packages/testing/src/harness.ts

Walkthrough

The tracing APIs now provide span handles for post-hoc attributes. RAG embedding calls use them to record model identifiers, token usage, and available provider costs, while untraced calls retain their vector-only return path.

Changes

Embedding tracing

Layer / File(s) Summary
Span handle contracts and exports
packages/server/src/types.ts, packages/server/src/index.ts, packages/do/src/context-telemetry.ts, packages/do/src/index.ts
Tracing callbacks receive a SpanHandle with attribute-setting methods, and the type is re-exported through package entrypoints.
Span attribute collection
packages/do/src/context-telemetry.ts, packages/testing/src/harness.ts
Tracer spans collect normalized post-hoc attributes, merge them over start attributes, and the test harness supplies a no-op span handle.
RAG embedding instrumentation
packages/ai/src/rag/define-rag.ts, packages/ai/src/rag/types.ts
Embedding execution propagates the span handle and records model, input-token, and available cost attributes after resolution; JSDoc documents the behavior.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant defineRag
  participant ctxTrace as ctx.trace
  participant embeddingModel as Embedding model
  participant spanHandle as SpanHandle
  defineRag->>ctxTrace: Start generation span with model id
  ctxTrace->>embeddingModel: Execute embedding
  embeddingModel-->>defineRag: Return vectors, usage, metadata
  defineRag->>spanHandle: Record tokens and optional cost
  ctxTrace-->>defineRag: Return embedding vectors
Loading
🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Title check ✅ Passed The title clearly matches the main change: post-hoc span attributes and traced RAG embed cost instrumentation.
Description check ✅ Passed The description is detailed and covers the core change, testing, follow-up, and CLA, but it omits the template's Linked issues and checklist sections.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
✨ 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 feat/post-hoc-span-attributes

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@github-actions

Copy link
Copy Markdown
Contributor

Thank you for following the naming conventions! 🙏

@github-actions

Copy link
Copy Markdown
Contributor

Thank you for confirming the Contributor License Agreement! 🙏

@codspeed

codspeed Bot commented Jul 22, 2026 •

Copy link
Copy Markdown

Merging this PR will improve performance by 10.28%

⚠️ Different runtime environments detected

Some benchmarks with significant performance changes were compared across different runtime environments,
which may affect the accuracy of the results.

Open the report in CodSpeed to investigate

⚡ 1 improved benchmark
✅ 159 untouched benchmarks
⏩ 1 skipped benchmark1

Performance Changes

Benchmark BASE HEAD Efficiency
⚡ hit: cache.run returns memoized result 73.2 µs 66.4 µs +10.28%

Tip

Curious why this is faster? Comment @codspeedbot explain why this is faster on this PR, or directly use the CodSpeed MCP with your agent.


Comparing feat/post-hoc-span-attributes (1de1b33) with alpha (0804b38)2

Open in CodSpeed

Footnotes

  1. 1 benchmark was skipped, so the baseline result was used instead. If it was deleted from the codebase, click here and archive it to remove it from the performance reports. ↩

  2. No successful run was found on alpha (d71f8f1) during the generation of this report, so 0804b38 was used instead as the comparison base. There might be some changes unrelated to this pull request in this report. ↩

Regenerates the server/do/lunora api-snapshots to record the new SpanHandle
interface and the LunoraTracer/ContextTracer second `span` callback arg.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0197KjhmBDB3PXAc6TXiPqZ9
@prisis
prisis merged commit 8ebe128 into alpha Jul 22, 2026
44 checks passed
@prisis
prisis deleted the feat/post-hoc-span-attributes branch July 22, 2026 14:48
@github-actions

github-actions Bot commented Sep 9, 2026

Copy link
Copy Markdown
Contributor

This pull request has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.
Please note this issue tracker is not a help forum. We recommend using our GitHub Discussions tab for questions.

@github-actions github-actions Bot locked as resolved and limited conversation to collaborators Sep 9, 2026

This branch was previously deployed

1 inactive deployment
benchmarks — 1de1b331 Deployed Jul 22, 2026 by prisis via Benchmarks #853
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant