From 4763bd1b4025cd8b36573f9c1cbe02cdf9822c4b Mon Sep 17 00:00:00 2001 From: "mads.thines" Date: Sat, 14 Nov 2026 11:29:42 +0000 Subject: [PATCH] feat(telemetry): stamp auth.user_id on tool and REST handler spans The caller's id was only on the root request span, while the facts a per-user view needs (lorekit.write.inserted, lorekit.memory.count) sit on the child operation span. Span metrics cannot join the two, so memories per user could not be charted. Co-authored-by: dash0-dev[bot] <257284812+dash0-dev[bot]@users.noreply.github.com> --- docs/otel.md | 1 + .../tool-span-user-identity.spec.ts | 80 +++++++++++++++++++ supabase/functions/_shared/api/router.ts | 7 ++ supabase/functions/mcp/mcp-handler.ts | 8 ++ 4 files changed, 96 insertions(+) create mode 100644 packages/mcp-core/src/mcp-guards/tool-span-user-identity.spec.ts diff --git a/docs/otel.md b/docs/otel.md index 1e7ba1be7..be0e0d81f 100644 --- a/docs/otel.md +++ b/docs/otel.md @@ -87,6 +87,7 @@ Attributes on `lorekit.memory.*` spans: | Attribute | Example | Notes | |-----------|---------|-------| | `lorekit.tool.name` | `memory.write` | Bounded set — safe as metric dimension | +| `auth.user_id` | `6e05fc90-…` | The caller's Supabase user UUID (pseudonymous), the same id the root request span and `usage_events.user_id` carry. Repeated here — and on the REST handler spans (`lorekit.memories.get/quota`, the write route, …) — because span metrics cannot join a child span to its parent: per-user counts of `lorekit.write.inserted` or `lorekit.memory.count` need the id on the span that holds them. **Omitted** for service-role callers, never empty. Guarded by `mcp-guards/tool-span-user-identity.spec.ts` | | `lorekit.scope` | `repo::mthines/gw-tools` | Canonical scope string | | `lorekit.scope.type` | `repo` | `global` \| `project` \| `repo` \| `branch` \| `mixed` (a multi-type `memory.search`, or a batch `memory.read` whose `refs` span several scope types) \| `invalid` (ungrammatical input). **Omitted entirely** when the operation carries no scope — never a placeholder. Resolved by the shared `scope-type-attribute.ts`. A batch read names its scopes inside `refs` rather than in a `scope` argument or query string, so MCP resolves them from the parsed refs and REST's handler reports the type to the router through `X-LoreKit-Scope-Type` — see "Scope attribution for body-carried scopes" below | | `lorekit.key` | `aw-lessons::worktree-naming` | Lesson key | diff --git a/packages/mcp-core/src/mcp-guards/tool-span-user-identity.spec.ts b/packages/mcp-core/src/mcp-guards/tool-span-user-identity.spec.ts new file mode 100644 index 000000000..c5ea64212 --- /dev/null +++ b/packages/mcp-core/src/mcp-guards/tool-span-user-identity.spec.ts @@ -0,0 +1,80 @@ +import { describe, it, expect } from 'vitest'; +import { readFileSync } from 'node:fs'; +import { fileURLToPath } from 'node:url'; +import path from 'node:path'; + +/** + * Source-scan drift guard: the caller's `auth.user_id` is stamped on the + * per-operation span, not only on the root request span. + * + * Both surfaces already put `auth.user_id` on their ROOT span (`lorekit.mcp` + * in `mcp/index.ts`, `lorekit.memories` / `lorekit.orgs` in + * `_shared/api/router.ts`). The facts a per-user view needs are written one + * level down, on the operation span: + * + * - MCP `lorekit.memory.write` — `lorekit.write.inserted`, `lorekit.source_agent` + * - MCP `lorekit.memory.quota` and REST `lorekit.memories.get/quota` — + * `lorekit.memory.count`, `lorekit.memory.limit` + * + * Span metrics (Dash0's `dash0.spans`, any spanmetrics connector) group one + * span's attributes at a time and cannot join a child to its parent, so + * without the id on the operation span "memories held per user" and "new + * memories per user" are unanswerable without a trace join. + * + * The edge tree has no test job, and the regression is missing telemetry, not + * a wrong value — nothing else in the suite goes red if a refactor drops it. + */ + +const here = path.dirname(fileURLToPath(import.meta.url)); // packages/mcp-core/src/mcp-guards +const repoRoot = path.resolve(here, '../../../..'); +const fnRoot = path.join(repoRoot, 'supabase', 'functions'); + +/** Executable lines only — mirrors `mcp-handler-plan-reuse.spec.ts`. */ +const COMMENT_PREFIXES = ['//', '*', '/*', '*/']; +function executable(relPath: string): string { + return readFileSync(path.join(fnRoot, relPath), 'utf8') + .split('\n') + .map((line) => line.trim()) + .filter((line) => line.length > 0) + .filter((line) => !COMMENT_PREFIXES.some((prefix) => line.startsWith(prefix))) + .join('\n'); +} + +const handler = executable('mcp/mcp-handler.ts'); +const router = executable('_shared/api/router.ts'); + +describe('MCP tool span carries the caller (mcp/mcp-handler.ts)', () => { + // Anti-vacuity: a rename that made the span or the id unfindable must fail loudly. + it('still creates the tool span and still resolves analyticsUserId', () => { + expect(handler).toMatch(/const toolSpan = span\.child\(`lorekit\.\$\{toolName\}`/); + expect(handler).toMatch(/const analyticsUserId = /); + }); + + it('stamps auth.user_id on the tool span, guarded so it is absent rather than empty', () => { + expect(handler).toMatch( + /if \(analyticsUserId\) toolSpan\.setAttributes\(\{ 'auth\.user_id': analyticsUserId \}\);/, + ); + }); +}); + +describe('REST handler span carries the caller (_shared/api/router.ts)', () => { + it('still creates the handler span and still passes it to the route handler', () => { + expect(router).toMatch(/const hs = span\.child\(/); + expect(router).toContain('route.handler(req, resolved.auth, resolved.db, hs, params, cors)'); + }); + + it('stamps auth.user_id on the handler span, guarded so it is absent rather than empty', () => { + expect(router).toMatch( + /if \(usageUserId !== null\) hs\.setAttributes\(\{ 'auth\.user_id': usageUserId \}\);/, + ); + }); +}); + +describe('no placeholder user id on either surface', () => { + it('never writes an empty or defaulted auth.user_id', () => { + for (const src of [handler, router]) { + expect(src).not.toMatch(/'auth\.user_id':\s*''/); + expect(src).not.toMatch(/'auth\.user_id':\s*[^,}]+\?\?\s*''/); + } + }); +}); diff --git a/supabase/functions/_shared/api/router.ts b/supabase/functions/_shared/api/router.ts index eebe267f1..52dce18e6 100644 --- a/supabase/functions/_shared/api/router.ts +++ b/supabase/functions/_shared/api/router.ts @@ -282,6 +282,13 @@ export function createRouter(routes: Route[], functionName: string) { 'auth.type': usageAuthType(resolved.auth), ...(usageUserId !== null ? { 'auth.user_id': usageUserId } : {}), }); + // ...and on the HANDLER span (`lorekit.memories.get/quota`, the write + // route, …), which is where handlers stamp what they learned — + // `lorekit.memory.count`, `lorekit.write.inserted`. A span-metric backend + // groups one span's attributes at a time and cannot join a child to its + // root, so the identity has to sit beside those facts for "memories per + // user" to be chartable. Same id, same absent-never-empty rule. + if (usageUserId !== null) hs.setAttributes({ 'auth.user_id': usageUserId }); // Only from the query string: the router must not consume the request // body to peek at a scope, so body-carried scopes report null. Same diff --git a/supabase/functions/mcp/mcp-handler.ts b/supabase/functions/mcp/mcp-handler.ts index 236a3d656..379899c5d 100644 --- a/supabase/functions/mcp/mcp-handler.ts +++ b/supabase/functions/mcp/mcp-handler.ts @@ -380,6 +380,14 @@ export async function handleMcp(req: Request, auth: AuthContext, span: Span, ada ? await getUserPlanName(db, analyticsUserId, span) : null; if (planName) toolSpan.setAttributes({ 'lorekit.plan': planName }); + // Caller identity on the TOOL span, not only on the root `lorekit.mcp` + // span (`mcp/index.ts`). The facts a per-user view needs live HERE — + // `lorekit.write.inserted`, `lorekit.memory.count`, `lorekit.source_agent`, + // `lorekit.scope.type` — and a span-metric backend cannot join a child + // span to its parent, so without the id on this span "new memories per + // user" or "memories held per user" is unanswerable without a trace join. + // Same id the usage event records; absent, never empty, for service-role. + if (analyticsUserId) toolSpan.setAttributes({ 'auth.user_id': analyticsUserId }); // Client-supplied grouping key (same header as the REST surface). Bounded by // the pure validator; a malformed value degrades to null, never an error.