Edge Observability Reference

Edge observability is implemented via:

  • structured logs (log/slog)

  • Prometheus recorder (edge/metrics/prometheus.go)

  • OS-survival epoch evidence (edge/epoch)

Structured Log Events

Canonical log schema reference:

  • edge/LOG_SCHEMA.md

Examples of implemented event names:

  • edge.assurance.reduced

  • edge.quota.exceeded

  • edge.retry.exhausted

  • edge.os.update_detected

  • edge.os.reconstruction_started

  • edge.os.reconstruction_completed

Bounded statement: additional component logs may use service-level messages (relay: ..., transport: ...) in addition to edge.* event names.

Prometheus Metrics

Metric family names are underscore-delimited (edge_*).

Implemented families include:

  • storage/disk: edge_disk_used_bytes, edge_disk_ceiling_bytes

  • ingress/segments: edge_segments_received_total, edge_segments_dropped_total

  • relay lifecycle: edge_relay_delivery_state_changes_total, edge_relay_deadletter_total, edge_relay_success_condition_met_total

  • retry: edge_retry_attempts_total, edge_retry_exhausted_total

  • transport: edge_connections_accepted_total, edge_connections_rejected_total

  • assurance: edge_assurance_level

  • OS-survival lifecycle: edge_os_update_detected_total, edge_os_reconstruction_started_total, edge_os_reconstruction_duration_seconds, edge_os_reconstruction_failures_total

Per-peer metric cardinality is bounded by MaxPeerLabelCardinality; overflow labels are recorded under peer_id="_overflow".

Epoch Evidence

On successful reconstruction path, epoch rotation writes:

{state_root}/epoch/current/evidence.json
{state_root}/epoch/previous/evidence.json

Evidence fields in JSON:

  • os_fingerprint

  • binary_hash

  • config_hash

  • rotated_at

How To Verify

# 1) daemon health/status over control socket
./edge/edgectl --socket /run/edged/ctl.sock status

# 2) metrics endpoint (if --prometheus-addr configured)
curl -s http://127.0.0.1:9300/metrics | grep '^edge_'

# 3) reconstruction lifecycle logs
journalctl -u edged-precheck -n 200 --no-pager | grep -E 'edge\.os\.'

# 4) epoch evidence files
ls -R /var/lib/edge-state/epoch
cat /var/lib/edge-state/epoch/current/evidence.json

Evidence

Code:

  • edge/metrics/metrics.go

  • edge/metrics/prometheus.go

  • edge/LOG_SCHEMA.md

  • edge/cmd/edged/main.go (runPrecheck, runDaemon)

  • edge/epoch/epoch.go

Tests:

  • edge/metrics/prometheus_test.go

  • edge/cmd/edged/precheck_test.go

  • edge/epoch/epoch_test.go

Captured outputs:

  • docs/_generated/test-outputs/edged-integration.txt

  • docs/_generated/test-outputs/demo-output.txt