magus v0.3.0 is out. See what's new
¶ View markdown source · ✎ Suggest an edit
6 min read

MetricsService

MetricsService serves the derived dashboard metrics. Served over ConnectRPC, so one endpoint speaks Connect (browser-native HTTP), gRPC, and gRPC-Web from this one contract.

Package magus.metrics.v1, defined in proto/magus/metrics/v1/metrics.proto. Part of the daemon API.

Methods

GetMetrics

GetMetrics returns the current derived snapshot.

POST /magus.metrics.v1.MetricsService/GetMetrics - unary.

Takes GetMetricsRequest, returns GetMetricsResponse.

StreamMetrics

StreamMetrics pushes the rolling history first (one Backfill), then a fresh Snapshot on each tick, so the dashboard's charts and utilization grid start populated and stay live.

POST /magus.metrics.v1.MetricsService/StreamMetrics - server streaming.

Takes StreamMetricsRequest, returns StreamMetricsResponse.

Messages

Backfill

Backfill is the ring-buffer history the daemon sends once, right after a dashboard connects, so the utilization grid and cache-rate trend start populated instead of empty.

Field Type # Description
samples repeated Sample 1 oldest-first

Buzz

Buzz rolls up the magus.buzz.* families: script exec/compile latency, the native-boundary host-call family, session-pool health, import and spell resolution, and VM-level counters.

Field Type # Description
exec_count int64 1
exec_p50 double 2 seconds
exec_p95 double 3 seconds
compile_count int64 4
compile_p50 double 5 seconds
compile_p95 double 6 seconds
host_call_count int64 7
host_call_p50 double 8 seconds
host_call_p95 double 9 seconds
session_pool_reuse int64 10 acquires served from an idle session
session_pool_idle int64 11 current idle sessions (gauge)
session_pool_evictions int64 12
session_warm_p50 double 13 seconds
session_warm_p95 double 14 seconds
import_count int64 15
import_p50 double 16 seconds
import_p95 double 17 seconds
spell_resolve_count int64 18
spell_resolve_p50 double 19 seconds
spell_resolve_p95 double 20 seconds
jit_runs int64 21
vm_faults int64 22

GetMetricsRequest

No fields.

GetMetricsResponse

Field Type # Description
snapshot Snapshot 1

Latency

Latency is an operation-family rollup: how many happened and how long they took. The percentiles are interpolated from the OTel histogram's buckets server-side, so the dashboard never re-derives them from raw buckets.

Field Type # Description
count int64 1 number of observations (the operation count)
p50 double 2 seconds
p95 double 3 seconds
p99 double 4 seconds
max double 5 seconds (upper bound of the largest populated bucket)
sum double 6 total seconds observed (for averages / throughput)

MCPToolStat

MCPToolStat is one per-tool rollup of the magus.mcp.tool.* families: call/error tallies, input/output payload sizes, and call duration percentiles.

Field Type # Description
tool string 1
calls int64 2
errors int64 3
input_p50 double 4 bytes
input_p95 double 5 bytes
input_total int64 6 total input bytes observed
output_p50 double 7 bytes
output_p95 double 8 bytes
output_total int64 9 total output bytes observed
duration_p50 double 10 seconds
duration_p95 double 11 seconds

Remote

Remote is the remote-cache instrument family: outcome tallies plus transfer latency and volume.

Field Type # Description
hits int64 1
misses int64 2
errors int64 3
duration_p50 double 4 seconds
duration_p95 double 5 seconds
io_count int64 6 number of get/put operations observed
bytes_total int64 7 total bytes transferred (sum of the io.size histogram)

Sample

Sample is one point in the rolling utilization/activity history. The daemon appends one per tick; the dashboard diffs adjacent samples for per-interval rates and colors one grid square per sample by utilization.

Field Type # Description
at Timestamp 1
running int32 2 pool slots running at this tick
capacity int32 3 pool capacity (0 = unlimited)
queued int32 4 tasks queued for a slot
cache_hits int64 5 cumulative; diff adjacent samples for a hit rate
cache_misses int64 6 cumulative
target_runs int64 7 cumulative target executions

Sandbox

Sandbox rolls up the magus.sandbox.* filesystem families: apply latency, the rule counts a sandbox was built from, allow/deny check tallies, and dropped environment variables.

Field Type # Description
apply_p50 double 1 seconds
apply_p95 double 2 seconds
rules_read int64 3
rules_write int64 4
rules_exec int64 5
env_rules int64 6 exact + glob env rules
checks_allow int64 7
checks_deny int64 8
env_dropped int64 9

Snapshot

Snapshot is the derived-metrics view at one instant: each OTel instrument family aggregated for the dashboard.

