Add optional OpenTelemetry traces, metrics and OTLP logs

README.md

@@ -204,13 +204,47 @@ DATABASE_URL=postgres://kca:password@localhost:5432/kca uv run aerich migrate --
 DATABASE_URL=postgres://kca:password@localhost:5432/kca uv run aerich upgrade
 ```
 
+## OpenTelemetry
+
+OpenTelemetry is optional and disabled by default. The Docker image includes
+the `otel` extra; for a non-image install run:
+
+```sh
+uv sync --package kca-app --extra otel
+```
+
+Enable export with:
+
+```sh
+OTEL_ENABLED=1
+OTEL_SERVICE_NAME=kca
+OTEL_EXPORTER_OTLP_ENDPOINT=http://collector:4318
+# Optional comma-separated "Name=Value" pairs:
+OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer token,X-Tenant=one"
+```
+
+The OTLP/HTTP endpoints are derived automatically (`/v1/traces`,
+`/v1/metrics`, `/v1/logs`). KCA exports:
+
+- HTTP server spans and metrics through `kaya-otel`, with W3C trace-context
+  propagation and health-check exclusion;
+- asyncpg and Redis client spans;
+- the `kca.active_sessions` gauge plus process/GC system metrics;
+- application logs through the OTLP log exporter (OpenTelemetry's own SDK
+  logs are filtered to avoid export loops);
+- `session.id` (truncated digest) and `user.id` span attributes for trace
+  correlation.
+
+`OTEL_EXCLUDED_PATHS`, `OTEL_METRIC_EXPORT_INTERVAL_MILLIS` and
+`OTEL_METRICS_POLL_INTERVAL_SECONDS` are documented in `server/.env.example`.
+
 ## Layout
 
 ```
 server/
   packages/kca-core/   # pure PKI domain (keys, names, extensions, certs, CSRs,
                        # CRLs, templates, imports/exports, .xdb, AES-GCM)
-  packages/kca-app/    # kaya app, config, Tortoise models, routes, static
+  packages/kca-app/    # kaya app, config, telemetry, Tortoise models, routes, static
   migrations/          # aerich schema history
   tests/               # app integration suite
   dev/mockoauth/       # dev OIDC provider image + test users