Connection Monitor Phase 2: Traceroute burst capture

[itsDNNS]

Summary

Add on-demand and event-triggered traceroute capture to the Connection Monitor module, building on the always-on latency monitoring from #194.

Instead of storing continuous traceroute data (expensive), run traceroute bursts in specific situations to capture hop-level evidence when it matters most.

Trigger conditions

• Periodic schedule (slower interval, e.g. every 15-30 minutes)
• Alert threshold violations (outage detected, high packet loss)
• Route change suspicion (latency pattern shift)
• On-demand from the UI (manual trigger button)

Data to capture per trace

• Full hop list with hop index, host, IP
• Per-hop latency snapshots
• Timeout/missing hops
• Route fingerprint for change detection over time

Data model sketch

latency_traces

• id, target_id, timestamp, trigger_reason, hop_count, route_fingerprint

latency_trace_hops

• trace_id, hop_index, hop_host, hop_ip, latency_ms, timeout

UI

• Trace history view per target
• Route change timeline
• Per-hop latency visualization
• Manual "Run traceroute" button in detail view

Open questions

• Which traceroute method works reliably inside Docker (ICMP, UDP, TCP)?
• Shell-based (traceroute/tracert) vs Python library for parsing?
• Retention policy for trace data (separate from sample retention?)
• How to detect route changes reliably from fingerprints?

Depends on

• Add DOCSight-native always-on latency monitor for PingPlotter-style evidence gathering #194 (Phase 1 - merged)

[itsDNNS]

Update: Smart Capture (shipped in v2026-03-16.1/v2026-03-16.2) provides the trigger infrastructure this issue needs.

The Connection Monitor is already wired into the Smart Capture engine (#245). Events like cm_target_unreachable and cm_packet_loss_warning can trigger actions. Currently the only action adapter is Speedtest Tracker, but the adapter interface is designed for exactly this kind of extension.

Proposed approach:

1. Build a TracerouteAdapter as a second Smart Capture action adapter (action_type="traceroute")
2. Register it alongside the existing STT adapter in main.py
3. The adapter executes traceroute on trigger, stores results in latency_traces / latency_trace_hops tables
4. Link completed traces back to the Smart Capture execution via linked_result_id
5. Guardrails, execution history, audit trail, and correlation timeline integration come for free from the existing engine

What this means for the trigger conditions from the issue:

Trigger	Smart Capture coverage
Alert threshold violations (outage, packet loss)	Already wired: cm_target_unreachable, cm_packet_loss_warning
Periodic schedule	Not a Smart Capture pattern, keep as separate collector interval
Route change suspicion	Could be a new event type from Connection Monitor
On-demand from UI	Separate API endpoint, not Smart Capture

So Smart Capture covers the event-triggered bursts, while periodic and on-demand traces stay as standalone features in the Connection Monitor module.