Field Type # Description
captured_at Timestamp 1
target Latency 2 magus.target.duration + magus.target.runs
cache Latency 3 cache is the local Cache.Run family (magus.cache.duration + magus.cache.{hits,misses,errors}). Named "cache" (not "cache_op") because "op" collides with the Operation glossary term and this family measures a Cache.Run, not a resolved op.
pool_wait Latency 4 magus.pool.wait.duration
graph_query Latency 5 magus.graph.query.duration + magus.graph.queries
remote Remote 6 magus.cache.remote.*
target_stats repeated TargetStat 7 per-target rollup of magus.target.{duration,runs}
mcp_tools repeated MCPToolStat 8 per-tool rollup of magus.mcp.tool.*
buzz Buzz 9 magus.buzz.* families
sandbox Sandbox 10 magus.sandbox.* filesystem families

StreamMetricsRequest

No fields.

StreamMetricsResponse

Field Type # Description
backfill Backfill 1 one of of
snapshot Snapshot 2 one of of

TargetStat

TargetStat is one per-target rollup: how often a (project, target, spell) ran, its latency percentiles, cache hit-rate, and success/error split. Grouped from the magus.target.duration histogram's per-(project,spell,target,outcome,cache.hit) data points.

Field Type # Description
project string 1 magus.project attribute
target string 2 magus.target attribute
spell string 3 magus.spell attribute ("" when the project declares none)
count int64 4 total executions (including cache replays)
p50 double 5 seconds
p95 double 6 seconds
p99 double 7 seconds
cache_hit_rate double 8 [0,1]; fraction of runs served from cache
success int64 9 runs with outcome=success
errors int64 10 runs with outcome=error
ReferencePages in this section. StatusServiceStatusService serves the snapshot, and streams it for a live dashboard. The CLI in practiceThe magus subcommands you actually reach for, grouped by the question you are asking, with the quirks that are not obvious from the help text. SpellsA spell is a library of tool-native ops (go-build, cargo-clippy, eslint) plus cache metadata that your magusfile composes into runnable targets.
apiprotoconnectgrpcmetricsservice
Last updated (38e9171e)
Glossary

Project

A directory magus recognizes as a unit of work (it has a magusfile); the unit of caching, scheduling, and dependency tracking. See workspace.

Target

A named operation (build, test, ...) you invoke with magus run <target>; it may compose a spell's tool-native operations and depend on other targets. See targets.

Operation

A single tool-native command a target composes; the middle of the work hierarchy (Spell to Operation to Target). See operations.

Spell

A language/runtime adapter (e.g. go, md) that maps generic targets onto a toolchain's real commands. See spells.

Buzz

The language magusfiles are written in (the .buzz engine). See engines.

Cache

The content-addressed store magus consults before running a target, so unchanged work is skipped. See cache.

Sandbox

The restricted filesystem and environment a target runs in, so builds stay reproducible and side-effect-free. See sandbox.

Service

A long-running or shared process magus manages across runs, distinct from a one-shot target. See services.

Daemon

The background magus host that owns shared state such as services and the warm knowledge graph. See daemon.

CI

An ordinary magusfile-defined target you compose yourself with magus\needs - magus does not hardcode its stages. Magus.RunCI treats it specially only in that it strips the rw charm, it is the anchor magus affected ci keys off, and a selected scope with no project declaring it is a load error rather than a silent no-op. See targets.

Pool

The concurrency pool: the shared set of slots that caps how many targets run in parallel on one machine. Its capacity defaults to MAGUS_CONCURRENCY, then 4 on GitHub-hosted runners, then min(NumCPU, 8); magus status and the dashboard report it live. See daemon.

Slot

One unit of the pool's capacity. A target acquires the slots it needs to run (most take one) and releases them when it finishes; the pool tracks capacity (total slots), running (acquired), and queued (blocked). See daemon.

Queued

A target that wants a slot while the pool is full; it blocks first-in-first-out until a slot frees. The dashboard colors a sample with queued > 0 accordingly. See daemon.

Snapshot

A point-in-time view of live state - the pool's occupancy or a tick of exported metrics - as opposed to accumulated history. See daemon.

Backfill

The recent history the daemon replays to a dashboard on connect, so its charts start populated instead of empty. It is served from a bounded ring buffer of the last few hundred samples. See daemon.

Latency

How long an operation takes. magus records latency as OpenTelemetry histograms per family - target execution, cache op, pool wait, and graph query - and reports each as a count, sum, and percentiles. See telemetry.

Percentile

A latency value at a given rank, interpolated from a histogram's buckets: p50 is the median, p95 and p99 are the tail that most latency budgets care about. See telemetry.

Health

The at-a-glance daemon state derived from the pool: healthy when the pool is reporting, degraded when it reports an error, down when there is no pool. The dashboard color-codes each state. See daemon.

Trend

An insight lens: the recent half of the window against the earlier half. A positive delta is a rising hotspot; a negative one is cooling. See insight.

Conventions

This page uses none of the site's convention markers. The full set is on the conventions page.