Signals and metrics catalog

Monitor publishes 45 platform instruments into the Agent’s Metra engine: gauges for observed state and cumulative monotonic sums for query workload and consumption. This reference maps those native descriptors to the exact current Prometheus names.

Successful observations create samples. A failed, denied, or missing collection does not create a zero sample. Rule states and Timeline events are separate operational evidence, not additional samples that can be assumed to exist in every metric query.

Optional collector instruments use scope iclens.resources.v1 and protected origin infrastructure. They add snapshot count and latest age, subnet registry version, node proposals/failures, and exact Reserve health. Snapshot age becomes stale when no snapshots remain. Subnet labels use subnet_id; node counters also use node_id. Reserve and snapshot instruments use canister_id.

Native descriptor	PromQL name	Meaning
iclens.canister.snapshot_count	iclens_canister_snapshot_count	Current snapshot count
iclens.canister.latest_snapshot_age	iclens_canister_latest_snapshot_age_seconds	Age of the most recent snapshot
iclens.subnet.registry_version	iclens_subnet_registry_version	Observed registry version
iclens.node.blocks_proposed	iclens_node_blocks_proposed_total	Sparse daily cumulative proposals
iclens.node.block_failures	iclens_node_block_failures_total	Sparse daily cumulative failed proposals
iclens.reserve.balance	iclens_reserve_balance_cycles	Explained reserve checkpoint
iclens.reserve.reserved	iclens_reserve_reserved_cycles	Unresolved admitted principal plus fee
iclens.reserve.available	iclens_reserve_available_cycles	Explained balance less reservations, zero under containment
iclens.reserve.incident	iclens_reserve_incident	Open reserve incident: 1, otherwise 0
iclens.reserve.evidence_age	iclens_reserve_evidence_age_seconds	Age of the last successful reserve balance check
iclens.reserve.delivered	iclens_reserve_delivered_cycles_total	Pruning-independent confirmed delivered cycles
iclens.reserve.network_fee	iclens_reserve_network_fee_cycles_total	Pruning-independent proved network fees

Identity and labels

A descriptor includes name, description, unit, point kind, temporality, monotonicity, Resource, InstrumentationScope, and metadata. Protected host attributes and point attributes are also part of metric identity.

Platform instruments use scope iclens.platform.v1, protected origin monitor, and the observed principal in point attribute canister_id.

Native attribute origin	Prometheus label form
Point	Sanitized attribute key, such as canister_id
Resource	resource_ plus sanitized key
Instrumentation scope	scope_ plus sanitized key
Protected host	metra_protected_ plus sanitized key

For example, protected iclens.origin projects to metra_protected_iclens_origin. A resource label with the same underlying key is a different identity field and does not confer protected provenance.

Projection sanitizes the metric name, appends a unit suffix when the unit is not empty or 1, and appends _total for a monotonic Sum when needed. Projection collisions reject explicitly. Discover the actual name rather than guessing it from a display label.

Cycles and freezing

All instruments in this table are gauges.

Native descriptor	PromQL name	Unit / interpretation
iclens.canister.balance	iclens_canister_balance_cycles	cycles; observed canister balance
iclens.canister.reserved	iclens_canister_reserved_cycles	cycles; reserved balance
iclens.canister.reserved_cycles_limit	iclens_canister_reserved_cycles_limit_cycles	cycles; configured reserve limit
iclens.canister.idle_burn	iclens_canister_idle_burn_cycles_per_day	cycles/day; idle burn
iclens.canister.estimated_freeze	iclens_canister_estimated_freeze_seconds	seconds; estimated balance exhaustion at idle burn
iclens.canister.freezing_threshold	iclens_canister_freezing_threshold_seconds	seconds; configured threshold

The estimated balance coverage is based on idle burn, not a guarantee of future lifetime under changing workload. The canister’s balance is distinct from the Agent Reserve ledger balance.

Memory, artifacts, and limits

These gauges use the native unit By (bytes).

