Telemetry (OpenTelemetry)

magus can export metrics and traces to any OTLP collector you run. Telemetry is OFF by default: there is no magus-operated backend. The collector is yours, and magus connects only to the endpoint you configure.

Instrument definitions live in internal/observability/otlp/provider.go and internal/observability/otlp/families.go; the interface every producer records through is internal/observability/provider.go, and config is in internal/config/config.go.

Enabling

In magus.yaml:

telemetry:
  enabled: true
  endpoint: "localhost:4318" # host:port, no scheme
  protocol: "http" # "grpc" (default) or "http"
  insecure: true # plaintext for local collectors
  service_name: "magus" # resource attribute service.name
  sample_ratio: 1.0 # head-based trace sampling, [0,1]
  headers: # static headers on every OTLP request
    x-api-key: "..."

Or via the environment:

Export details. magus pushes metrics over OTLP on a periodic reader every 30s. It batches traces and samples them head-based by sample_ratio (1.0 = every trace). Metrics are unsampled: every recorded point is exported.

Resource attributes

Every metric and span carries these resource attributes:

Metrics

Cache (local)

Low-cardinality aggregate view of the on-disk content-addressed cache; no per-project attribute.

magus.cache.duration says what a hit cost; magus.cache.saved.duration says what it saved, one observation per hit. Its sum is the wall-clock the cache has given back, and its distribution says which hits are worth having. An entry written before the manifest carried a duration reports nothing rather than zero, so the total understates and never overstates - the same measured-not-modeled rule the cache_saved_ms field in magus status follows.

Remote cache

The shared backend (S3, GitHub Actions, ...), exported only when one is wired via magus\cache.remote(...). These mirror the local-cache vocabulary under a .remote prefix so a remote hit is never folded into the local counters: a remote hit is still a local miss, because the remote fetch only runs after the local store misses. Instrumentation wraps the backend interface, so it applies to every backend (including ones you write) with no backend changes.

outcome ∈ {hit, miss, stored, error}; stored is a successful put. Remote hit-rate is hits / (hits + misses). Put success is the magus.cache.remote.duration count for op=put minus magus.cache.remote.errors for op=put.

Graph

strategy is present only when the query reports one. op=build is the full graph build.

Target runs

Per-project, per-spell. magus.project has unbounded cardinality; see Cardinality.

outcome ∈ {success, error} · cache.hit ∈ {true, false} · one row is emitted per resolved spell per project.

Concurrency pool

magus.pool.slots.running is an up-down counter: it rises as targets acquire slots and falls as they release, so its value reads as the live running depth.

Agent surface

Leases, attention requests and paired review: the three places a fleet of agents and the people working with them meet. Every producer here runs in the daemon, which is what makes them collectable at all - a magus CLI invocation is a one-shot process, and the CLI halves of these same surfaces (raising an attention request, the agent guard grading a write) reach the activity trail instead. Read each row for what it counts, not for the whole surface.

verdict on registrations is match, revision-match, diverged or unknown; a rising diverged share says a fleet's workers are building on trees their orchestrator never handed them. verdict on publishes is comment, approve or request_changes, and it is the verdict that landed: downgraded=true means the asserting verdict the person asked for was refused (a review cannot approve a change its own credential opened), which is invisible in the forge's record and known only here.

magus.attention.disposition.duration counts the disposals made through the console route. magus session dispose closes a request from a one-shot process with no collector, so those are absent - the instrument is a wait-time distribution rather than a queue depth, which would read as the whole queue and be neither. severity is re-read from the store and clamped to the declared tiers (info, notice, warning, critical, plus unset), so a record written by another build can never mint a series.

Metrics observe, they never gate. magus.review.remarks is attributed by author because that says which door a remark came through, and both doors write to one store. magus.review.publishes is deliberately not: how a change was judged, split by who wrote it, is the first half of a threshold that blocks work by author kind, and magus does not build the instrument that invites one.

Traces (spans)

Spans are sampled head-based by telemetry.sample_ratio.

The magus.cache.hash / replay / snapshot spans break a target's latency down by phase: hashing vs. building vs. I/O. The remote get/put spans put a network fetch or upload inline in the build trace with its own latency, so a slow remote round-trip is visible instead of opaque time inside the target.

Cardinality

magus.target.runs and magus.target.duration include magus.project, which is unbounded in large monorepos. If your setup has thousands of projects, drop or relabel the attribute at the collector:

# OpenTelemetry Collector - attributes processor
processors:
  attributes/drop_project:
    actions:
      - key: magus.project
        action: delete

Alternatively, use an SDK View at startup to drop the attribute before it leaves the process. Three other instruments carry a workspace-sized attribute and the same recipe applies: magus.sandbox.checks and magus.sandbox.env.dropped carry magus.project, and magus.buzz.spell.resolve.duration and the magus.buzz.spell.builtins.* family carry spell, a workspace-authored name. Every other metric omits them. The remote get/put spans carry magus.project, but spans are sampled and not aggregated into time series, so they don't create cardinality the way a metric attribute would.