Observability — logs and metrics

DioscHub emits three things you monitor a running deployment with: structured logs to stdout, a Prometheus metrics endpoint, and health probes for your load balancer. This page covers each, and is clear about where the responsibility for sensitive data in your telemetry sits — with you.

Metrics

DioscHub exposes Prometheus metrics at /api/metrics in the standard text exposition format. Metrics are event-driven: they are incremented as sessions start, tools run, and connections open, not sampled on a timer.

The families it exposes:

Area	Metrics
Sessions	diosc_sessions_created_total, diosc_sessions_completed_total, diosc_sessions_active
MCP tools	diosc_mcp_tool_calls_total, diosc_mcp_tool_duration_seconds, diosc_mcp_tool_retries_total, diosc_mcp_circuit_breaker_trips_total, diosc_mcp_auth_errors_total
Knowledge retrieval	diosc_rag_indexing_total, diosc_rag_chunks_indexed_total, diosc_rag_tokens_indexed_total
WebSocket	diosc_ws_connections_active, diosc_ws_disconnections_total, diosc_ws_rate_limited_total
Guardrails	diosc_guardrail_input_blocked_total, diosc_guardrail_output_blocked_total
Process	diosc_process_uptime_seconds, diosc_process_heap_bytes, diosc_process_rss_bytes

Danger

The metrics endpoint is unauthenticated. Put /api/metrics behind your firewall or network policy so it is reachable only by your monitoring, never the public internet. It is operational telemetry, not a user-facing surface. See Production hardening.

There is also an authenticated admin metrics endpoint, /api/admin/metrics/realtime, that returns a JSON snapshot for the admin portal. It requires an admin session with analytics permission, so it is safe to leave reachable — but it is for the portal, not for scraping.

Health probes

Three endpoints back load-balancer and orchestrator checks:

• /api/health — overall health, including a database ping.
• /api/health/ready — readiness, also database-backed; use it to gate traffic.
• /api/health/live — a static liveness response; use it to decide whether to restart the container.

Logs

DioscHub logs to stdout, one structured line per event. In production the format is JSON; each line carries a context field naming the component and the event’s own fields. Ship stdout to your log aggregator — that is the primary sink.

You tune the log stream with environment variables:

Variable	Effect
LOG_LEVEL	Verbosity (info in production, debug in development).
LOG_FORMAT	json or pretty.
LOG_FILES_ENABLED, LOG_DIR	Also write rotating log files to a directory.

In production, file logging is on by default; set LOG_FILES_ENABLED=false to turn it off. When it is on, DioscHub writes rotating files (combined, error, audit, and conversation streams) under LOG_DIR — that directory is inside the container, so mount a volume if you want those files to survive a restart. For most deployments, shipping stdout to an aggregator is what you rely on.

What securing your telemetry leaves to you

DioscHub does not scrub its operational logs for you. Beyond a narrow denylist applied to conversation and tool-payload logging, the general application log stream is written as-is. Treat the log destination as sensitive, control verbosity with LOG_LEVEL, and apply redaction at your aggregator if your compliance posture requires it.

Auth credentials are a deliberate exception: by design they stay out of the log path, the same way BYOA keeps them out of the model’s context. That is the intent the code is built around — it is not a substitute for securing the log sink itself, which remains yours to protect.