> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cyberun.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Observability

> How the Cyberun platform exposes logs, traces, and (in development) metrics for operators.

A Cyberun deployment exposes observability through standard
mechanisms operators are already running — structured logs and
OpenTelemetry traces today, a public metrics catalog and audit-log
shipping in development.

## Logs

Every cloud-side component (API server, gateway, license service)
emits structured logs. Two settings control the output:

| Key             | Values                           | Notes                                                      |
| --------------- | -------------------------------- | ---------------------------------------------------------- |
| `logger.level`  | `debug`, `info`, `warn`, `error` | Default `info`. Set per environment.                       |
| `logger.format` | `text`, `json`                   | Default `text` for dev; `json` for production aggregators. |

Environment overrides follow the standard `CYBERUN_<SECTION>_<KEY>`
mapping — `CYBERUN_LOGGER_LEVEL`, `CYBERUN_LOGGER_FORMAT`.

### Structured fields

Logs use these consistent fields where applicable. An aggregator
can index on any of them:

* `team_id` — the team scope of the request, when team-scoped.
* `user_id` — the requesting user, on user-initiated actions.
* `task_id`, `agent_id`, `workflow_id` — resource references.
* `credential_kind` — `integration`, `agent`, or `device`; never the credential value.
* `feature` — the license feature requirement, when a request is
  rejected by feature gating.
* `error` — the serialized error chain.

Credential values, JWTs, refresh tokens, license material, webhook
signing secrets, and OAuth client secrets are never logged.

### Log sources

| Source            | Component                              | Useful for                                                 |
| ----------------- | -------------------------------------- | ---------------------------------------------------------- |
| HTTP request log  | API server (HTTP middleware)           | Latency, status, route timing per request.                 |
| Gateway event log | Agent gateway                          | Agent connect/disconnect, task dispatch, tunnel lifecycle. |
| Agent process log | Per-agent process + runtime subprocess | Task execution detail; ComfyUI / Nerfstudio stdout.        |
| Repository log    | DB layer                               | Query timing on slow / failing paths.                      |
| License log       | License service + license middleware   | License loads, refreshes, gate rejections.                 |

## Traces (OpenTelemetry)

OTLP export is built in and off by default. Enable it per
deployment:

| Key                       | Default          | Notes                                                      |
| ------------------------- | ---------------- | ---------------------------------------------------------- |
| `telemetry.enabled`       | `false`          | Turn on for production.                                    |
| `telemetry.service_name`  | `cyberun`        | Override per process when collecting multi-service traces. |
| `telemetry.otlp_endpoint` | `localhost:4317` | Your collector address.                                    |
| `telemetry.otlp_insecure` | `true` (dev)     | Set `false` in production; collector should terminate TLS. |
| `telemetry.sample_ratio`  | `1.0`            | Lower in production if request volume is high.             |

When enabled, the API server, gateway, and agent emit spans for
HTTP request handling, task dispatch, tunnel lifecycle, and
runtime invocations. Point the endpoint at any OTLP-compatible
collector (Jaeger, Tempo, Honeycomb, Datadog, Lightstep, etc.).

## Metrics

A first-class Prometheus / OpenMetrics endpoint with documented
metric names, labels, and recommended alerts is in development.
Until that ships, operators typically derive operational signals
from:

* The HTTP request log's status and latency fields (aggregator
  side, e.g. Loki / OpenSearch).
* The OTLP trace data (collector side).
* The license-validator's renewal events.

If you need explicit metric points for a specific monitoring
target before the formal endpoint lands, reach out at
[sales@cyberun.cloud](mailto:sales@cyberun.cloud) — we can advise on the
interim hooks already exposed.

## Streamed task events

Task progress is published to the internal event bus (`task.*`
events) that the API server forwards to clients in two shapes:

* **HTTP Server-Sent Events** at `GET /api/v1/r/tasks/{taskId}/events`
  — the canonical wire format clients subscribe to.
* **MCP `notifications/progress`** events through the
  `stream_task_events` tool (Cloud MCP).

Subscribing your own backend to the event bus (stream-consumer
style) is an operator concern; the pattern is in development as
part of the public deployment guide. Today, custom subscribers
are partner-channel.

## Healthchecks

Each cloud-side process exposes a basic liveness endpoint. The
canonical paths, expected payloads, and alerting recommendations
land with the public deployment guide. Treat them as standard HTTP
`200`-or-not for now; a formal healthcheck spec is in development.

## Audit logging

Access decisions (sign-in, credential issuance, role changes,
license-gated rejections) appear in the structured log stream
with the field set above. A dedicated audit-log destination
(separate sink, separate retention, tamper-evident) is in
development for compliance-driven deployments.

## See also

* [Architecture](/platform/architecture) — components that emit
  the signals above.
* [Requirements](/platform/requirements) — what the dependencies
  contribute to observability (DB query logs, message-bus retention).
* [License administration](/platform/license) — license events
  surface in the same log stream as everything else.