Tyler King
6eb2de5dc0
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>
78 lines
2.4 KiB
Markdown
78 lines
2.4 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 |
|
|
|
|
## Management API
|
|
|
|
The built-in management API (port 9090) provides real-time session monitoring:
|
|
|
|
```bash
|
|
# 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](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}
|
|
```
|