Observability
Shared telemetry and redaction libraries exist. Deployed SLOs, alert delivery and complete admin summaries are not established.
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"]
Signal ownership
Section titled “Signal ownership”| Signal | Owner and purpose |
|---|---|
| Logs and traces | Configured backend; request failures, dependencies and latency |
| Provider receipts | Product PostgreSQL; usage, reservations, estimates and settlement |
| Audit and security events | Product PostgreSQL; durable decisions and enforcement evidence |
| Queue, lease and cleanup state | Owning 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.
Privacy
Section titled “Privacy”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.
Health and operations
Section titled “Health and operations”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.
Local telemetry
Section titled “Local telemetry”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.
Enforcement and targets
Section titled “Enforcement and targets”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.