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.

This page is the complete reference for everything magus emits. Instrument definitions live in internal/observability/provider.go; config 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.

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.

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. Every other metric intentionally omits magus.project. 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.