Monitoring and Alerting for Tor Hidden Services

External monitoring services cannot reach .onion addresses. Self-hosted monitoring solutions that can be configured to use Tor SOCKS5 proxy include Uptime Kuma (supports custom HTTP headers, can be configured with a Tor SOCKS5 proxy via the proxy setting), custom cron-based curl scripts, and Prometheus blackbox exporter configured with a SOCKS5 proxy. Deploy the monitoring instance on a separate server (ideally in a different datacenter than the monitored hidden service) to avoid correlated failures. A monitoring VPS with Tor client installed runs periodic checks against the .onion address, alerting on failures via Telegram, email, or PagerDuty.

The Tor project provides a Prometheus exporter that exposes Tor daemon metrics including bandwidth utilization, circuit count, descriptor publication status, and connection pool statistics. Configure tor_exporter on the hidden service server and scrape from a Prometheus instance. Key metrics: tor_bandwidth_bytes_total (rate should match BandwidthRate), tor_circuit_total (active circuit count), tor_connection_total (open connections), tor_node_flags (confirms Guard/Stable/HSDir flags for relays). Alert on: bandwidth dropping to zero (process issue), circuit count spike (possible attack), descriptor publication failure (service may become unreachable).

Beyond Tor process health, the application backend requires its own monitoring. Standard Prometheus exporters for web servers (nginx_exporter), databases (postgres_exporter, mysql_exporter), and application frameworks expose application metrics. A /health endpoint returning 200 with basic status information is the standard pattern. Configure health checks to verify: web server responsiveness, database connectivity, cache (Redis) connectivity, and critical application functionality (user login path, content delivery path). Health check endpoints should be reachable over both the .onion interface (for end-to-end monitoring) and a local loopback interface (for direct backend monitoring).

Tor's control port provides rich data for monitoring circuit health. The control protocol's GETINFO circuit-status command returns current circuit states. Healthy hidden services show consistent introduction point circuit establishment. Persistent failure to build introduction point circuits indicates either a network issue or an attack. The onionoo project maintains a public API providing relay information that can be checked to confirm whether the guard nodes your hidden service uses are currently healthy. Alert on: introduction point circuit failures exceeding baseline, guard node downtime, unexpected changes in circuit topology that might indicate path manipulation.

Tor logs provide operational intelligence beyond what metrics capture. WARNING and ERROR level messages indicate configuration issues or attacks. Log patterns to monitor: repeated authentication failures (potential credential stuffing), unusual traffic volume spikes (DDoS or viral content), slow-log patterns indicating backend performance degradation, and Tor bootstrap failures indicating network connectivity issues. Use structured logging (JSON output from the application layer) to enable log aggregation in Grafana Loki or Elasticsearch. Alert on: error rate increase above baseline, authentication failure rate spike, and response time increase beyond threshold.