fix: propagate user hash to startup spans

.changeset/user-hash-spans.md

@@ -0,0 +1,5 @@
+---
+"hevy-mcp": patch
+---
+
+Use the OpenTelemetry `user.hash` semantic convention and propagate the user hash to every recorded span.

src/index.test.ts

@@ -13,6 +13,7 @@ const originalEnv = { ...process.env };
 const originalArgv = [...process.argv];
 const TEST_KEY_HMAC_SHA256 = "2cb0b5f95a";
 const TEST_API_KEY_HMAC_SHA256 = "0eefd4f47c";
+const TEST_SECRET_API_KEY_HMAC_SHA256 = "e09f100508";
 
 const testDoubles = vi.hoisted(() => ({
 	span: {
@@ -84,8 +85,8 @@ vi.mock("./utils/telemetry.js", () => ({
 	},
 	serviceName: "hevy-mcp",
 	serviceVersion: "dev",
-	setCurrentUserId: vi.fn(),
-	getCurrentUserId: vi.fn(() => undefined),
+	setCurrentUserHash: vi.fn(),
+	getCurrentUserHash: vi.fn(() => undefined),
 }));
 
 vi.mock("./utils/metrics.js", () => ({
@@ -199,6 +200,7 @@ describe("Server entry", () => {
 			expect.objectContaining({
 				attributes: expect.objectContaining({
 					"mcp.server.name": "hevy-mcp",
+					"user.hash": TEST_KEY_HMAC_SHA256,
 				}),
 			}),
 			expect.any(Function),
@@ -491,6 +493,15 @@ describe("Server entry", () => {
 			expect(Sentry.setUser).toHaveBeenCalledWith({
 				id: TEST_API_KEY_HMAC_SHA256,
 			});
+			expect(testDoubles.startActiveSpan).toHaveBeenCalledWith(
+				"mcp.server.run",
+				expect.objectContaining({
+					attributes: expect.objectContaining({
+						"user.hash": TEST_API_KEY_HMAC_SHA256,
+					}),
+				}),
+				expect.any(Function),
+			);
 			expect(
 				JSON.stringify(vi.mocked(Sentry.setUser).mock.calls),
 			).not.toContain(secret);
@@ -656,6 +667,15 @@ describe("Server entry", () => {
 					"https://api.hevyapp.com",
 					{ maxGetRetries: 0, timeoutMs: 5_000 },
 				);
+				expect(testDoubles.startActiveSpan).toHaveBeenCalledWith(
+					"mcp.server.run",
+					expect.objectContaining({
+						attributes: expect.objectContaining({
+							"user.hash": TEST_SECRET_API_KEY_HMAC_SHA256,
+						}),
+					}),
+					expect.any(Function),
+				);
 				errorSpy.mockRestore();
 				stdoutSpy.mockRestore();
 			},

src/index.ts

@@ -5,7 +5,7 @@ import {
 	tracer,
 	serviceName,
 	serviceVersion,
-	setCurrentUserId,
+	setCurrentUserHash,
 } from "./utils/telemetry.js";
 import { serverStartups } from "./utils/metrics.js";
 
@@ -79,9 +79,9 @@ const SAFE_NETWORK_ERROR_CODES = new Set([
 const SENTRY_USER_ID_CONTEXT = "hevy-mcp:sentry-user-id:v1";
 
 function fingerprintApiKey(apiKey: string) {
-	// HMAC-SHA-256 gives Sentry a deterministic pseudonymous user ID without
-	// sending, logging, or storing the raw Hevy API key.
-	// Trimmed to 10 characters to keep it compact and readable in Sentry & OTel traces.
+	// HMAC-SHA-256 gives Sentry and OTel a deterministic pseudonymous user
+	// hash without sending, logging, or storing the raw Hevy API key.
+	// Trimmed to 10 characters to keep it compact and readable in traces.
 	return createHmac("sha256", apiKey)
 		.update(SENTRY_USER_ID_CONTEXT)
 		.digest("hex")
@@ -161,7 +161,8 @@ async function validateApiKey(apiKey: string) {
 }
 
 function buildServer(apiKey: string) {
-	const userId = fingerprintApiKey(apiKey);
+	const userHash = fingerprintApiKey(apiKey);
+	setCurrentUserHash(userHash);
 
 	return tracer.startActiveSpan(
 		"mcp.server.build",
@@ -170,13 +171,12 @@ function buildServer(apiKey: string) {
 				"mcp.server.name": name,
 				"mcp.server.version": version,
 				"mcp.transport": "stdio",
-				"user.id": userId,
+				"user.hash": userHash,
 			},
 		},
 		(span) => {
 			try {
-				Sentry.setUser({ id: userId });
-				setCurrentUserId(userId);
+				Sentry.setUser({ id: userHash });
 				const server = createSharedMcpServer({
 					apiKey,
 					clientOptions: createNodeHevyClientOptions(),
@@ -224,11 +224,22 @@ export async function runServer() {
 
 	serverStartups.add(1, { version });
 
+	// Seed the user context before config validation so startup failures for a
+	// supplied key retain the same trace correlation as normal tool calls.
+	const configuredApiKey = process.env.HEVY_API_KEY;
+	const initialUserHash = configuredApiKey
+		? fingerprintApiKey(configuredApiKey)
+		: undefined;
+	if (initialUserHash) {
+		setCurrentUserHash(initialUserHash);
+	}
+
 	await tracer.startActiveSpan(
 		"mcp.server.run",
 		{
 			attributes: {
 				"mcp.transport": "stdio",
+				...(initialUserHash ? { "user.hash": initialUserHash } : {}),
 			},
 		},
 		async (span) => {

src/utils/hevy-client-observability.test.ts

@@ -1,7 +1,7 @@
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import { HevyHttpError } from "./hevy-http-error.js";
 import { createNodeHevyClientOptions } from "./hevy-client-observability.js";
-import { getCurrentUserId } from "./telemetry.js";
+import { getCurrentUserHash } from "./telemetry.js";
 
 const testDoubles = vi.hoisted(() => ({
 	span: {
@@ -17,7 +17,7 @@ const testDoubles = vi.hoisted(() => ({
 testDoubles.startSpan.mockReturnValue(testDoubles.span);
 
 vi.mock("./telemetry.js", () => ({
-	getCurrentUserId: vi.fn(() => undefined),
+	getCurrentUserHash: vi.fn(() => undefined),
 	tracer: { startSpan: testDoubles.startSpan },
 }));
 
@@ -34,11 +34,11 @@ describe("createNodeHevyClientOptions", () => {
 	beforeEach(() => {
 		vi.clearAllMocks();
 		delete process.env.HEVY_MCP_API_TIMEOUT;
-		vi.mocked(getCurrentUserId).mockReturnValue(undefined);
+		vi.mocked(getCurrentUserHash).mockReturnValue(undefined);
 	});
 
 	it("records successful requests with bounded operational metadata", () => {
-		vi.mocked(getCurrentUserId).mockReturnValue("user-123");
+		vi.mocked(getCurrentUserHash).mockReturnValue("user-123");
 		const options = createNodeHevyClientOptions();
 
 		options.onRequestComplete?.({
@@ -53,7 +53,7 @@ describe("createNodeHevyClientOptions", () => {
 				"http.method": "GET",
 				"http.status_code": 200,
 				"hevy.api.endpoint": "/v1/user/info",
-				"user.id": "user-123",
+				"user.hash": "user-123",
 			},
 		});
 		expect(testDoubles.span.setStatus).toHaveBeenCalledWith({ code: 1 });

src/utils/hevy-client-observability.ts

@@ -3,7 +3,7 @@ import { debugLog } from "./debug.js";
 import type { HevyClientOptions } from "./hevyClientKubb.js";
 import { apiCalls, apiDuration } from "./metrics.js";
 import { createSafeErrorDiagnostic } from "./safe-error-diagnostic.js";
-import { getCurrentUserId, tracer } from "./telemetry.js";
+import { getCurrentUserHash, tracer } from "./telemetry.js";
 
 /** Node-only adapter; the Worker graph never imports telemetry or metrics. */
 export function createNodeHevyClientOptions(): HevyClientOptions {
@@ -21,8 +21,8 @@ export function createNodeHevyClientOptions(): HevyClientOptions {
 					"http.method": observation.method,
 					"http.status_code": observation.status,
 					"hevy.api.endpoint": observation.endpoint,
-					...(getCurrentUserId()
-						? { "user.id": getCurrentUserId() as string }
+					...(getCurrentUserHash()
+						? { "user.hash": getCurrentUserHash() }
 						: {}),
 				},
 			});

src/utils/stdio-observability.test.ts

@@ -58,8 +58,8 @@ vi.mock("./telemetry.js", () => ({
 	},
 	serviceName: "hevy-mcp",
 	serviceVersion: "dev",
-	setCurrentUserId: vi.fn(),
-	getCurrentUserId: vi.fn(() => undefined),
+	setCurrentUserHash: vi.fn(),
+	getCurrentUserHash: vi.fn(() => undefined),
 }));
 
 vi.mock("./metrics.js", () => ({

src/utils/telemetry-wrapper.test.ts

@@ -1,6 +1,6 @@
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import { HevyHttpError } from "./hevy-http-error.js";
-import { getCurrentUserId } from "./telemetry.js";
+import { getCurrentUserHash } from "./telemetry.js";
 import { withTelemetry } from "./telemetry-wrapper.js";
 
 const testDoubles = vi.hoisted(() => ({
@@ -22,7 +22,7 @@ const testDoubles = vi.hoisted(() => ({
 
 vi.mock("./telemetry.js", () => ({
 	tracer: { startActiveSpan: testDoubles.startActiveSpan },
-	getCurrentUserId: vi.fn(() => undefined),
+	getCurrentUserHash: vi.fn(() => undefined),
 }));
 
 vi.mock("./metrics.js", () => ({
@@ -39,7 +39,7 @@ describe("withTelemetry", () => {
 	beforeEach(() => {
 		delete process.env.HEVY_MCP_DEBUG;
 		vi.clearAllMocks();
-		vi.mocked(getCurrentUserId).mockReturnValue(undefined);
+		vi.mocked(getCurrentUserHash).mockReturnValue(undefined);
 	});
 
 	it("emits redacted debug input from the central tool wrapper", async () => {
@@ -258,8 +258,8 @@ describe("withTelemetry", () => {
 		);
 	});
 
-	it("preserves safe argument ordering, scalar values, truncation, and user ID", async () => {
-		vi.mocked(getCurrentUserId).mockReturnValue("user-123");
+	it("preserves safe argument ordering, scalar values, truncation, and user hash", async () => {
+		vi.mocked(getCurrentUserHash).mockReturnValue("user-123");
 		const handler = vi.fn().mockResolvedValue({ content: [] });
 		const longQuery = "a".repeat(120);
 
@@ -283,7 +283,7 @@ describe("withTelemetry", () => {
 					"workflow.name": "ArgsContext",
 					"mcp.tool.args.key_count": 6,
 					"mcp.tool.args.keys": "page,pageSize,query,includeCustom",
-					"user.id": "user-123",
+					"user.hash": "user-123",
 					"mcp.tool.args.page": 2,
 					"mcp.tool.args.pageSize": 10,
 					"mcp.tool.args.query": `${"a".repeat(100)}...`,

src/utils/telemetry-wrapper.ts

@@ -3,7 +3,7 @@ import { debugLog, isDebugEnabled, redactToolArgs } from "./debug.js";
 import { resolveErrorPolicy } from "./error-policy.js";
 import { toolDuration, toolErrors, toolInvocations } from "./metrics.js";
 import type { McpToolResponse } from "./response-formatter.js";
-import { getCurrentUserId, tracer } from "./telemetry.js";
+import { getCurrentUserHash, tracer } from "./telemetry.js";
 
 /** Whitelist of safe argument keys that can be logged without exposing PII. */
 const ARGUMENT_WHITELIST = new Set([
@@ -113,7 +113,7 @@ export function withTelemetry<TParams extends Record<string, unknown>>(
 
 		toolInvocations.add(1, { tool_name: context });
 
-		const userId = getCurrentUserId();
+		const userHash = getCurrentUserHash();
 		const safeArgs = extractSafeArgs(args);
 		const whitelistedKeys = Object.keys(safeArgs).map((key) =>
 			key.replace("mcp.tool.args.", ""),
@@ -127,7 +127,7 @@ export function withTelemetry<TParams extends Record<string, unknown>>(
 					"workflow.name": context,
 					"mcp.tool.args.key_count": argumentKeyCount,
 					"mcp.tool.args.keys": whitelistedKeys.join(","),
-					...(userId ? { "user.id": userId } : {}),
+					...(userHash ? { "user.hash": userHash } : {}),
 					...safeArgs,
 				},
 			},

src/utils/telemetry.test.ts

@@ -17,6 +17,7 @@ const testDoubles = vi.hoisted(() => ({
 	batchSpanProcessor: vi.fn(),
 	meterProvider: vi.fn(),
 	periodicExportingMetricReader: vi.fn(),
+	nodeTracerProviderOptions: undefined as unknown,
 }));
 
 vi.mock("@sentry/node", () => ({
@@ -63,6 +64,9 @@ vi.mock("@opentelemetry/sdk-trace-base", () => ({
 
 vi.mock("@opentelemetry/sdk-trace-node", () => {
 	class MockNodeTracerProvider {
+		constructor(options: unknown) {
+			testDoubles.nodeTracerProviderOptions = options;
+		}
 		register = testDoubles.register;
 	}
 	return { NodeTracerProvider: MockNodeTracerProvider };
@@ -151,4 +155,25 @@ describe("telemetry initialization", () => {
 		expect(mod.serviceName).toBe("hevy-mcp");
 		expect(mod.serviceVersion).toBe("dev");
 	});
+	it("adds the current user hash to every started span", async () => {
+		vi.resetModules();
+		const mod = await import("./telemetry.js");
+		mod.setCurrentUserHash("hash-123");
+		expect(mod.getCurrentUserHash()).toBe("hash-123");
+
+		const providerOptions = testDoubles.nodeTracerProviderOptions as {
+			spanProcessors: Array<{
+				onStart: (span: unknown, parentContext: unknown) => void;
+			}>;
+		};
+		const processor = providerOptions.spanProcessors[0];
+		if (!processor) {
+			throw new Error("Expected user hash span processor");
+		}
+
+		const setAttribute = vi.fn();
+		processor.onStart({ setAttribute }, {});
+
+		expect(setAttribute).toHaveBeenCalledWith("user.hash", "hash-123");
+	});
 });

src/utils/telemetry.ts

@@ -20,7 +20,11 @@ import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
 import { OTLPMetricExporter } from "@opentelemetry/exporter-metrics-otlp-http";
 import { resourceFromAttributes } from "@opentelemetry/resources";
 import { BatchSpanProcessor } from "@opentelemetry/sdk-trace-base";
-import type { SpanProcessor } from "@opentelemetry/sdk-trace";
+import type {
+	ReadableSpan,
+	Span,
+	SpanProcessor,
+} from "@opentelemetry/sdk-trace";
 import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
 import {
 	MeterProvider,
@@ -73,9 +77,28 @@ const sentryClient = Sentry.init({
 });
 
 // --- OpenTelemetry tracer provider (dual export) ---
-const spanProcessors: SpanProcessor[] = [new SentrySpanProcessor()];
+let currentUserHash: string | undefined;
 
-// Span processor 2: OTel Collector → Honeycomb (traces) — only if token is available
+class UserHashSpanProcessor implements SpanProcessor {
+	onStart(span: Span): void {
+		if (currentUserHash) {
+			span.setAttribute("user.hash", currentUserHash);
+		}
+	}
+
+	onEnd(_span: ReadableSpan): void {}
+
+	async forceFlush(): Promise<void> {}
+
+	async shutdown(): Promise<void> {}
+}
+
+const spanProcessors: SpanProcessor[] = [
+	new UserHashSpanProcessor(),
+	new SentrySpanProcessor(),
+];
+
+// OTel Collector → Honeycomb traces — only if token is available
 if (collectorToken) {
 	spanProcessors.push(
 		new BatchSpanProcessor(
@@ -144,12 +167,10 @@ export const serviceInfo: ServiceInfo = { name, version } as const;
 export { name as serviceName, version as serviceVersion };
 
 // --- User context for span attributes ---
-let currentUserId: string | undefined;
-
-export function setCurrentUserId(id: string): void {
-	currentUserId = id;
+export function setCurrentUserHash(hash: string): void {
+	currentUserHash = hash;
 }
 
-export function getCurrentUserId(): string | undefined {
-	return currentUserId;
+export function getCurrentUserHash(): string | undefined {
+	return currentUserHash;
 }