Skip to content

Observability

Partial

Shared telemetry and redaction libraries exist. Deployed SLOs, alert delivery and complete admin summaries are not established.

Code and tests

Operational telemetry explains failures. Durable product records explain usage, access and accounting decisions. Telemetry is not the billing or audit source of truth.

flowchart LR
  Services["App, APIs and workers"] --> Logs["Structured JSON logs"]
  Services --> Traces["Correlated traces"]
  Services --> Records[("Usage, audit and security records")]
  Logs --> Backend["Configured telemetry backend"]
  Traces --> Backend
  Records --> Admin["Authorized admin views"]
SignalOwner and purpose
Logs and tracesConfigured backend; request failures, dependencies and latency
Provider receiptsProduct PostgreSQL; usage, reservations, estimates and settlement
Audit and security eventsProduct PostgreSQL; durable decisions and enforcement evidence
Queue, lease and cleanup stateOwning database; operational diagnosis

Use @kesita/observability in Node and packages/observability-go in Go. Keep structured logging active when trace export is disabled. Propagate request IDs and W3C trace context across supported internal calls.

Never log credentials, private document bodies, legal queries, prompts or completions by default. Use opaque IDs, route templates, bounded reason codes, counts and durations. Persist confidential execution evidence only in protected product storage with retention controls.

Record security/audit write failures explicitly. Avoid unbounded metric labels and per-stage info logging in hot paths. Product analytics require their own purpose and consent policy.

Liveness checks the process without dependency I/O. Readiness checks required dependencies and worker coordination. Do not infer provider health or successful job execution from a recent worker heartbeat.

Admin operations read timestamped, scoped summaries through service-owned capabilities. Legal summaries come through Legal Core, not direct product SQL. Unknown or stale observations remain explicit.

SLO definitions and alert rules require provisioned exporters, backends and delivery routes before they become operational guarantees. The checked-in observability/slos.yaml is a specification, not proof of deployed alerts.

Use logger-only mode for ordinary development. Set KESITA_TELEMETRY_ENABLED=false to disable trace export while keeping logs. Node uses APPLICATIONINSIGHTS_CONNECTION_STRING; Go uses OTEL_EXPORTER_OTLP_ENDPOINT. Setting an OTLP endpoint alone does not configure the Node initializer.

See configuration, deployment and worker recovery.

packages/observability/src/redact.ts and redact.test.ts enforce shared redaction behavior; propagation.test.ts checks context propagation. packages/observability-go/otel_test.go covers Go initialization. Redaction is a defense against accidental disclosure, not permission to send arbitrary document bodies to a logger.

services/legal-core-api/internal/handlers/legal_core_server.go and the health Hermit suite distinguish liveness from dependency readiness. Deployed SLOs, alert delivery and complete administrative summaries remain targets until their infrastructure and acceptance checks exist.