Private probes

In addition to the public probes run by Grafana Labs, you can choose to install your own private probes. These are only accessible to you and only write data to your Grafana Cloud account. Private probes are instances of the open source Grafana Synthetic Monitoring Agent.

Make sure you have installed and configured Synthetic Monitoring before adding a private probe.

You can install multiple private probes. If you do, create a unique API key for each private probe.

Note: Installing from our APT repository on amd64-based Debian and Ubuntu systems is the only packaging option provided. The agent will need to be built from source on other systems.

Add a new probe in your Grafana instance

1. Navigate to Synthetic Monitoring > Probes.
2. Click New.
3. Enter a Probe Name.
4. Enter a Latitude and Longitude to see an accurate location on the map panel.
5. Enter a Region. Defaults are AMER, EMEA, and APAC, but you may define your own.
6. Optionally enter up to three custom labels to identify your probe.
7. Click Save.
8. Copy the Probe Authentication Token and save it for next step.

Probe API Server URL

Based on region of your stack, you need to use different Probe API server URL when setting up private probe.

For United States Region - synthetic-monitoring-grpc.grafana.net:443

For Europe Region - synthetic-monitoring-grpc-eu-west.grafana.net:443

If you are unsure about the region of your stack, check Synthetic Monitoring -> Config page. If Backend address contains eu-west in URL, your stack is in Europe Region, and you need to use Europe Region Probe API Server URL.

NOTE: You need to be Admin in Grafana to access Synthetic Monitoring config page

Install the agent on Ubuntu/Debian

You can install the agent using our official APT repository.

1. Add the required packages, and the repository GPG key:

   sudo apt install -y apt-transport-https
   sudo apt install -y software-properties-common wget
   wget -q -O - https://packages-sm.grafana.com/gpg.key | sudo apt-key add -
   

2. Add the repository for stable releases.

   echo "deb https://packages-sm.grafana.com/deb stable main" | sudo tee -a /etc/apt/sources.list.d/grafana.list
   

3. Run the following commands:

   sudo apt update
   sudo apt install synthetic-monitoring-agent
   

4. Configure the probe.

   1. Open /etc/synthetic-monitoring/synthetic-monitoring-agent.conf.
   2. Replace <YOUR TOKEN HERE> with the probe authentication token.
   3. Repleace API_SERVER with Probe API Server URL based on your stack region. (defaults to US region)
   4. Save the file.

5. Restart the agent:

   sudo service synthetic-monitoring-agent restart
   

The new probe appears on your Synthetic Monitoring > Probes page.

Deploy the agent using Docker

You can find the Synthetic Monitoring Agent docker image on Docker Hub

1. Pull image from Docker Hub.

   docker pull grafana/synthetic-monitoring-agent:latest
   

2. Export required config as environment variables.

   Replace <YOUR TOKEN> with the probe authentication token. Replace <PROBE_API_SERVER_URL> with Probe API Server URL based on your stack region.

   export API_TOKEN=<YOUR_TOKEN>
   export API_SERVER="<PROBE_API_SERVER_URL>"
   

3. Start the agent.

   docker run grafana/synthetic-monitoring-agent --api-server-address=${API_SERVER} --api-token=${API_TOKEN} --verbose=true
   

The new probe appears on your Synthetic Monitoring > Probes page.

Deployment with Kubernetes

Synthetic Monitoring Agent can be deployed to Kubernetes using Synthetic Monitoring Agent Docker image

We maintain a Kubernetes deployment example in agent repo.

We will be using these files to deploy Synthetic Monitoring Agent in a Kubernetes namespace.

1. Get deployment files.

   wget https://raw.githubusercontent.com/grafana/synthetic-monitoring-agent/master/examples/kubernetes/namespace.yaml
   wget https://raw.githubusercontent.com/grafana/synthetic-monitoring-agent/master/examples/kubernetes/secret.yaml
   wget https://raw.githubusercontent.com/grafana/synthetic-monitoring-agent/master/examples/kubernetes/deployment.yaml
   

2. Create the synthetic-monitoring namespace.

   kubectl apply -f namespace.yaml
   

3. Create a secret with Probe Authentication Token.

   Replace <YOUR_TOKEN> in secret.yaml with your Probe Authentication Token. Replace <PROBE_API_SERVER_URL> in secret.yaml with Probe API Server URL based on your stack region.

   kubectl apply -f secret.yaml
   
   # verify secret
   kubectl get secrets -n synthetic-monitoring
   

4. Deploy the Synthetic Monitoring Agent.

   kubectl apply -f deployment.yaml
   

The new probe appears on your Synthetic Monitoring > Probes page.

Troubleshooting Private Probes

If you are facing problems with your private probes, check the following:

1. Check the probe version (use -version flag) and make sure you are running a supported version.
2. Make sure the probe has a valid probe access token.
3. Make sure the probe is able to connect to the Synthetic Monitoring API server.
4. Run the Synthetic Monitoring Agent in debug mode (use the -debug and -verbose flags), and check for errors in the logs.
5. Check the Synthetic Monitoring Agent metrics. The default address for Synthetic Monitoring Agent Prometheus metrics is localhost:4050/metrics

If you are still facing issues with Private Probes, ask for help in the community forum. See Account types and support available for Grafana Cloud users for more information.

Production Deployments

The Agent process exposes Prometheus-style metrics on an HTTP server running on port 4050 (/metrics endpoint).

You can scrape and monitor your private probe in this way using either Prometheus or the Grafana Agent.

Next steps

You must reconfigure any existing checks to use your new probe even if you selected all probes when initially creating the check.

Synthetic Monitoring Agent is open-source, and [avaliable on GitHub][https://www.github.com/grafana/synthetic-monitoring-agent).