Skip to content

Monitoring Setup

Every CompassVPN agent ships its metrics (via Grafana Alloy) to a Prometheus-compatible endpoint, and a ready-made Grafana dashboard visualizes them. The standard setup uses Grafana Cloud: its free tier is sufficient for monitoring several agents, and there is nothing to host or maintain.

If you prefer to run your own monitoring stack, see Self-Hosted Prometheus and Grafana below.

Grafana Cloud

Step 1: Create a Grafana Cloud Account

  1. Go to Grafana Cloud and sign up for a free account
  2. Verify your email address and complete the registration process

Step 2: Create a Connection Token

  1. After creating your account, go to the following URL (replace <your-username> with your actual Grafana Cloud username):

    https://<your-username>.grafana.net/connections/add-new-connection/hmInstancePromId

  2. Create a new token as shown in the image below:

    Grafana Cloud screen prompting the user to create a new connection token
    Figure 1: Creating a new connection token in Grafana Cloud.

  3. After creating the token, you’ll see three credentials as shown below:

    Grafana Cloud screen displaying the generated URL, username, and password credentials
    Figure 2: Copying the URL, username, and password credentials for agent configuration.

  4. Copy these three credentials:

    • URL
    • Username
    • Password

Step 3: Add the Credentials to Your Agent

  1. Open the env_file in the root of the agent directory (refer to the Quick Start Guide if needed).
  2. Set the three Alloy remote-write variables to the values you copied from Grafana Cloud:
    • ALLOY_REMOTE_WRITE_URL
    • ALLOY_REMOTE_WRITE_USER
    • ALLOY_REMOTE_WRITE_PASSWORD
  3. Apply the configuration by running sudo ./agent.sh start.

For detailed explanations of all parameters, see the Configuration Guide .

Step 4: Import the Dashboard

  1. In Grafana Cloud, navigate to Dashboards in the left sidebar
  2. Click the Import button
  3. Enter dashboard ID 23181 (the CompassVPN dashboard, also available on grafana.com )
  4. Select your Prometheus data source and click Import
Allow 5 to 10 minutes after the agent starts for metrics to populate the dashboard.

Self-Hosted Prometheus and Grafana

If you want complete control over your monitoring data, any Prometheus instance that accepts remote-write works in place of Grafana Cloud:

  1. Deploy Prometheus (with the remote-write receiver enabled and protected by basic auth) and Grafana. The Helm values the CompassVPN team uses on Kubernetes are available in the manager repository .
  2. In your agent’s env_file, set ALLOY_REMOTE_WRITE_URL to your Prometheus remote-write URL and ALLOY_REMOTE_WRITE_USER / ALLOY_REMOTE_WRITE_PASSWORD to your basic-auth credentials, then run sudo ./agent.sh start.
  3. In Grafana, import dashboard ID 23181 and select your Prometheus data source.
Your Prometheus instance must accept remote-write (enable the remote-write receiver). The agent pushes metrics through Grafana Alloy; nothing is scraped from outside the server.

Monitoring Multiple Agents

Any number of agents can report to the same endpoint. Each agent is identified by the DONOR value in its env_file; use the DONOR label as a filter variable in the dashboard to tell them apart.

Next Steps

Your CompassVPN installation is now complete. To connect client devices, see the User Guide .