Native descriptor	PromQL name	Meaning
iclens.canister.memory	iclens_canister_memory_bytes	Aggregate canister memory
iclens.canister.memory.wasm	iclens_canister_memory_wasm_bytes	Wasm memory
iclens.canister.memory.stable	iclens_canister_memory_stable_bytes	Stable memory
iclens.canister.memory.global	iclens_canister_memory_global_bytes	Global memory
iclens.canister.memory.binary	iclens_canister_memory_binary_bytes	Wasm binary
iclens.canister.memory.custom_sections	iclens_canister_memory_custom_sections_bytes	Wasm custom sections
iclens.canister.memory.history	iclens_canister_memory_history_bytes	Canister history
iclens.canister.memory.chunk_store	iclens_canister_memory_chunk_store_bytes	Wasm chunk storage
iclens.canister.memory.snapshots	iclens_canister_memory_snapshots_bytes	Snapshot storage
iclens.canister.memory.logs	iclens_canister_memory_logs_bytes	Canister log storage
iclens.canister.memory_allocation	iclens_canister_memory_allocation_bytes	Configured memory allocation
iclens.canister.wasm_memory_limit	iclens_canister_wasm_memory_limit_bytes	Configured Wasm memory limit
iclens.canister.wasm_memory_threshold	iclens_canister_wasm_memory_threshold_bytes	Configured Wasm memory threshold
iclens.canister.log_memory_limit	iclens_canister_log_memory_limit_bytes	Configured log memory limit

A configured limit or threshold is a setting, not current usage. Do not add configuration gauges to usage totals.

Lifecycle, authority, and configuration

These are gauges. State encodings describe observations; they do not authorize an operation.

Native descriptor	PromQL name	Meaning
iclens.canister.compute_allocation	iclens_canister_compute_allocation_percent	Configured percent; native unit %
iclens.canister.controllers	iclens_canister_controllers	Number of controllers
iclens.canister.agent_controller	iclens_canister_agent_controller	Whether this Agent is a controller
iclens.canister.module_installed	iclens_canister_module_installed	Whether a module is installed
iclens.canister.status_code	iclens_canister_status_code	Running = 0, stopping = 1, stopped = 2
iclens.canister.module_hash_fingerprint	iclens_canister_module_hash_fingerprint	First eight module-hash bytes as an unsigned fingerprint
iclens.canister.log_visibility_code	iclens_canister_log_visibility_code	Controllers = 0, public = 1, allowed viewers = 2
iclens.canister.snapshot_visibility_code	iclens_canister_snapshot_visibility_code	Controllers = 0, public = 1, allowed viewers = 2
iclens.canister.status_visibility_code	iclens_canister_status_visibility_code	Controllers = 0, public = 1, allowed viewers = 2
iclens.canister.minimum_incoming_call_cycles	iclens_canister_minimum_incoming_call_cycles	Configured minimum cycles attached to an incoming canister call
iclens.canister.ready_for_migration	iclens_canister_ready_for_migration	Reported migration readiness
iclens.canister.version	iclens_canister_version	Canister version

A module fingerprint is a chartable identifier, not the complete Wasm hash or release attestation. Verify module identity through the operational code or release workflow.

Query workload

These are cumulative monotonic sums. Use rate() for per-second demand or increase() for a windowed estimate, with an appropriate observation window.

Native descriptor	PromQL name	Quantity
iclens.canister.query.calls	iclens_canister_query_calls_total	Query calls
iclens.canister.query.instructions	iclens_canister_query_instructions_total	Query instructions
iclens.canister.query.request_payload	iclens_canister_query_request_payload_bytes_total	Request bytes
iclens.canister.query.response_payload	iclens_canister_query_response_payload_bytes_total	Response bytes

These platform query counters do not replace application instrumentation for arbitrary business events or update-method request counts.

Cycle consumption categories

Each instrument is a cumulative monotonic Sum with unit cycles.

Native descriptor	PromQL name	Category
iclens.canister.consumed.memory	iclens_canister_consumed_memory_cycles_total	Memory
iclens.canister.consumed.compute	iclens_canister_consumed_compute_cycles_total	Compute allocation
iclens.canister.consumed.ingress	iclens_canister_consumed_ingress_cycles_total	Ingress induction
iclens.canister.consumed.instructions	iclens_canister_consumed_instructions_cycles_total	Executed instructions
iclens.canister.consumed.transmission	iclens_canister_consumed_transmission_cycles_total	Request/response transmission
iclens.canister.consumed.uninstall	iclens_canister_consumed_uninstall_cycles_total	Uninstall operations
iclens.canister.consumed.creation	iclens_canister_consumed_creation_cycles_total	Canister creation
iclens.canister.consumed.http_outcalls	iclens_canister_consumed_http_outcalls_cycles_total	HTTP outcalls
iclens.canister.consumed.burned	iclens_canister_consumed_burned_cycles_total	Explicit system-API cycle burning

These counters describe consumption, while balance also reflects funding. Exact observed range increases need reset handling and an eligible pre-range baseline. A missing baseline must not be replaced with zero.

Availability checks

The Agent writes one atomic frame of these gauges for each completed availability check attempt on a canister that has an opt-in check. Canisters without a check have no such series.

