Twingate Connector Monitoring with Prometheus & Grafana

Complete Setup Guide: Twingate Monitoring with Prometheus & Grafana

This guide will walk you through setting up comprehensive monitoring for your Twingate deployment, from configuring metrics on your Connectors to visualizing data in Grafana dashboards.

Prerequisites

• Twingate deployment with at least one Connector
• Docker and Docker Compose installed
• Basic command line familiarity
• Network access to your Twingate Connectors

What You’ll Accomplish

By the end of this guide, you’ll have:

• Twingate Connectors exporting metrics
• Prometheus collecting and storing metrics
• Grafana dashboards visualizing your network performance
• A complete monitoring stack that scales with your deployment

Step 1: Enable Metrics on Twingate Connectors

Understanding Twingate Connector Metrics

Twingate Connectors can expose detailed metrics about their performance, including:

• Traffic metrics: Bytes transferred, and transfer rates
• Transport analytics: Direct vs relay connection breakdown
• Health indicators: Uptime, and resource counts

Enable Metrics Collection

To enable metrics on your Twingate Connectors, you need to configure each of them to expose the metrics endpoint by setting the TWINGATE_METRICS_PORT environment variable. Any unused port can be used.

Option A: Docker Connector Setup

If you’re running Twingate connectors via Docker, update your docker-compose.yml:

version: '3.8'
services:
  twingate-connector:
    image: twingate/connector:latest
    environment:
      - TWINGATE_ACCESS_TOKEN=your_access_token_here
      - TWINGATE_REFRESH_TOKEN=your_refresh_token_here
      - TWINGATE_URL=https://your-network.twingate.com
      - TWINGATE_METRICS_PORT=9999
    ports:
      - "9999:9999"  # Expose metrics port
    restart: unless-stopped

Option B: Linux Service Connector

For Connectors installed as Linux services, update the configuration:

• Edit the Connector configuration:

  Copy

  sudo nano /etc/twingate/connector.conf

• Add metrics configuration:

  Copy

  TWINGATE_METRICS_PORT=9999

• Restart the Connector service:

  Copy

  sudo systemctl restart twingate-connector

Verify Metrics Endpoint

Test that metrics are being exported:

# Replace <connector-ip> with your Connector's IP address
curl http://<connector-ip>:9999/metrics

# A file will download with a format of:
# twingate_inbound_bytes_total{transport="direct"} 1234567
# twingate_outbound_bytes_total{transport="relay"} 987654
# twingate_connector_uptime_seconds 86400

Step 2: Set Up Prometheus

Prometheus will collect and store metrics from your Twingate Connectors.

Create Prometheus Configuration

• Create a project directory:

  Copy

  mkdir twingate-monitoring
  cd twingate-monitoring

• Create Prometheus configuration (prometheus.yml):

  Copy

  global:
    scrape_interval: 15s
    evaluation_interval: 15s
  
  scrape_configs:
    - job_name: 'twingate-connectors'
      static_configs:
        - targets:
          # Add all your Connector IPs here
          - 'connector1-ip:9999'
          # - 'connector2-ip:9999'
          # - 'connector3-ip:9999'
      scrape_interval: 30s
      metrics_path: /metrics
      
    - job_name: 'prometheus'
      static_configs:
        - targets: ['localhost:9090']

• Create Docker Compose for monitoring stack (docker-compose.yml):

  Copy

  version: '3.8'
  
  services:
    prometheus:
      image: prom/prometheus:latest
      container_name: prometheus
      ports:
        - "9090:9090"
      volumes:
        - ./prometheus.yml:/etc/prometheus/prometheus.yml
        - prometheus_data:/prometheus
      command:
        - '--config.file=/etc/prometheus/prometheus.yml'
        - '--storage.tsdb.path=/prometheus'
        - '--web.console.libraries=/etc/prometheus/console_libraries'
        - '--web.console.templates=/etc/prometheus/consoles'
        - '--storage.tsdb.retention.time=200h'
        - '--web.enable-lifecycle'
      restart: unless-stopped
  
    grafana:
      image: grafana/grafana:latest
      container_name: grafana
      ports:
        - "3000:3000"
      environment:
        - GF_SECURITY_ADMIN_PASSWORD=admin123
        - GF_USERS_ALLOW_SIGN_UP=false
      volumes:
        - grafana_data:/var/lib/grafana
        - ./grafana/provisioning:/etc/grafana/provisioning
      restart: unless-stopped
      depends_on:
        - prometheus
  
  volumes:
    prometheus_data:
    grafana_data:

Start the Monitoring Stack

