QVAC-13658 feat[api]: SDK Profiler

[opaninakuffo]

🎯 What problem does this PR solve?

• We did not have a end-to-end profiling surface across client RPC, server handling, and delegation paths.
• Profiling behavior was inconsistent across operations and lacked a clear precedence model for runtime vs per-call control.
• Delegated requests (consumer server -> provider server) did not expose timing visibility back to the originating client.

📝 How does it solve it?

• Adds a centralized profiler module with runtime API:
  • profiler.enable(...), profiler.disable(), profiler.exportJSON(), profiler.exportTable(), profiler.exportSummary().
• Implements deterministic precedence:
  • per-call override > runtime enablement > default disabled.
• Adds internal __profiling envelope propagation end-to-end.
• Instruments client RPC transport (unary + streaming).
• Instruments server request funnel.
• Instruments delegation transport and peer connection lifecycle.
• Adds operation-level profiling wrappers + metric extraction maps for handler-level stats (plugin/rag + related handlers).
• Finalizes mode/session behavior.

🧪 How was it tested?

• Focused unit tests added in:
  • packages/sdk/test/unit/profiler.test.ts
• Ran the full test suite (320 tests) with profiler enabled in summary mode. Captured 4,874 events across 450 RPC calls with full server breakdown, validating profiler overhead remains negligible during comprehensive test execution: Screenshot shows profiler output (partial) on consumer shutdown:

🔌 API Changes

import { profiler } from "@qvac/sdk";

// Runtime control
profiler.enable({
  mode: "verbose", // "summary" | "verbose"
  includeServerBreakdown: true,
});

// ... run operations ...

console.log(profiler.exportSummary());
console.log(profiler.exportTable());
console.log(profiler.exportJSON({ includeRecentEvents: true }));

profiler.disable();

// Per-call control
await embed(
  { modelId: "m1", text: "hello" },
  { profiling: { enabled: true } },
);

await completion(
  { modelId: "m1", history: [{ role: "user", content: "Hello" }] },
  { profiling: { enabled: false } },
);

// Additional client APIs now accept RPC options passthrough
await invokePlugin({ modelId: "m1", handler: "h", params: {} }, { profiling: { enabled: true } });
await ragSearch({ workspace: "default", query: "q" }, { profiling: { enabled: true } });
await transcribe({ modelId: "m1", audioChunk: "..." }, { profiling: { enabled: true } });
await translate({ modelId: "m1", text: "hello" }, { profiling: { enabled: true } });

---

📊 Metrics Catalog

Notes

• Duration metrics are in milliseconds (ms).
• Aggregated metric key format is op.phase when phase exists, otherwise just op.
• op is the operation name (e.g., loadModel, completionStream, unloadModel, pluginInvoke).

Aggregated Timing Metrics (exportTable())

