@construct/observability

Minimal analytics + essential error logging for Construct platform workers.

API

import { track, log } from '@construct/observability';

track(env, {
  event: 'llm_call',
  trigger: 'user',
  userId,
  model: 'gpt-4o',
  costUsd: 0.002,
});

log(env, {
  kind: 'log',
  level: 'error',
  source: 'agent.loop',
  message: 'Turn crashed',
  error,
  userId,
  sessionKey,
  context: { iteration: 3 },
});

Both functions are fire-and-forget and never throw. Messages are sent to ANALYTICS_QUEUE with envelope kind: 'analytics' | 'log'.

Platform producers

Pin the same commit across all workers (currently #d3607bb). Each producer needs a wrangler queue binding and a stable SERVICE_NAME:

Worker	SERVICE_NAME	Queue binding
construct-api-staging	construct-api-staging	ANALYTICS_QUEUE → construct-analytics
construct-api-production	construct-api-production	same
construct-app-registry	construct-app-registry	same
construct-memory	construct-memory	same

Observer consumes construct-analytics and indexes by service. Bump the git pin in construct/worker, app-registry/worker, and memory together when upgrading.

Logging policy

• log(error|warn) — actionable failures only (5xx, turn crash, hard tool/LLM failure, billing/webhook errors)
• track() — metrics (llm_call, tool_call, agent_turn, incident, user_activity, system_event)
• Do not duplicate full stack traces in analytics payloads — use log() for stacks