max / makenotwork

Add tracing spans to API handlers and module docs across the tree Audit Run-18 Obs B+ / Docs B+. api.rs had no #[instrument] at all, so request handling produced no spans and only the db/tools/peer-spawn layers were traceable. Instrument every handler plus build_target_status, and peer.rs heartbeat_loop. Fields are kept to bounded-cardinality values: target names come from the config, so they are a fixed set. State and pools are skipped. Add //! headers to the 33 modules that lacked them. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: Max Johnson <me@maxj.phd> · 2026-07-20 19:25 UTC

Commit: 451794c0fa57e085690279ab47c8e4e2963e6521

Parent: 63efc42

35 files changed, +89 insertions, -0 deletions

M pom/src/api.rs +9

			@@ -10,6 +10,7 @@ use axum::response::IntoResponse;
10	10		use axum::routing::get;
11	11		use axum::{Json, Router};
12	12		use serde::Serialize;
	13	+	use tracing::instrument;
13	14
14	15		use crate::checks::drift::{compute_test_staleness, detect_test_duration_drift};
15	16		use crate::config::Config;
			@@ -150,6 +151,7 @@ async fn require_bearer_token(
150	151
151	152		/// `GET /api/health` — simple health endpoint for PoM itself.
152	153		/// Not behind auth — allows external monitoring without credentials.
	154	+	#[instrument]
153	155		async fn self_health() -> impl IntoResponse {
154	156		Json(serde_json::json!({
155	157		"status": "operational",
			@@ -298,6 +300,7 @@ impl From<HealthSnapshot> for SnapshotJson {
298	300		}
299	301
300	302		/// Build a `TargetStatus` for a single target.
	303	+	#[instrument(skip_all, fields(target = %name))]
301	304		async fn build_target_status(
302	305		pool: &sqlx::SqlitePool,
303	306		name: &str,
			@@ -444,6 +447,7 @@ async fn build_target_status(
444	447		}
445	448
446	449		/// `GET /api/status` — JSON summary for all targets.
	450	+	#[instrument(skip_all)]
447	451		async fn status_all(
448	452		AxumState(state): AxumState<ApiState>,
449	453		) -> impl IntoResponse {
			@@ -460,6 +464,7 @@ async fn status_all(
460	464		}
461	465
462	466		/// `GET /api/status/{target}` — JSON summary for a single target.
	467	+	#[instrument(skip_all, fields(target = %target))]
463	468		async fn status_target(
464	469		AxumState(state): AxumState<ApiState>,
465	470		Path(target): Path<String>,
			@@ -477,6 +482,7 @@ async fn status_target(
477	482		// --- Peer endpoints ---
478	483
479	484		/// `GET /api/peer/info` — Returns this instance's identity info.
	485	+	#[instrument(skip_all)]
480	486		async fn peer_info(
481	487		AxumState(state): AxumState<ApiState>,
482	488		) -> impl IntoResponse {
			@@ -491,6 +497,7 @@ async fn peer_info(
491	497		}
492	498
493	499		/// `GET /api/peer/status` — This instance's full view: own info + target statuses + peer summaries.
	500	+	#[instrument(skip_all)]
494	501		async fn peer_status(
495	502		AxumState(state): AxumState<ApiState>,
496	503		) -> impl IntoResponse {
			@@ -537,6 +544,7 @@ async fn peer_status(
537	544		}
538	545
539	546		/// `GET /api/mesh` — Aggregated view: self + each peer's cached status.
	547	+	#[instrument(skip_all)]
540	548		async fn mesh_view(
541	549		AxumState(state): AxumState<ApiState>,
542	550		) -> impl IntoResponse {
			@@ -673,6 +681,7 @@ struct TrendResponse {
673	681		}
674	682
675	683		/// `GET /api/trends/{target}?hours=24&bucket_minutes=60` — latency trend data.
	684	+	#[instrument(skip_all, fields(target = %target))]
676	685		async fn trends(
677	686		AxumState(state): AxumState<ApiState>,
678	687		Path(target): Path<String>,

M pom/src/checks/http.rs +3

			@@ -1,3 +1,6 @@
	1	+	//! HTTP health probing: issues the request, applies the configured JSON
	2	+	//! expectations, and classifies the response into a `HealthStatus`.
	3	+
1	4		use std::time::Instant;
2	5
3	6		use tracing::instrument;

M pom/src/checks/mod.rs +3

			@@ -1,3 +1,6 @@
	1	+	//! Check implementations, one module per probe kind: health, TLS, DNS, WHOIS,
	2	+	//! routes, CORS, backups, SSH, port scans, plus latency-drift analysis.
	3	+
1	4		pub mod backup;
2	5		pub mod cors;
3	6		pub mod dns;

M pom/src/checks/parse.rs +3

			@@ -1,3 +1,6 @@
	1	+	//! Parsers for CI test output. Turns raw `cargo test` text into a structured
	2	+	//! `TestSummary` and per-test `TestDetail` records.
	3	+
1	4		use crate::types::{StepResult, TestDetail, TestSummary};
2	5
3	6		/// Parse run-ci.sh output into a structured TestSummary.

M pom/src/checks/ssh.rs +3

			@@ -1,3 +1,6 @@
	1	+	//! Remote test execution over SSH. Validates the test filter, runs the target's
	2	+	//! configured command, and parses the output into a `TestRun`.
	3	+
1	4		use tokio::process::Command;
2	5		use tracing::instrument;
3	6

M pom/src/cli/incident.rs +3

			@@ -1,3 +1,6 @@
	1	+	//! Incident state machine: decides whether a confirmed health transition should
	2	+	//! open, close, or close-and-open an incident.
	3	+
1	4		use pom::types::HealthStatus;
2	5
3	6		#[derive(Debug, PartialEq, Eq)]

M pom/src/cli/serve.rs +2

			@@ -1,3 +1,5 @@
	1	+	//! `pom serve`: starts the API/dashboard server and every background check task.
	2	+
1	3		use tokio::task::JoinHandle;
2	4		use tracing::info;
3	5

M pom/src/cli/status.rs +2

			@@ -1,3 +1,5 @@
	1	+	//! `pom status`: one-shot status summary across all configured targets.
	2	+
1	3		use pom::checks::drift;
2	4		use pom::config::Config;
3	5		use pom::db;

M pom/src/cli/tasks/backup.rs +2

			@@ -1,3 +1,5 @@
	1	+	//! Background backup freshness check task.
	2	+
1	3		use tokio::task::JoinHandle;
2	4		use tracing::info;
3	5

M pom/src/cli/tasks/cors.rs +2

			@@ -1,3 +1,5 @@
	1	+	//! Background CORS preflight check task.
	2	+
1	3		use tokio::task::JoinHandle;
2	4		use tracing::info;
3	5

M pom/src/cli/tasks/dns.rs +2

			@@ -1,3 +1,5 @@
	1	+	//! Background DNS record check task.
	2	+
1	3		use tokio::task::JoinHandle;
2	4		use tracing::info;
3	5

M pom/src/cli/tasks/health.rs +3

			@@ -1,3 +1,6 @@
	1	+	//! Background health and SSH-banner check tasks, including the transition gate,
	2	+	//! incident bookkeeping, and latency-drift alerting.
	3	+
1	4		use tokio::task::JoinHandle;
2	5		use tracing::info;
3	6

M pom/src/cli/tasks/meta_alert.rs +2

			@@ -1,3 +1,5 @@
	1	+	//! Background task that drains the pending-alert retry queue.
	2	+
1	3		use tokio::task::JoinHandle;
2	4		use tracing::info;
3	5

M pom/src/cli/tasks/mod.rs +2

			@@ -1,3 +1,5 @@
	1	+	//! Background check tasks spawned by `pom serve`, one spawner per check kind.
	2	+
1	3		mod backup;
2	4		mod cors;
3	5		mod dns;

M pom/src/cli/tasks/prune.rs +2

			@@ -1,3 +1,5 @@
	1	+	//! Background retention task that periodically prunes old records.
	2	+
1	3		use tokio::task::JoinHandle;
2	4		use tracing::info;
3	5

M pom/src/cli/tasks/routes.rs +2

			@@ -1,3 +1,5 @@
	1	+	//! Background route check task.
	2	+
1	3		use tokio::task::JoinHandle;
2	4		use tracing::info;
3	5

M pom/src/cli/tasks/tls.rs +2

			@@ -1,3 +1,5 @@
	1	+	//! Background TLS certificate check task.
	2	+
1	3		use tokio::task::JoinHandle;
2	4		use tracing::info;
3	5

M pom/src/cli/tasks/whois.rs +2

			@@ -1,3 +1,5 @@
	1	+	//! Background WHOIS/domain-expiry check task.
	2	+
1	3		use tokio::task::JoinHandle;
2	4		use tracing::info;
3	5

M pom/src/db/alerts.rs +3

			@@ -1,3 +1,6 @@
	1	+	//! Alert history (for cooldown checks) and the pending-alert retry queue that
	2	+	//! backs delivery to Postmark, WAM, and MNW.
	3	+
1	4		use super::*;
2	5		use tracing::instrument;
3	6

M pom/src/db/backup.rs +2

			@@ -1,3 +1,5 @@
	1	+	//! Database backup freshness check storage.
	2	+
1	3		use super::*;
2	4		use tracing::instrument;
3	5

M pom/src/db/cors.rs +2

M pom/src/db/dns.rs +2

M pom/src/db/health.rs +3

M pom/src/db/incidents.rs +3

M pom/src/db/maintenance.rs +3

M pom/src/db/migrations.rs +4

M pom/src/db/peers.rs +2

M pom/src/db/routes.rs +2

M pom/src/db/test_runs.rs +3

M pom/src/db/tls.rs +2

M pom/src/db/whois.rs +2

M pom/src/peer.rs +1

M pom/src/tools/health.rs +2

M pom/src/tools/mod.rs +2

M pom/src/tools/tests.rs +2