Metric key pattern	Source	What it measures
rpc.connection	Client RPC transport	Time to establish the first RPC connection in the client lifecycle.
delegation.connection	Server delegation profiler	Time to establish a provider peer connection (recorded once per peer lifecycle).
op.request.zodValidation	Client RPC transport	Request schema validation time on the client before sending.
op.request.stringify	Client RPC transport; delegation transport	JSON serialization time for outbound request payload.
op.request.totalSerialization	Client RPC transport	request.zodValidation + request.stringify.
op.serverWait	Client RPC transport; delegation transport	Network/server wait from send to first full unary response receipt.
op.ttfb	Client stream transport; delegation stream transport	Time to first streamed chunk/token from send time.
op.streamDuration	Client stream transport; delegation stream transport	Duration from first streamed chunk to last streamed chunk.
op.response.jsonParse	Client RPC transport; delegation transport	JSON parse time for inbound response payload.
op.response.zodValidation	Client RPC transport	Response schema validation time on the client.
op.response.totalParsing	Client RPC transport	response.jsonParse + response.zodValidation.
op.totalClientTime	Client RPC transport	End-to-end client-observed duration for the operation.
op.clientOverhead	Client RPC transport	totalClientTime - server.totalServerTime when server breakdown is present.
op.server.request.jsonParse	Server breakdown (injected to client)	Server-side JSON parse time for the incoming request.
op.server.request.zodValidation	Server breakdown (injected to client)	Server-side request schema validation time.
op.server.handlerExecution	Server breakdown (injected to client)	Server-side handler execution time.
op.server.response.zodValidation	Server breakdown (injected to client)	Server-side response schema validation time.
op.server.response.stringify	Server breakdown (injected to client)	Server-side response serialization time.
op.server.totalServerTime	Server breakdown (injected to client)	Total server request lifecycle time (parse -> handler -> serialize).
op.delegation.connection	Delegation breakdown (injected to client)	Connection establishment time for delegated provider hop attached to unary response.
op.delegation.request.stringify	Delegation breakdown (injected to client)	Delegation request serialization time.
op.delegation.serverWait	Delegation breakdown (injected to client)	Wait time for delegated provider unary response.
op.delegation.response.jsonParse	Delegation breakdown (injected to client)	Delegated response JSON parse time.
op.delegation.totalDelegationTime	Delegation breakdown (injected to client)	End-to-end delegated hop time for unary flow.
op.delegated.request.jsonParse	Delegation profiler with provider server meta	Provider-server parse time, recorded under delegated.* prefix.
op.delegated.request.zodValidation	Delegation profiler with provider server meta	Provider-server request validation time.
op.delegated.handlerExecution	Delegation profiler with provider server meta	Provider-server handler execution time.
op.delegated.response.zodValidation	Delegation profiler with provider server meta	Provider-server response validation time.
op.delegated.response.stringify	Delegation profiler with provider server meta	Provider-server response stringify time.
op.delegated.totalServerTime	Delegation profiler with provider server meta	Provider-server total server lifecycle time.
op.totalDelegationTime	Server delegation transport	Delegation hop total time recorded by server-side delegation transport.
op.failed	Generic failure recorder	Duration from operation start until error capture point.
op (no phase, e.g., embed, rag)	Operation wrappers	Handler wall-clock execution duration (reply/stream wrapper scope).

Event Gauges and Counters (exportJSON().recentEvents / onRecord)

Metric field	Where emitted	What it measures
gauges.ttfb	Operation wrappers (stream handlers)	Time to first yielded chunk within wrapper scope.
gauges.timeToFirstToken	completionStream operation metrics	Model-reported TTFT from completion stats.
gauges.tokensPerSecond	completionStream operation metrics	Model-reported output throughput from completion stats.
gauges.cacheTokens	completionStream operation metrics	Model-reported cache token count.
gauges.processedTokens	translate operation metrics	Model-reported number of processed translation tokens.
gauges.processingTime	translate operation metrics	Model-reported translation processing time.
gauges.detectionTime	ocrStream operation metrics	OCR detection stage time from response stats.
gauges.recognitionTime	ocrStream operation metrics	OCR recognition stage time from response stats.
gauges.totalTime	ocrStream operation metrics	OCR total time from response stats.
gauges.processed	rag operation metrics	Number of processed items returned by RAG operation.
gauges.resultsCount	rag operation metrics	Number of results in RAG response.
count	Stream transports and wrappers	Chunk/token/event count captured for streaming flows.

Summary Rows (exportSummary())

Summary row	Derived from aggregates	What it represents
RPC Total	keys ending in .totalClientTime	Aggregate client-observed end-to-end RPC time across operations.
Handler	keys ending in .server.handlerExecution OR phaseless keys (e.g., embed)	Server-side handler execution times combined with operation-wrapper durations.
Model Load	load.totalTime or *.load.totalTime	Load timing roll-up if/when emitted by load metrics instrumentation.
Download	download.time or *.download.time	Download timing roll-up if/when emitted by download instrumentation.

[opaninakuffo]

/review

[github-actions]

Tier-based Approval Status

**PR Tier:** TIER1

**Current Status:** ✅ APPROVED

**Requirements:**
- 1 Team Member approval ✅ (1/1)
- 1 Team Lead OR Management approval ✅ (1/1)



---
*This comment is automatically updated when reviews change.*