# Start Prometheus and Grafana
docker-compose up -d

# Verify services are running
docker-compose ps

# Check Prometheus is collecting metrics
curl http://localhost:9090/api/v1/targets

Step 3: Configure Grafana

Initial Grafana Setup

• Access Grafana:

  • Open http://localhost:3000 in your browser
  • Login with username: admin, password: admin123
  • (Optional) Change the admin password when prompted

• Add Prometheus Data Source:

  • Navigate to Configuration → Data Sources
  • Click Add data source
  • Select Prometheus
  • Set URL to: http://prometheus:9090
  • Click Save & Test (should show “Data source is working”)

Import Twingate Dashboards

Method 1: Direct JSON Import

• Download the dashboard:

  • Go to https://github.com/Twingate-Community/dashboards
  • Navigate to grafana/insights.json
  • Click Raw and save the file

• Import into Grafana:

  • In Grafana, go to Dashboards → Import
  • Click Upload JSON file and select your downloaded file
  • Select your Prometheus data source
  • Click Import

Method 2: Copy-Paste JSON

• Copy the JSON:

  • Go to the GitHub repository
  • Open grafana/insights.json
  • Copy all the JSON content

• Import via JSON:

  • In Grafana, go to Dashboards → Import
  • Paste the JSON content
  • Configure the Prometheus data source
  • Click Import

Step 4: Verify Your Setup

Check Data Flow

• Verify Prometheus is scraping:

  • Go to http://localhost:9090
  • Navigate to Status → Targets
  • Ensure all Twingate Connector targets are “UP”

• Test metric queries:

  • In Prometheus, go to Graph

  • Try queries like:

    Copy

    twingate_inbound_bytes_total
    twingate_outbound_bytes_total
    twingate_connector_uptime_seconds

• Verify Grafana dashboard:

  • Open your imported Twingate Insights dashboard
  • Check that all panels are displaying data
  • Adjust time range if needed (last 1 hour, 6 hours, etc.)

Troubleshooting Common Issues

No Data in Dashboard

Problem: Panels show “No data” or “N/A”

Solutions:

• Check Prometheus targets are UP: http://localhost:9090/targets
• Verify Connector metrics are accessible: curl http://connector-ip:9999/metrics
• Ensure firewall allows access to port 9999 on Connectors
• Check Prometheus logs: docker-compose logs prometheus

Connection Refused Errors

Problem: Cannot reach Connector metrics endpoint

Solutions:

• Verify Connector metrics are enabled in configuration
• Check if port 9999 is open: telnet connector-ip 9999
• Ensure Connector has been restarted after config changes
• Check Docker port mapping if using containerized Connectors

Dashboard Import Fails

Problem: JSON import shows errors

Solutions:

• Ensure you’re using a compatible Grafana version (12.2.1+)
• Verify that the Prometheus data source is properly configured
• Check the JSON file isn’t corrupted (valid JSON format)

Step 5: Customize and Scale

Adding More Connectors

To monitor additional Connectors, update prometheus.yml:

scrape_configs:
  - job_name: 'twingate-connectors'
    static_configs:
      - targets:
        - 'connector1-ip:9999'
        - 'connector2-ip:9999'
        - 'connector3-ip:9999'
        - 'connector4-ip:9999'
        # Add more as needed

Then restart Prometheus:

docker-compose restart prometheus

Setting Up Alerts

Create alerting rules in prometheus.yml:

rule_files:
  - "alerts.yml"

alerting:
  alertmanagers:
    - static_configs:
        - targets:
          - alertmanager:9093

Example alerts.yml:

groups:
  - name: twingate_alerts
    rules:
      - alert: ConnectorDown
        expr: up{job="twingate-connectors"} == 0
        for: 1m
        labels:
          severity: critical
        annotations:
          summary: "Twingate connector is down"
          description: "Connector {{ $labels.instance }} has been down for more than 1 minute."

You’re All Set!

Congratulations! You now have a complete Twingate monitoring setup. Your dashboard will show:

• Real-time traffic flow across all Connectors
• Transport method breakdown (direct vs relay connections)
• Performance metrics including uptime and resource utilization
• Historical trends for capacity planning and troubleshooting

Next Steps

• Set up alerting for proactive monitoring
• Create custom dashboards for specific use cases
• Contribute back to the community with your own dashboard creations
• Explore advanced Prometheus queries for deeper insights

Getting Help

• Issues with setup: Check our GitHub Issues
• Community support: Join discussions on our Reddit page
• Twingate documentation: Refer to official Twingate docs for Connector configuration

Happy monitoring!