Native descriptor	PromQL name	Meaning
iclens.canister.availability.up	iclens_canister_availability_up	Reply = 1, reject = 0; stale for protocol and transport failures
iclens.canister.availability.round_trip	iclens_canister_availability_round_trip_milliseconds	Outcall round trip in milliseconds, including subnet consensus; stale for protocol and transport failures
iclens.canister.availability.result_code	iclens_canister_availability_result_code	Replied = 0, IC reject code 1–6, protocol error = 7, transport error = 8

Availability over a window is replies divided by replies plus rejects, for example avg_over_time(iclens_canister_availability_up[24h]). Protocol and transport failures are not evidence that the target is down. A missing frame means no attempt completed, for example while the Agent was stopped; it is a gap, not zero.

Log collection

The Agent writes one atomic frame of these gauges for each complete minute of log lines it collected from a canister, at the minute’s start by record time, once every record of that minute has been read. Canisters the Agent does not collect have no such series.

Native descriptor	PromQL name	Meaning
iclens.canister.log_lines	iclens_canister_log_lines_per_minute	Lines the canister logged in the minute
iclens.canister.traps	iclens_canister_traps_per_minute	Trap records the IC wrote for the canister in the minute

Counts include lines the daily cap left out of storage. A minute without a frame inside the collected range had no lines; a minute touched by a gap (records the canister’s buffer dropped before the Agent read them) or outside the collected range has no frame and is unknown, not zero. Use the collection’s coverage from the Agent API to tell the two apart.

Overview measurement rules

Consumption, memory, and missing categories

Legends retain every category: 0 is an established zero; Unavailable is missing evidence. Zero has no donut slice. Incomplete categories show a known subtotal and suppress percentage shares. Memory’s independent total remains in Details. Partial data summarizes incomplete evidence; Details retains exact coverage and full timestamps.

Historical memory composition uses the latest reading in the preceding hour. Missing evidence never substitutes a future sample or current memory values.

An unchanged positive consumption counter can show 0 TC in Range and a positive cumulative Total. Total includes consumption before Monitor began. Each canister uses its newest consumption frame without mixing older parts. Reads respect the Agent’s permitted lookback; missing history does not fall back to reads as You. Consumption bars stay in the selected range even when the donut shows Total. Hourly/daily bars occupy actual slots, with values at visible bucket midpoints, including partial boundary buckets; missing buckets remain blank.

Detailed Agent-workspace memory status requires the Agent’s guarded operation and the caller’s eligibility. Passive readers can retain fleet totals without permission to run active status reads. This browser reuses its status read; neither path substitutes another reader. Unclassified Other does not reveal its constituent categories. A denial removes the prior private response. Total, category, and snapshot-history timestamps stay separate; snapshot cost is not inferred from storage bytes.

Burn coverage

Daily burn requires one hour of covered counter intervals. A fully sampled selection of at least one hour also qualifies with four readings covering 54 measured minutes, allowing boundary sampling loss only. Internal gaps and startup history do not qualify. Rates use actual covered duration, excluding gaps, stale samples, and resets. Below the minimum, Burn shows spending with Collecting history; runway and Frozen in use labelled idle estimates or remain blank.

Normal boundary sampling loss can coexist with full coverage. Partial coverage names the actual span; Details gives exact coverage such as 23 h 59 min of 24 h. A balance-history estimate needs at least one hour of genuine aligned observations, a fresh final sample, and accounting for known executed funding credits. A short suffix after a gap does not yield daily burn. Samples are never interpolated. Once the overall window qualifies, sparkline buckets use their actual covered duration: a valid 59-minute bucket remains valid; buckets without usable intervals stay gaps.

Availability evidence

Configuration and history load independently. Paused or deleted checks may still have retained attempts. Not checked requires a complete successful history read with no attempt; pending, failed, and incomplete reads do not establish it. Partial coverage describes only returned attempts. Reconnect or read-access loss immediately hides retained check data. A transient refresh failure can retain last-good evidence with its error and original time.

Use Overview and Cycles for the operator workflows.

Application instruments

Application producers define Gauge, Sum, and explicit Histogram descriptors under their accepted ingestion contract. Use discovery to inspect their origin and actual descriptor identity; application names are not part of the fixed platform catalog.

The Agent returns capability and projection revisions for the current supported query profile. Native preserves exact integer representations; PromQL/Prometheus use binary64 projection. Read precision notices, coverage, stale markers, and reset diagnostics alongside a numeric result.

Use metrics basics for interpretation, PromQL for executable expressions, and custom metrics for producer contracts.