Observability

GuideKit ships client-side pipeline telemetry so you can understand:

Latency: which stages are slow (DOM scan vs LLM vs validation)
Cost signals: token usage metadata attached to the LLM stage
Failures: correlate stage timing with EventBus errors and server proxy logs

What gets recorded

Each user message runs the v2 pipeline stages:

scan → enrich → retrieve → context → cognize → llm → validate → render

For each stage, GuideKit records one span with:

name: stable span name (example: guidekit.pipeline.llm)
stage: pipeline stage id
startTimeEpochMs / endTimeEpochMs: wall-clock timestamps for log correlation
durationMs: monotonic duration in milliseconds
attributes: stage metadata (primitives only)

In development, enable the DevTools panel and open the Telemetry tab:


import { GuideKitDevTools } from '@guidekit/react/devtools';
 
{process.env.NODE_ENV === 'development' && <GuideKitDevTools />}

The Telemetry tab shows stage timings and provides Copy JSON for sharing or analysis.

If you own a custom UI, you can read the last message spans from the core instance:


const spans = core.getTelemetrySpans();

This returns an array of exported spans with epoch timestamps and attributes.

GuideKit guarantees these attribute keys when applicable:

stage: pipeline stage id
conversationId: unique per user message
totalTokens: total tokens used for the completed message (attached as stages complete)
toolCallsExecuted: number of executed tool calls for the message
rounds: LLM/tool rounds performed

Additional attributes may be added over time, but existing keys are stable.

Track these signals in contract and live E2E suites when rolling out to production:

Metric	Contract target	Live target
Claim grounding (hallucination guard clean)	≥ 90%	≥ 85%
Highlight accuracy on plain pages	≥ 85%	≥ 85%
Tool success (`highlight`, `scroll`, `readPageContent`)	≥ 95%	≥ 90%
Prompt tokens per turn (after PageMemory)	−40% vs full prompt	−40%

Bus events for context and grounding:

context:memory-rebuild — PageMemory rebuilt after route or hash change
context:delta — incremental TurnDelta sent on subsequent turns
element:resolve — semantic ref resolved to selector (confidence, reason)
action:confirmation-required — dangerous click blocked pending user confirmation
validation:corrected — high-severity hallucination issues appended to response

Use DevTools Events or window.__guidekitTest in the example app to capture these during E2E debugging.

Reproduce the slow or failed message in dev with options={{ debug: true }}.
Open GuideKit DevTools → Telemetry and note the slowest stage (llm vs scan vs validate).
Check Events for error, auth:token-refreshed, or validation:complete.
Correlate conversationId and startTimeEpochMs with server proxy logs.

For proxy/auth failures (401, 403, 429), see Troubleshooting.