Skip to content

irtop Observability

Stage: Alpha Status: Draft

irtop is an operator-facing view over IronRoot status APIs. It complements OpenTelemetry dashboards by giving administrators a fast terminal interface for live checks.

What irtop Reads

irtop uses read-only status endpoints:

  • GET /v1/status/overview
  • GET /v1/status/server
  • GET /v1/status/ca
  • GET /v1/status/ca-hierarchy
  • GET /v1/status/certificates
  • GET /v1/status/enrollments
  • GET /v1/status/tokens
  • GET /v1/status/security
  • GET /v1/status/telemetry
  • GET /v1/audit/recent

These endpoints are intentionally safe for monitoring. They do not return private keys, bootstrap token secret values, token hashes, or raw CA key material.

CA Hierarchy View

The CA view renders the Root and Intermediate CA hierarchy as a terminal tree. It shows environment labels, active/disabled/retired issuer states, certificate counts, expiration health, token policy counts, and RBAC role counts.

GET /v1/status/ca-hierarchy is read-only. It exposes metadata needed for monitoring multi-root deployments, including Root CAs, Intermediate CAs, token policies, and role bindings, but never returns private key material.

Telemetry Generated By irtop

irtop initializes IronRoot telemetry and instruments:

  • API request spans through the OpenTelemetry HTTP transport
  • refresh cycle spans
  • UI action spans for refresh and view changes

Telemetry is optional. In local development, irtop works without an OpenTelemetry Collector.

How It Fits With Dashboards

Use irtop for immediate operator inspection and Grafana/Prometheus/Tempo/Loki for longer-term visibility:

  • irtop: current state from the terminal
  • Prometheus: metrics and alerts
  • Tempo: distributed traces
  • Loki: structured logs
  • Grafana: dashboards across all signals

Security Notes

irtop is safe to use for screen sharing when credentials are not shown in the terminal command line. Prefer configuration files or environment-managed shell history rules for admin tokens.

Never paste private keys, bootstrap token values, or CA key material into irtop configuration.