Tyler King
e7fc9fa5e1
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>
61 lines
1.9 KiB
Markdown
61 lines
1.9 KiB
Markdown
# Observability
|
|
|
|
## Structured Logging
|
|
|
|
Bascule logs structured events via the `tracing` crate. Every log includes session context (session ID, principal, backend, source IP).
|
|
|
|
### JSON format
|
|
|
|
```bash
|
|
BASCULE_LOG_FORMAT=json ./bascule --config config.toml
|
|
```
|
|
|
|
Output:
|
|
|
|
```json
|
|
{"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
|
|
|
|
```bash
|
|
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}
|
|
```
|