Technical Documentation

How Synthmon's Distributed Monitoring Works

System Overview

Synthmon is a distributed synthetic monitoring platform that leverages a peer-to-peer network of agents to monitor website availability and performance from real-world locations. Unlike traditional monitoring services that rely on data center infrastructure, Synthmon uses a decentralized approach with Byzantine fault-tolerant consensus.

Key Innovations

Geographic Distribution

Agents run on real devices in real locations, providing authentic user perspective rather than data center views.

Consensus-Based Verification

Multiple agents verify each check, eliminating false positives through distributed consensus.

Community Powered

Anyone can run an agent and contribute to the network, earning points and future revenue share.

Architecture

Coordinator Service

Central orchestrator written in Go that manages monitors, schedules checks, and processes consensus results.

coordinator/main.go
type Coordinator struct {
  db        *sql.DB
  redis     *redis.Client
  scheduler *Scheduler
  consensus *ConsensusEngine
  alerts    *AlertManager
}

Agent Network

Lightweight Go binaries that run on user devices, perform checks, and submit signed results.

agent/worker.go
func (a *Agent) PerformHTTPCheck(url string) CheckResult {
  start := time.Now()
  resp, err := a.client.Get(url)
  duration := time.Since(start)
  
  return CheckResult{
    Success:      err == nil && resp.StatusCode < 400,
    StatusCode:   resp.StatusCode,
    ResponseTime: duration.Milliseconds(),
    Timestamp:    time.Now(),
  }
}

Data Layer

PostgreSQL for persistent storage and Redis for work queues and caching.

PostgreSQL Tables

  • • monitors
  • • agents
  • • scheduled_checks
  • • check_results
  • • incidents

Redis Keys

  • • agent:work:{{id}}
  • • agent:heartbeat:{{id}}
  • • check:results:{{id}}
  • • monitor:status:{{id}}

System Flow

  1. 1

    Monitor Creation

    User creates a monitor with URL, check interval (1-10 minutes), and alert settings.

  2. 2

    Check Scheduling

    Scheduler creates check tasks and assigns them to 3 agents in different geographic locations.

  3. 3

    Agent Execution

    Agents poll for work, perform checks, and submit cryptographically signed results.

  4. 4

    Consensus Processing

    Consensus engine analyzes results from multiple agents to determine true status.

  5. 5

    Status Update & Alerts

    Monitor status is updated and alerts are sent if thresholds are breached.

Consensus Algorithm

Synthmon uses a practical Byzantine fault-tolerant consensus algorithm to determine the true status of monitored endpoints. This approach eliminates false positives that plague traditional monitoring systems.

How It Works

  1. 1. Each check is assigned to exactly 3 agents
  2. 2. Agents perform checks independently and submit results
  3. 3. Consensus requires at least 2 matching results
  4. 4. Status is determined by majority vote
  5. 5. Response time is calculated as the average of successful checks
consensus_optimized.go
func (c *ConsensusEngine) DetermineConsensus(results []CheckResult) ConsensusResult {
  if len(results) < 2 {
    return ConsensusResult{Valid: false}
  }
  
  successCount := 0
  for _, result := range results {
    if result.Success {
      successCount++
    }
  }
  
  // Majority determines consensus
  consensusSuccess := successCount >= 2
  
  return ConsensusResult{
    Valid:        true,
    Success:      consensusSuccess,
    ResponseTime: calculateAvgResponseTime(results),
  }
}

Trust Score System

Agents maintain trust scores based on their reliability and agreement with consensus results:

  • 40% Overall Success Rate

    Long-term reliability across all checks

  • 40% Recent Success Rate

    Performance over last 100 checks

  • 20% Experience Factor

    Total checks performed (up to 1000)

Agent Network

The agent network is the backbone of Synthmon's distributed monitoring. Agents are lightweight Go binaries that can run on any platform.

Agent Capabilities

