SHA256

Tyler King e7fc9fa5e1 feat: structured logging, tracing spans, comprehensive documentation

Observability:
  Structured JSON logging via BASCULE_LOG_FORMAT=json
  Tracing spans on auth (method, principal, peer)
  Tracing spans on session lifecycle (id, principal, backend, source_ip)
  Tracing spans on exec requests (session_id, command)
  Config: [telemetry] and [metrics] sections (OTel export planned)

Documentation (8 files, 489 lines):
  docs/quickstart.md — three-path getting started
  docs/configuration.md — full config reference with examples
  docs/authentication.md — all auth modes with setup guides
  docs/architecture.md — backends, traits, extension model, security
  docs/observability.md — logging, tracing, metrics
  docs/comparison.md — vs Teleport, Boundary, StrongDM
  images/README.md — curated image catalog
  README.md — features, comparison, quickstart, extension example

1557 lines Rust, 489 lines docs, 0 substrate deps.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

2026-04-04 23:45:03 -04:00

1.9 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

OTel Tracing (Planned)

OpenTelemetry OTLP export is planned as an optional feature flag (--features telemetry). Session lifecycle maps to OTel spans:

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

Prometheus Metrics (Planned)

Prometheus-compatible metrics endpoint planned as --features metrics:

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

1.9 KiB Raw Blame History