SHA256

Tyler King 6eb2de5dc0 docs: update all documentation for management API + dashboard

Updated 9 files to reflect:
  Management API (axum, port 9090) — embedded in bascule-server
  Dioxus dashboard components (WASM web target)
  6 crates in workspace (was 4)

README.md:
  Added Management API + Dashboard features section
  Added dashboard row to comparison table

docs/architecture.md:
  Updated diagram showing dual-listener architecture
  Added Management API section explaining Arc<SessionStore> sharing
  Updated crate table (6 crates)

docs/configuration.md:
  Added [dashboard] config section reference

docs/observability.md:
  Added Management API monitoring section with curl examples

docs/quickstart.md:
  Added Management API quick start section

docs/comparison.md:
  Added dashboard and TPM attestation rows

CLAUDE.md + CONTRIBUTING.md:
  Updated crate lists and feature flags

config/bascule.example.toml:
  Added [dashboard] section

All 17 README links verified valid. Build clean.

Signed-off-by: Tyler King <tking@guildhouse.dev>

2026-04-05 17:17:18 -04:00

2.4 KiB

Raw Blame History

Observability

Structured Logging

Bascule logs structured events via the tracing crate. Every log includes session context (session ID, principal, backend, source IP).

JSON format

BASCULE_LOG_FORMAT=json ./bascule --config config.toml

Output:

{"timestamp":"2026-04-04T20:30:00Z","level":"INFO","message":"Auth accepted","method":"ssh-key","principal":"tking","peer":"192.168.1.10:54321"}
{"timestamp":"2026-04-04T20:30:00Z","level":"INFO","message":"Shell session starting","session.id":"abc-123","session.principal":"tking","session.backend":"container","session.source_ip":"192.168.1.10"}

Log levels

RUST_LOG=debug ./bascule --config config.toml     # verbose
RUST_LOG=info ./bascule --config config.toml      # standard
RUST_LOG=warn ./bascule --config config.toml      # quiet
RUST_LOG=bascule=debug ./bascule --config config.toml  # debug bascule only

Key Events

Event	Level	When
Auth accepted	INFO	SSH authentication succeeds
Auth rejected	WARN	SSH authentication fails
Shell session starting	INFO	New session with backend type
Exec request	INFO	Non-interactive command execution
Container spawning	INFO	Container session starting
Upstream connected	INFO	Proxy session connected to target
Session ended	INFO	Disconnect or exit

Management API

The built-in management API (port 9090) provides real-time session monitoring:

# Active sessions
curl http://localhost:9090/api/sessions

# Aggregate stats (auth breakdown, TPM %, peak concurrent)
curl http://localhost:9090/api/stats

# Server health
curl http://localhost:9090/api/health

Configure via [dashboard] in your config file. See configuration.md.

OTel Tracing (Planned)

OpenTelemetry OTLP export is planned as an optional feature flag (--features telemetry). Not yet implemented. Session lifecycle will map to OTel spans:

session (root)
├── auth (ssh-key / agent-id)
├── backend_setup (pty / proxy / container)
└── session_active (commands, I/O)

Prometheus Metrics (Planned)

Prometheus-compatible metrics endpoint is planned as --features metrics. Not yet implemented. Planned metrics:

bascule_sessions_total{backend,auth_method,outcome}
bascule_sessions_active
bascule_session_duration_seconds{backend}
bascule_auth_attempts_total{method,outcome}

2.4 KiB Raw Blame History