Current Features

  • ✓ HTTP/HTTPS monitoring
  • ✓ Response time measurement
  • ✓ Status code validation
  • ✓ SSL certificate checking
  • ✓ Custom headers support
  • ✓ Timeout handling

Coming Soon

  • • Browser automation (Playwright)
  • • Multi-step API testing
  • • Visual regression testing
  • • Performance metrics (Core Web Vitals)
  • • Custom scripting support

Running an Agent

Quick Start

curl -sSL https://synthmon.io/install.sh | bash

Docker

docker run -d --name synthmon-agent synthmon/agent:latest

Configuration

COORDINATOR_URL=https://api.synthmon.io
AGENT_NAME=my-agent
AGENT_LOCATION=US-EAST  # Auto-detected if not set

Incentive System

Current: Agents earn points for each successful check (10 points base reward)

Future: Revenue sharing model where agents earn a percentage of monitoring fees for premium features

Trust-Based Rewards: Higher trust scores lead to more work assignments and bonus multipliers

Security

Security is fundamental to Synthmon's architecture. Every component is designed with security-first principles.

Cryptographic Authentication

Agent Authentication

Every agent generates an Ed25519 keypair on registration. All communications are signed with the private key.

// Agent signs every request
signature := ed25519.Sign(agent.PrivateKey, payload)
request.Header.Set("X-Agent-Signature", base64.StdEncoding.EncodeToString(signature))

Result Integrity

Check results are signed to prevent tampering and ensure authenticity.

type SignedResult struct {
  Result    CheckResult
  AgentID   string
  Signature []byte
  Timestamp time.Time
}

Security Measures

  • Rate Limiting

    All API endpoints implement rate limiting to prevent abuse

  • Input Validation

    Strict validation of all user inputs and API parameters

  • Secure Communication

    All traffic encrypted with TLS 1.3

  • Isolation

    Agents run in isolated environments with minimal permissions

Integrations & Alerts

Synthmon provides real-time notifications when your monitors go down or recover. Configure multiple notification channels and customize alert messages using our rich template system.

🔔

Multiple Integrations Per Monitor

Send alerts to multiple channels simultaneously! Connect Slack, Discord, PagerDuty, and more to a single monitor with individual control over each integration.

✓ Unlimited integrations per monitor✓ Conditional routing✓ Individual thresholds
Read the Multiple Integrations Guide →

🔔Available Integrations

Slack

Send rich notifications to Slack channels with custom formatting

Discord

Post embed messages to Discord servers with color-coded alerts

Email Coming Soon

Send HTML emails via SMTP with full template customization

PagerDuty

Integrate with PagerDuty for incident management

Webhooks

Send custom HTTP requests to any endpoint

Setting Up Integrations

Quick Start

  1. 1. Navigate to Settings → Integrations in your dashboard
  2. 2. Click "Add Integration"
  3. 3. Select your notification channel (Slack, Discord, etc.)
  4. 4. Provide required credentials (webhook URL, API keys, etc.)
  5. 5. Customize alert templates using the Monaco editor
  6. 6. Test your integration with the built-in test feature
  7. 7. Link the integration to your monitors

Slack Integration

