initial setup

This commit is contained in:
ari committed 2026-10-15 17:07:03 -04:00
1 parent 58ebcaa97f
commit 389c4f998a
19 files changed
+1206 -40

No files matched your search

+82
View File
@@ -0,0 +1,82 @@
# P0 — Foundation
| Field | Value |
|---|---|
| Status | Ready |
| Owner | — |
| Phase | 0 (blocking, single track) |
| Depends on | — |
| Blocks | Every other card |
| Owned files | `Cargo.toml`, `devenv.nix`, `config.example.toml`, `src/main.rs`, `src/config.rs`, `src/error.rs`, `src/state.rs`, `src/sources/mod.rs`, `src/sources/fake.rs`, initial stubs of every other module |
## Goal
Fix every contract that parallel work depends on: dependencies, config shape, DTOs, source traits, error type, `AppState`, and module signatures. After P0, no other card should need to touch `Cargo.toml`, `main.rs` or `sources/mod.rs`, except by agreed exception.
Keep it small. Stubs contain `todo!()` and no logic.
## Tasks
Tick these in [`TODO.md`](../../TODO.md).
- **P0-1 devenv.** Keep `languages.rust.enable` and the existing `CLAUDE_CONFIG_DIR` `enterShell`. Add `pkgs.pkg-config` and `pkgs.systemd` (its `.dev` output provides `libsystemd.pc`). Add `scripts.build`, `scripts.run` and `scripts.token`, which wraps `cargo run -- token`. Do not add openssl. Optionally add `pkgs.opentelemetry-collector-contrib` for G7.
- **P0-2 Cargo.toml.** Package `skyg-linux-tracker` with `[[bin]] name = "slinuxm"` (DEC-1). Pin every crate needed by all phases:
- Runtime: `tokio` (full), `tokio-util` (`CancellationToken`), `futures`.
- HTTP: `axum` 0.8, `tower`, `tower-http` (`trace`).
- Data: `serde`, `serde_json`, `schemars`, `thiserror`, `jiff` or `chrono`.
- Config/CLI: `figment` (`toml`, `env`), `clap` (`derive`, `env`).
- MCP: `rmcp` (`server`, `macros`, `schemars`, `transport-streamable-http-server`).
- systemd/journal: `zbus`, `zbus_systemd` (`systemd1`), `systemd` (`journal`, default features off where possible).
- Docker: `bollard`, no TLS features needed for a unix socket.
- OTel: `opentelemetry`, `opentelemetry_sdk`, `opentelemetry-otlp` (`grpc-tonic`, `http-proto`, rustls), `tracing`, `tracing-subscriber`, `tracing-opentelemetry`.
- Auth: `sqlx` (`runtime-tokio`, `sqlite`), `sha2`, `rand`, `base64`.
- Optional: `async-trait`.
- Release profile: `lto = true`, `strip = true`, `codegen-units = 1`.
- **P0-3 API spike, max half a day.** Confirm against the pinned versions:
- The rmcp `StreamableHttpService::new` signature, `StreamableHttpServerConfig` fields, and whether it validates Origin or Host (DEC-8).
- zbus_systemd `ManagerProxy`, `UnitProxy`, `ServiceProxy`, `TimerProxy` names and property types.
- The `systemd` crate journal open API, `wait` with timeout, namespace support, and whether `Journal` is `Send`.
- bollard feature flags that avoid pulling openssl or rustls when only the unix socket is used.
- The opentelemetry-otlp builder API for headers and protocol selection.
- Record findings in the log below.
- **P0-4 config.rs.** Use figment `Serialized::defaults` < `Toml::file` < `Env::prefixed("SKYG_").split("__")` < CLI overrides. Key additions over `plan.md`:
- `otel.headers` (map)
- `otel.metrics.units` / `otel.metrics.containers` (glob allowlists)
- `limits.max_lines` (default 1000), `limits.max_tail` (default 1000), `limits.max_follow_secs` (default 60)
- Validation: reject `auth.enabled = false` when `bind` is not loopback.
- **P0-5 config.example.toml.** Document every key with a comment and its env-var name.
- **P0-6 DTOs** in `src/sources/mod.rs`:
- `UnitSummary`, `UnitStatus` (service fields `Option`), `TimerInfo`
- `JournalQuery`, `JournalEntry`, `Priority` (0–7, parse from name or number)
- `ContainerSummary`, `ContainerStatus`, `LogLine { stream: Stdout|Stderr, ts, message }`
- All derive `Serialize`, `JsonSchema` and `Debug`. Timestamps serialize as RFC3339.
- **P0-7 Traits + fakes.** `SystemdSource`, `JournalSource`, `DockerSource`. Follow methods return `mpsc::Receiver` or a boxed `Stream`. `fake.rs` provides fixture-backed implementations for tests (DEC-2).
- **P0-8 error.rs.** `AppError { NotFound, BadRequest, Unauthorized, Unavailable, Internal }`. Implement `IntoResponse` (status + `{"error": {"code", "message"}}`) and `From<AppError> for rmcp::ErrorData`.
- **P0-9 state.rs.** `AppState { config: Arc<Config>, systemd: Arc<dyn SystemdSource>, journal: Arc<dyn JournalSource>, docker: Arc<dyn DockerSource>, db: Option<SqlitePool>, shutdown: CancellationToken }`. Must be `Clone`.
- **P0-10 Stubs with final signatures:**
- `api::router(AppState) -> Router`
- `mcp::service(AppState) -> StreamableHttpService<…>`
- `telemetry::init(&Config) -> Result<TelemetryGuard>`
- `auth::layer(AppState)`
- `auth::tokens::run(TokenCmd, &Config) -> Result<()>`
- `db::open(&Config) -> Result<SqlitePool>`
- Source constructors in `sources/{systemd,journal,docker}.rs`.
- `main.rs` dispatches `slinuxm serve` (default), `slinuxm token …`, and `--print-config`.
- **P0-11 Tests.** Defaults only, file overrides defaults, env overrides file, CLI overrides env. The auth-off + `0.0.0.0` combination is an error.
## Done when
- `cargo run -- serve --print-config` prints the merged config, and precedence works by hand.
- `cargo build` produces `target/debug/slinuxm`.
- `cargo clippy -- -D warnings`, `cargo fmt --check` and `cargo test` are clean.
- `cargo tree -i openssl` and `cargo tree -i openssl-sys` print nothing.
- Spike findings are recorded below and DEC-8 is updated.
## Risks
- Changing DTOs after Phase 1 starts causes merge pain in four places. Spend the time here.
- rmcp moves fast. Pin the exact version and note it in the log.
## Log
- 2026-10-15: Card created from `plan.md` review. DEC-1 decided: CLI is `slinuxm`.
+59
View File
@@ -0,0 +1,59 @@
# P3 — Integration & hardening
| Field | Value |
|---|---|
| Status | Backlog |
| Owner | — |
| Phase | 3 (single track) |
| Depends on | WS-E, WS-F, WS-G (and transitively A–D) |
| Blocks | Release |
| Owned files | `src/main.rs` (serve wiring), `systemd/skyg-linux-tracker.service`, `README.md`, `tests/` |
## Goal
Wire every surface into one axum server, prove the negative paths, and ship the unit file and docs. This is the only place the surfaces meet.
## Tasks
Tick these in [`TODO.md`](../../TODO.md).
- **I1** `slinuxm serve` wiring in `main.rs`:
1. Load config, then `telemetry::init`, then `db::open` when auth is enabled, then construct sources and `AppState`.
2. Build the protected router: `.nest("/api/v1", api::router(state))` and `.nest_service("/mcp", mcp::service(state))`, then `.layer(auth::layer(state))`.
3. Build the public router with `/healthz`.
4. `public.merge(protected).layer(TraceLayer::new_for_http())` (review R3).
5. Spawn the metrics and log export tasks when enabled.
6. On SIGINT or SIGTERM: cancel `state.shutdown` so SSE streams and background tasks end, run `axum::serve(...).with_graceful_shutdown`, then drop the telemetry guard to flush OTel (review G3).
- **I2** Integration tests in `tests/` covering Verification #6:
- A missing or invalid token gets 401 on `/api/v1/*` and `/mcp`. `/healthz` returns 200 without a token.
- `auth.enabled = false` with `bind = 0.0.0.0` makes startup exit non-zero with a clear message.
- A missing Docker socket gives 503 on docker routes while systemd routes still return 200.
- SIGTERM with an open SSE client exits within a few seconds.
- **I3** `systemd/skyg-linux-tracker.service`:
- `ExecStart=/usr/local/bin/slinuxm serve --config /etc/skyg-linux-tracker.toml`
- A dedicated `User=` (for example `skyg`), or `DynamicUser=yes` if the token CLI story still works. Decide and note it.
- `StateDirectory=skyg-linux-tracker`, `StateDirectoryMode=0700`
- `ProtectSystem=strict`, `ProtectHome=yes`, `PrivateTmp=yes`, `NoNewPrivileges=yes`, `ProtectKernelTunables=yes`, `ProtectControlGroups=yes`, `RestrictAddressFamilies=AF_UNIX AF_INET AF_INET6`, `LockPersonality=yes`, `MemoryDenyWriteExecute=yes`
- `SupplementaryGroups=systemd-journal`. Add `docker` commented out with a root-equivalence warning (DEC-6).
- **I4** `README.md`:
- What it is and how to build it (`devenv shell`, `cargo build --release`).
- Install: binary, config, unit file.
- Config reference, or a pointer to `config.example.toml` and the env-var naming.
- Token workflow: `sudo -u skyg slinuxm token create <name>`.
- REST endpoint list, and MCP client setup with a bearer header example.
- OTel setup and the hardened Docker socket-proxy option.
- **I5** Release build checks:
- `cargo build --release`.
- `ldd target/release/slinuxm` lists only libc, libsystemd and libsystemd's own deps.
- Record the binary size in the log.
- **I6** Run Verification #1–#6 from `plan.md` by hand on a real systemd + Docker host and record the results in the log.
## Done when
- I2 tests pass in `cargo test`.
- I6 results are logged with all six checks passing.
- The unit file starts the service on a clean host with only the binary, config and unit installed.
## Log
- 2026-10-15: Card created.
+42
View File
@@ -0,0 +1,42 @@
# WS-A — systemd source
| Field | Value |
|---|---|
| Status | Backlog |
| Owner | — |
| Phase | 1 (parallel) |
| Depends on | P0 |
| Blocks | WS-E, WS-F, WS-G (to finish) |
| Owned files | `src/sources/systemd.rs`, `examples/systemd_dump.rs` |
## Goal
Implement `SystemdSource` over D-Bus with `zbus_systemd`. Every call hits the bus live, with no caching.
## Tasks
Tick these in [`TODO.md`](../../TODO.md).
- **A1** Create one `zbus::Connection::system()` at construction and share `ManagerProxy`.
- **A2** `list_units(state: Option<…>)`. Use `ListUnitsFiltered(states)` when a state is given, otherwise `ListUnits`. Map the tuple to `UnitSummary` (name, description, load/active/sub state).
- **A3** `list_timers()`. The Manager has no `ListTimers` method (review R1). Call `ListUnitsByPatterns([], ["*.timer"])`, then for each timer read `TimerProxy`: `NextElapseUSecRealtime`, `LastTriggerUSec`, `Unit` (the triggered unit). Convert µs since epoch to RFC3339. `0` or `u64::MAX` means `None`.
- **A4** `unit_status(name)`. Try `GetUnit(name)` first, falling back to `LoadUnit` only on `NoSuchUnit`. The fallback lets inactive unloaded units still report without side effects on loaded ones.
- `Unit` props: `ActiveState`, `SubState`, `LoadState`, `Description`, `ActiveEnterTimestamp`, `FragmentPath`.
- `Service` props, only when the name ends in `.service`: `ExecMainStatus`, `NRestarts`, `MainPID`.
- **A5** Validate names against systemd's charset (`[A-Za-z0-9:_.@\-\\]`, max 255) and return `BadRequest`. Map D-Bus `NoSuchUnit` to `NotFound`. Map bus connection failure to `Unavailable`.
- **A6** `examples/systemd_dump.rs` prints JSON for units, failed units, timers and one unit's status.
- **A7** Unit tests for µs-to-RFC3339 conversion, sentinel handling and tuple mapping.
## Done when
- `cargo run --example systemd_dump` prints sane JSON on a real host. Timers show next elapse times that match `systemctl list-timers`.
- `unit_status("nonexistent.service")` returns `NotFound` and `unit_status("../etc")` returns `BadRequest`.
## Notes
- Property reads cost one D-Bus round-trip each. Fetch with `GetAll` where zbus_systemd exposes it, or `join!` the reads.
- Unprivileged reads on the system bus are allowed. No polkit involvement is needed for these calls.
## Log
- 2026-10-15: Card created.
+47
View File
@@ -0,0 +1,47 @@
# WS-B — journal source
| Field | Value |
|---|---|
| Status | Backlog |
| Owner | — |
| Phase | 1 (parallel) |
| Depends on | P0 (incl. spike findings on the `systemd` crate) |
| Blocks | WS-E, WS-F, WS-G (to finish) |
| Owned files | `src/sources/journal.rs`, `examples/journal_tail.rs` |
## Goal
Implement `JournalSource` over sd-journal via the `systemd` crate. It provides a bounded snapshot query and a cancellable live follow.
## Tasks
Tick these in [`TODO.md`](../../TODO.md).
- **B1** Run every sd-journal call inside `tokio::task::spawn_blocking` (review G1). Open the journal inside the blocking closure and never hold it across `.await`. Use `sources.journal_namespace` if the spike found namespace support. Otherwise log a warning when it is set and use the default journal.
- **B2** `query(JournalQuery)`:
- Unit filter via `match_add("_SYSTEMD_UNIT", unit)`.
- Priority filter `≤ N` by adding one `PRIORITY=k` match for each k in 0..=N. Matches on the same field are OR'ed by sd-journal.
- `seek_tail`, then step backward `lines` entries. `lines` is clamped to `limits.max_lines`.
- Reverse the result so it returns oldest-first.
- **B3** `follow(JournalQuery, CancellationToken) -> mpsc::Receiver<JournalEntry>`:
- Seek to tail and run a blocking loop of `wait(Some(500ms))`, then drain new entries with `next`.
- Each iteration checks `tx.is_closed()` and `token.is_cancelled()` and exits if either is true (review G2).
- Use `blocking_send` with a bounded channel, around 1024 entries. Decide on drop-or-block for slow consumers and document it.
- **B4** Map `__REALTIME_TIMESTAMP`, `PRIORITY`, `_SYSTEMD_UNIT`, `SYSLOG_IDENTIFIER`, `_PID`, `_HOSTNAME` and `MESSAGE` to `JournalEntry`. `MESSAGE` may be binary, so convert it with lossy UTF-8.
- **B5** `examples/journal_tail.rs --unit X [--priority err] [--lines N] [--follow]`.
- **B6** Test that dropping the receiver makes the blocking thread exit within about one second. Use a counter or `JoinHandle` to prove it.
## Done when
- The example snapshot output matches `journalctl -u X -p err -n N -o json` for the same filters.
- Follow prints new entries live. `logger -t test hello` shows up in under a second.
- B6 passes.
## Notes
- Reading the full system journal needs the `systemd-journal` group (or root). Without it you only see your own user's entries. Say so in the example's error output.
- If the `systemd` crate turns out unmaintained or broken during the spike, record the alternative in the P0 log before starting.
## Log
- 2026-10-15: Card created.
+44
View File
@@ -0,0 +1,44 @@
# WS-C — docker source
| Field | Value |
|---|---|
| Status | Backlog |
| Owner | — |
| Phase | 1 (parallel) |
| Depends on | P0 |
| Blocks | WS-E, WS-F, WS-G (to finish) |
| Owned files | `src/sources/docker.rs`, `examples/docker_ps.rs` |
## Goal
Implement `DockerSource` over the Docker or Podman API with `bollard` on a unix socket. A missing Docker never breaks the rest of the service.
## Tasks
Tick these in [`TODO.md`](../../TODO.md).
- **C1** Construct with `Docker::connect_with_unix(socket, timeout, API_DEFAULT_VERSION)`. Construction must not fail when the socket is absent (review G9). Map connection-refused, not-found and permission-denied to `AppError::Unavailable` with a clear message on each call.
- **C2** `ps()`:
- `list_containers(all = true)`.
- Then `inspect_container` for each one concurrently, bounded with `buffer_unordered(8)`.
- Map `State.Health.Status`, `State.StartedAt` (to uptime seconds), `RestartCount`, image, and status.
- **C3** `container_status(name)` uses inspect only. A 404 maps to `NotFound`.
- **C4** `logs(name, follow, tail, since, token)` returns a boxed `Stream<Item = Result<LogLine>>`. Use `stdout`, `stderr` and `timestamps = true`, parse the timestamp prefix, and keep the stream type (stdout or stderr). The stream ends when dropped or when the token fires.
- **C5** Clamp `tail` to `limits.max_tail`.
- **C6** `examples/docker_ps.rs` prints `ps` as JSON. `--logs NAME [--follow]` streams logs.
- **C7** *(nice-to-have)* Run the example against `/run/podman/podman.sock` and note any field differences.
## Done when
- The example matches `docker ps -a` and shows health and uptime for containers with healthchecks.
- Following logs streams live, and Ctrl-C exits cleanly.
- With `docker_socket` pointed at a missing path, every call returns `Unavailable` and nothing panics.
## Notes
- Container names from the API have a leading `/`. Strip it in DTOs and accept names with or without it.
- `docker logs` only works for the `json-file`, `local` and `journald` log drivers. Others return an API error, which should map to `BadRequest` with the driver named.
## Log
- 2026-10-15: Card created.
+53
View File
@@ -0,0 +1,53 @@
# WS-D — auth + DB
| Field | Value |
|---|---|
| Status | Backlog |
| Owner | — |
| Phase | 1 (parallel) |
| Depends on | P0 |
| Blocks | WS-E, WS-F (to finish), P3 |
| Owned files | `src/db.rs`, `src/auth/mod.rs`, `src/auth/tokens.rs`, `migrations/` |
## Goal
Provide token storage in SQLite, the `slinuxm token` CLI, and one bearer-auth middleware that protects both `/api/v1` and `/mcp`.
## Tasks
Tick these in [`TODO.md`](../../TODO.md).
- **D1** `db::open`:
- Create the parent dir with mode `0700` if it is missing. In production, systemd `StateDirectory=` already creates it.
- Use `SqliteConnectOptions` with `create_if_missing`, `journal_mode(Wal)` and `busy_timeout(5s)`.
- Run `sqlx::migrate!()` from embedded `migrations/`.
- **D2** First migration: `tokens(id INTEGER PK, name TEXT NOT NULL UNIQUE, token_hash TEXT NOT NULL UNIQUE, created_at TEXT NOT NULL, revoked_at TEXT, last_used_at TEXT)`.
- **D3** `tokens.rs` with runtime `sqlx::query` / `query_as` (DEC-3):
- `create(name)` generates 32 bytes from the OS RNG and formats the token as `slinuxm_<base64url>`. Store `hex(sha256(token))` and print the plaintext once with a warning.
- `list()` shows name, created, revoked and last-used, never hashes.
- `revoke(name)` sets `revoked_at`. Revoking twice is a no-op with a message.
- **D4** Implement `auth::tokens::run(TokenCmd, &Config)` behind `slinuxm token create|list|revoke`. The `main.rs` dispatch already exists from P0, so do not edit `main.rs`.
- **D5** Middleware:
- Extract `Authorization: Bearer <t>`, hash it, and look up `WHERE token_hash = ? AND revoked_at IS NULL`.
- On success, optionally update `last_used_at`. Throttle that update to at most once a minute per token, or skip it.
- On failure, return `401` with `WWW-Authenticate: Bearer` and the standard JSON error body. Use the same response for `/mcp` (DEC-4).
- When `auth.enabled = false`, the layer is a pass-through.
- **D6** Expose the middleware so P3 applies it to the protected router only. `/healthz` must stay reachable without a token (review R3).
- **D7** Tests:
- Use an in-memory or tempdir DB.
- Create a token and confirm it is accepted. Revoke it and confirm it is rejected. Garbage and missing headers are rejected.
- Re-assert the P0 startup refusal for auth-off + non-loopback bind.
## Done when
- `slinuxm token create ci` prints a token. `slinuxm token list` shows it. A request with it passes the middleware.
- After `slinuxm token revoke ci`, the same request returns 401 without a server restart.
- D7 passes.
## Notes
- The CLI writes the same DB the server reads, so WAL mode is required. In production, run the CLI as the service user, for example `sudo -u skyg slinuxm token create …`. Document this in the README (I4).
## Log
- 2026-10-15: Card created.
+50
View File
@@ -0,0 +1,50 @@
# WS-E — REST API
| Field | Value |
|---|---|
| Status | Backlog |
| Owner | — |
| Phase | 2 (parallel) |
| Depends on | P0 to start (fakes). A, B, C, D to finish. |
| Blocks | P3 |
| Owned files | `src/api/mod.rs`, `src/api/systemd.rs`, `src/api/journal.rs`, `src/api/docker.rs` |
## Goal
Build thin, read-only GET handlers over `AppState` sources, with SSE for follow endpoints. `api::router(state)` returns a router that P3 nests under `/api/v1`.
## Tasks
Tick these in [`TODO.md`](../../TODO.md).
- **E1** `api::router(AppState) -> Router`. Use axum 0.8 path syntax `/{name}`, because `:name` panics (review R4). GET only.
- **E2** Systemd routes:
- `/systemd/units?state=failed|active|…`
- `/systemd/units/{name}`
- `/systemd/timers`
- **E3** `/journal?unit=&priority=err|3&lines=`. Parse priority by name or number. Clamp `lines` and return 400 on bad input.
- **E4** `/journal/follow?unit=&priority=` returns `Sse` built from the source receiver:
- `KeepAlive::default()`.
- The stream ends on client disconnect, which drops the receiver and stops the blocking thread, or on `state.shutdown` (review G3).
- **E5** Docker routes:
- `/docker/ps`
- `/docker/containers/{name}`
- `/docker/containers/{name}/logs?tail=&since=&follow=`: JSON array when `follow=0`, SSE when `follow=1`. Each SSE event's `event:` is `stdout` or `stderr`.
- **E6** Provide a public `healthz` handler for P3 to mount outside auth. It returns `{"status":"ok","version":…}`.
- **E7** All errors go through `AppError`, giving one JSON shape everywhere.
- **E8** Tests with `fake.rs` sources via `tower::ServiceExt::oneshot`. Cover each route's happy path, 400, 404, and one SSE stream that yields events and then ends.
- **E9** When the fake docker returns `Unavailable`, docker routes return 503 and systemd and journal routes still return 200.
## Done when
- E8 and E9 pass.
- With real sources wired by P3, Verification #3 curl checks pass, including `curl -N` on both SSE endpoints.
## Notes
- Handlers stay thin: parse, call the source, serialize. No business logic.
- `tower-http` `TraceLayer` is applied in P3, not here.
## Log
- 2026-10-15: Card created.
+60
View File
@@ -0,0 +1,60 @@
# WS-F — MCP server
| Field | Value |
|---|---|
| Status | Backlog |
| Owner | — |
| Phase | 2 (parallel) |
| Depends on | P0 to start (fakes, spike findings). A, B, C, D to finish. |
| Blocks | P3 |
| Owned files | `src/mcp/mod.rs`, `src/mcp/prompts.rs`, `src/mcp/resources.rs` |
## Goal
Build an `rmcp` Streamable HTTP server exposing the same data as REST, plus agent-facing context: instructions, rich descriptions, prompts and resources. `mcp::service(state)` returns the Tower service that P3 mounts at `/mcp`.
## Tasks
Tick these in [`TODO.md`](../../TODO.md).
- **F1** `TrackerService` holding `AppState`, with `#[tool_router]`. There are 8 tools (review R5):
- `list_systemd_units { state? }`
- `get_systemd_unit { name }`
- `list_systemd_timers {}`
- `get_journal_logs { unit?, priority?, lines }`
- `tail_journal { unit, seconds }`
- `list_containers {}`
- `get_container { name }`
- `get_container_logs { name, tail }`
- Parameter structs derive `Deserialize` and `JsonSchema`.
- **F2** `tail_journal` clamps `seconds` to `limits.max_follow_secs` and stops early at an entry cap, for example `limits.max_lines`. It returns whatever it collected and never streams indefinitely.
- **F3** `get_container_logs` clamps `tail` to `limits.max_tail`.
- **F4** `ServerHandler::get_info` sets server name/version, capabilities for tools, prompts and resources, and **instructions**. The instructions describe the workflow: start with failed units or unhealthy containers, then pull logs for the specific unit or container, and use timers to explain scheduled jobs.
- **F5** `#[tool(description = …)]` strings explain:
- active/sub states (`failed`, `activating`, `auto-restart`)
- journal priority numbers and names
- Docker health states (`starting`, `healthy`, `unhealthy`, `none`)
- **F6** Prompts in `prompts.rs`:
- `diagnose_unit { name }`: status, then recent err+ logs, then restart count, then a suggested next look.
- `container_health_report {}`: list, then unhealthy and restarting containers, then their logs.
- **F7** Resources in `resources.rs`: `systemd://units/failed` and `docker://containers`. Implement list and read, resolved live on each read, with no subscriptions (DEC-5).
- **F8** `mcp::service(state)` builds `StreamableHttpService::new(|| Ok(TrackerService::new(state.clone())), LocalSessionManager::default().into(), config)`. Apply Origin validation per DEC-8.
- **F9** Tests against fake sources:
- A snapshot of the tool list (names + schemas), so description changes are reviewed deliberately.
- Each tool's happy path.
- `AppError` maps to MCP errors.
- `tail_journal` respects its time cap.
## Done when
- F9 passes.
- With P3 wiring, Verification #4 passes. MCP Inspector at `http://localhost:9109/mcp` with a bearer header lists 8 tools, 2 prompts and 2 resources, and every tool returns data. Without the header the client receives 401.
## Notes
- Tool handlers must not duplicate logic from `api/`. Both call `sources/` directly.
- Keep tool output JSON-shaped (serialized DTOs) so agents can parse it, with a short text summary line where it helps.
## Log
- 2026-10-15: Card created.
+55
View File
@@ -0,0 +1,55 @@
# WS-G — OpenTelemetry export
| Field | Value |
|---|---|
| Status | Backlog |
| Owner | — |
| Phase | 2 (parallel) |
| Depends on | P0 to start (fakes, spike findings). A, B, C to finish. |
| Blocks | P3 |
| Owned files | `src/telemetry/mod.rs`, `src/telemetry/metrics_export.rs`, `src/telemetry/logs_export.rs`, `dev/otelcol.yaml` |
## Goal
Export traces, metrics and logs over a single OTLP exporter config. This is the only push path in the system. Metrics come from a poll loop, and logs fan out from the journal and Docker follow streams.
## Tasks
Tick these in [`TODO.md`](../../TODO.md).
- **G1** `telemetry::init(&Config) -> TelemetryGuard`:
- Build tracer, meter and logger providers from one exporter config: `otel.endpoint`, `otel.protocol` (`grpc` or `http`) and `otel.headers`.
- Resource attributes: `service.name`, `service.version`, `host.name`.
- When `otel.enabled = false`, return a no-op guard.
- **G2** Tracing subscriber: `fmt` to stderr (journald captures it under the unit) plus `tracing-opentelemetry` when enabled. Do **not** route the app's own logs into the OTel logs pipeline. That pipeline is for host logs.
- **G3** Metrics (review G11):
- A background task runs every `metrics_interval_secs`, calls `list_units`, `list_timers` and `ps`, and stores the result in an `ArcSwap` or `RwLock` snapshot.
- Observable gauges read the latest snapshot in their callbacks, so units or containers that disappear stop being reported.
- **G4** Metric set from `plan.md`:
- `systemd.unit.active`, `systemd.unit.failed`, `systemd.unit.restarts`, `systemd.timer.next_elapse_seconds`
- `docker.container.running`, `docker.container.healthy`, `docker.container.uptime_seconds`, `docker.container.restarts`
- Attribute names: `systemd.unit`, `systemd.sub_state`, `systemd.load_state`; `container.name`, `container.id`, `container.image.name` (semconv).
- Scope: apply `otel.metrics.units` / `otel.metrics.containers` globs. With an empty unit list, use the `*.service` + `*.timer` default (DEC-7).
- **G5** Logs (`otel.export_logs = true`, review G4):
- Journal: one `follow()` per configured unit, or one unfiltered follow when `otel.logs.journal_units` is empty. Map priority 0–7 to OTel severity (emerg/alert/crit to FATAL, err to ERROR, warning to WARN, notice/info to INFO, debug to DEBUG).
- Docker: a reconciler subscribes to Docker `events` (`start`, `die`, `destroy`). It starts and stops per-container `logs(follow)` tasks for allowlisted containers and does an initial list at startup. stderr maps to WARN and stdout to INFO.
- Every task restarts with exponential backoff on error. If Docker is unavailable, log once and retry slowly.
- Attributes: `systemd.unit` or `container.name`, plus `host.name` from the resource.
- **G6** On shutdown: cancel all tasks via `state.shutdown`, then `force_flush` and `shutdown` each provider, with a bounded timeout.
- **G7** `dev/otelcol.yaml` with an OTLP receiver (grpc 4317, http 4318) and a `debug` exporter at `verbosity: detailed`. Add a devenv `processes.otelcol` entry, coordinating the `devenv.nix` edit with the P0 owner.
## Done when
- Verification #5 passes. With `[otel] enabled = true`, the collector shows the gauges every interval and log records with correct severity and attributes.
- `logger -p user.err test` appears as an ERROR record.
- Starting a new container shows its logs without restarting the service.
- SIGTERM flushes pending records before exit.
## Notes
- opentelemetry-rust marks metrics and logs Stable and traces Beta. Pin versions together, because the `opentelemetry*` crates must match each other.
- Cardinality: one series per unit or container per attribute set. With the DEC-7 default, expect a few hundred series on a typical host.
## Log
- 2026-10-15: Card created.