# 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}
```