To set up Slack notifications:

  1. 1. Create an Incoming Webhook in your Slack workspace
  2. 2. Copy the webhook URL (starts with https://hooks.slack.com/)
  3. 3. Paste it in the Synthmon integration settings
  4. 4. Customize the message template for your needs
# Example Slack template
🔴 *{{.Monitor.Name}}* is {{.Incident.Type}}

*URL:* {{.Monitor.URL}}
*Status:* {{.Check.StatusCode}}
*Started:* {{.Incident.StartedAt.Format "15:04:05"}}

<{{.MonitorURL}}|View Details>

Discord Integration

To set up Discord notifications:

  1. 1. Go to Server Settings → Integrations → Webhooks
  2. 2. Create a new webhook and copy the URL
  3. 3. Add the webhook URL to Synthmon
  4. 4. Discord uses rich embeds with automatic color coding
Coming Soon

Email Integration

Email notifications via SMTP with HTML templates will be available in a future update.

Template System

Template Variables

All integrations support Go template syntax with rich data context:

{{.Monitor.Name}}        # Monitor name
{{.Monitor.URL}}         # Monitored URL
{{.Monitor.Type}}        # Monitor type (http, api, browser)
{{.Monitor.Interval}}    # Check interval in seconds

{{.Incident.Type}}       # "down" or "recovery"
{{.Incident.Status}}     # "open" or "resolved"
{{.Incident.StartedAt}}  # Incident start time
{{.Incident.Duration}}   # Human-readable duration

{{.Check.Success}}       # true/false
{{.Check.StatusCode}}    # HTTP status code
{{.Check.ResponseTime}}  # Response time in ms
{{.Check.ErrorType}}     # Error description

{{.DashboardURL}}        # Link to Synthmon dashboard
{{.MonitorURL}}          # Direct link to monitor details

Template Features

  • • Monaco Editor: VS Code-like editing experience with syntax highlighting
  • • Live Preview: See how your template renders with sample data
  • • Validation: Instant feedback on template syntax errors
  • • Default Templates: Start with sensible defaults for each integration type
  • • Time Formatting: Use Go's time format strings (e.g., "2006-01-02 15:04:05")
  • • Conditionals: Use if/else logic to customize messages

Best Practices

  • Test Before Production

    Always use the test feature to verify your integration works correctly

  • Separate Down/Recovery Alerts

    Configure different templates for incident and recovery notifications

  • Avoid Alert Fatigue

    Use appropriate check intervals and consider grouping related monitors

  • Include Context

    Add response times, error types, and direct links in your templates

API Reference

Synthmon provides a comprehensive REST API for all monitoring operations. Here are the key endpoints:

Monitor Management

POST /api/monitorsCreate monitor
{
  "name": "My Website",
  "url": "https://example.com",
  "type": "http",
  "check_interval": 300,
  "timeout": 30
}
GET /api/monitorsList monitors
DELETE /api/monitors/{{id}Delete monitor

Public Endpoints

GET /api/monitors/statsNetwork statistics
{
  "total_monitors": 78,
  "active_monitors": 78,
  "unique_urls": 76,
  "monitors_by_type": {"http": 76, "browser": 2},
  "health_status": {"up": 22, "down": 56},
  "checks_per_minute": 156
}
GET /api/agents/leaderboardAgent rankings

Agent Communication

POST /api/agent/registerRegister new agent
POST /api/agent/workRequest work assignment
POST /api/agent/resultSubmit check result

Integration Management

GET /api/integrationsList integrations
POST /api/integrationsCreate integration
{
  "name": "Team Slack",
  "type": "slack",
  "config": {
    "webhook_url": "https://hooks.slack.com/...",
    "message_template": "🔴 {{.Monitor.Name}} is down"
  }
}
PUT /api/integrations/{id}Update integration
DELETE /api/integrations/{id}Delete integration
POST /api/integrations/{id}/testTest integration
POST /api/monitors/{id}/integrationsLink integration to monitor
{
  "integration_id": "int_123",
  "alert_on_down": true,
  "alert_on_up": true
}

Future Development

Synthmon is actively evolving with ambitious plans for distributed monitoring capabilities.

Advanced Monitoring

  • • Browser automation with Playwright
  • • Multi-step API workflow testing
  • • GraphQL and WebSocket monitoring
  • • Performance metrics (Core Web Vitals)
  • • Visual regression testing

Network Evolution

  • • Blockchain-based verification
  • • Decentralized coordinator nodes
  • • IPFS for result storage
  • • Token-based incentive system
  • • DAO governance model

Get Involved

Synthmon is open source and welcomes contributions. Whether you're interested in running an agent, contributing code, or building on top of our platform, there's a place for you in our community.