Fastly Dashboards for Prometheus and Grafana

A comprehensive, out-of-the-box monitoring and alerting solution for Fastly services.

This repository contains a Docker Compose setup that deploys a full monitoring stack, including: The Fastly Exporter for Prometheus, Prometheus, Alertmanager, and Grafana. It comes pre-loaded with a suite of dashboards and alerting rules, with built-in Slack integration.

Features

• Turnkey Setup: Launch a complete Fastly monitoring stack with a single command
• Comprehensive Dashboards: Visualize real-time and historical metrics with a rich set of pre-built Grafana dashboards
• Alerting: 21 pre-configured Prometheus alerts covering error rates and latency at account, POP, origin, and service scope
• Slack Integration: Receive timely alerts directly in your Slack workspace
• Customizable: Easily extend the dashboards and alerting rules to fit your specific needs

Dashboards

The following Grafana dashboards are provisioned automatically:

• Fastly Dashboard: High-level overview of all Fastly services
• Fastly Service: Detailed view of a single Fastly service
• Fastly Compute: Metrics for your Fastly Compute services
• Fastly Security: Security-related metrics, including WAF and TLS data
• Fastly Thresholds: Monitor against defined thresholds
• Top Services: Summary of your most active services
• Top POPs: A breakdown of your traffic by Fastly POP
• Top Origins: A summary of your most active origin servers
• Top Domains: A summary of your most active domains, from Domain Inspector

Top Domains needs your account to be entitled to Domain Inspector and the product enabled on the service. The exporter then polls it automatically, with no flag to set. Top Origins has the same relationship with Origin Inspector. Without the entitlement those two dashboards have no data to show, and the rest are unaffected.

Screenshots

Account-wide cache, traffic and bandwidth, with request rate per POP, from Fastly Dashboard:

One service in detail, with its cache and shielding breakdown, from Fastly Service:

Request volume, execution time and guest errors for Compute services, from Fastly Compute:

Traffic and errors split by Fastly POP, from Fastly Top POPs:

Per-origin ranking with a service and POP filter, from Fastly Top Origins:

Per-domain requests, bandwidth and edge hit ratio, from Fastly Top Domains:

The figures in these screenshots come from synthetic data, not a real Fastly account.

Alerting

The stack includes 21 pre-configured Prometheus alerting rules that are sent to Alertmanager and can be routed to Slack. The same five alerts are defined at each of four scopes, plus one demo alert:

Scope	Rule file	Alerts
Account	account.yml	4xx ratio, 5xx ratio, error ratio, p50 latency, p99 latency
POP	datacenter.yml	the same five, per Fastly POP
Origin	origin.yml	the same five, per origin
Service	service.yml	the same five, per service
Demo	demo.yml	one example alert

Each alert uses a hold-down timer and hysteresis so it does not flap, and fires only once the scope it watches passes a minimum level of traffic.

The remaining rule files define recording rules and no alerts: cache.yml, compute.yml, domain.yml, errors.yml, latency.yml, security.yml, thresholds.yml, and traffic.yml. They feed the dashboards, and give you ratios to build your own alerts on.

The rule and metric names keep the word datacenter, as in fastly_datacenter:4xx_ratio, because that is the label the exporter emits. POP and datacenter mean the same thing here.

You can customize and add your own rules in the prometheus/rules/ directory.

Stack Components

This project uses the following containerized services:

Service	Image	Version
Prometheus	prom/prometheus	v2.53.5
Alertmanager	prom/alertmanager	v0.28.1
Grafana	grafana/grafana	12.1
Fastly Exporter	ghcr.io/fastly/fastly-exporter	v10.3.0
Envsubst	bhgedigital/envsubst	latest

Getting Started

Prerequisites

• Docker and Docker Compose
• A Fastly API Token with global:read permissions.
• A Slack Incoming Webhook URL for alerts.

Configuration

1. Clone the repository:

   git clone https://github.com/fastly/fastly-dashboards.git
   cd fastly-dashboards

2. Export the required environment variables:

   export FASTLY_API_TOKEN="YOUR_FASTLY_TOKEN"
   export SLACK_API_URL="YOUR_SLACK_WEBHOOK_URL"
   export SLACK_CONFIG_CHANNEL="#your-slack-channel"

Running the Stack

Use docker compose (recommended) or docker-compose to launch the stack:

docker compose up -d

It may take a few minutes for all services to start and for data to be collected.

Accessing Grafana

Once the stack is running, you can access the Grafana dashboards at http://localhost:3000.

Login is disabled, and you will be granted anonymous admin access.

Troubleshooting

1. no configuration file provided: not found

This can happen if you are using Docker Snap, which requires that all files Docker needs access to live within your $HOME folder. Try running the project from a directory inside your home folder.

2. Graphs are broken and my system is dying!

Processing Fastly metrics can be resource-intensive, especially with many services. To reduce the load, you can configure the fastly-exporter to sample a fraction of your services using the FASTLY_EXPORTER_OPTIONS environment variable.

For example, to process metrics for 1/10th of your services:

export FASTLY_EXPORTER_OPTIONS="-service-shard 1/10"
docker compose up

3. No Slack Alerts

If you see an error like channel \"#NO_SLACK_CONFIG_CHANNEL\": unexpected status code 404: 404 page not found, it means your Slack integration is not configured correctly.

Ensure that the $SLACK_API_URL and $SLACK_CONFIG_CHANNEL environment variables are exported correctly before starting the stack.

---

Integrating with Existing Monitoring

If you already have an existing monitoring stack, you can integrate the configurations from this repository.

Prometheus

1. Scrape Configuration: Add the fastly-exporter job to your prometheus.yml:

- job_name: "fastly-exporter"
  static_configs:
    - targets: ["fastly-exporter:8080"]

Ensure the fastly-exporter container is reachable by your Prometheus instance.

2. Alerting Rules: Copy the rule files from the prometheus/rules/ directory to your Prometheus rules directory and update your prometheus.yml to load them:

rule_files:
  - "/path/to/your/rules/*.yml"

Alertmanager

1. Configuration: Add the slack-notifications receiver from alertmanager/alertmanager.yml to your Alertmanager configuration. You will also need to add the corresponding route.

2. Templates: Copy the template files from alertmanager/templates/ to your Alertmanager templates directory.

Grafana

1. Dashboards: Copy the dashboard JSON files from the grafana/provisioning/dashboards/ directory to your Grafana dashboards directory.

2. Provisioning: Configure Grafana to provision the dashboards. You can use the grafana/provisioning/dashboards/dashboard.yml as a reference.

3. Datasource: Ensure you have a Prometheus datasource configured in Grafana.

Credit

These official dashboards were inspired by the original fastly-dashboards project by @mrnetops. Their work was featured in the Magic tricks with Docker (or how to monitor Fastly in about five minutes) presentation at the Fastly Altitude conference in 2020.