Adopt a single standard for all observability code:
1) Be policy-compliant and opt-out safe
- Prefer typed helper functions for telemetry events (fixed event names and fixed payload shapes).
- Never rely on raw event strings outside the allowed scopes.
- Telemetry capture must be a no-op when the adapter/host telemetry is disabled, and must never throw.
2) Ensure attribution is correct (per-turn, per-retry)
- Reset attribution fields at the start of each turn (or at the correct lifecycle boundary) to prevent stale causes (e.g., finishReason) leaking into later failures.
- Classify failure reasons using dedicated dimensions so distinct causes aren’t conflated into one bucket.
3) Keep metrics specific and non-inflating
- Don’t emit a “timeout” (or similar) reason when the code path is “any ask failure”.
- Avoid double counting by using the central instrumentation pipeline only once.
4) Preserve trace/span lifecycle ordering
- For streaming/tracing, record errors/exception details before the relevant spans end; ensure generation spans receive the correct status/exception.
5) Avoid false samples in observations
- If you start an observation timer, cancel it on early failures (e.g., spawn/connect errors) so you don’t report synthetic “ran for N seconds” samples.
6) Keep observability from mutating core behavior
- Observability hooks must attach telemetry and instrumentation, but must not rewrite bootstrap identity/session inputs that core uses to decide resume vs new session.
Practical pattern (safe helper + fixed payload shape)
// telemetry helpers: fixed catalog event + fixed properties; never throws
export function capturePendingPromptsDiscarded(
telemetry: ITelemetryService | undefined,
details: { sessionId: string; count: number; reason: 'queue_abort' | 'session_teardown' },
): void {
if (!telemetry?.isEnabled()) return;
try {
telemetry.capture({
event: CORE_TELEMETRY_EVENTS.SESSION.PENDING_PROMPTS_DISCARDED,
properties: { ...details },
});
} catch {
// observability must not break execution
}
}
Checklist for PRs touching observability