1. Home
  2. Reference documentation
  3. Tools

Monitoring with the Fastly Exporter for Prometheus

The Fastly Exporter for Prometheus bridges the gap between Fastly's Real-time Analytics API and modern monitoring infrastructure. It transforms Fastly's real-time metrics into a Prometheus-compatible format, allowing easy monitoring for your edge infrastructure straight out of the box.

Key features:

  • Real-time metrics collection from Fastly's Real-Time Analytics API
  • Automatic service discovery and dynamic configuration
  • Prometheus metrics exposition with proper labeling
  • Support for service sharding across multiple exporters
  • Built-in HTTP service discovery for Prometheus
  • Comprehensive filtering and metric selection capabilities

Conveniently monitor your Fastly infrastructure

Zero-configuration service discovery

The Exporter automatically discovers all services visible to your API token, eliminating the need for manual service configuration. When you add new services to Fastly, they're immediately available in your monitoring stack without any configuration changes.

# Single command to monitor all your Fastly services
$ fastly-exporter -token YOUR_API_TOKEN

Intelligent metric management

Unlike traditional exporters that require explicit metric definitions, Fastly Exporter dynamically adapts to Fastly's Real-time Stats API, automatically exposing all available metrics while providing powerful filtering capabilities.

# Export only bandwidth-related metrics
$ fastly-exporter -token XXX -metric-allowlist 'bytes_total$'


# Exclude test services from monitoring
$ fastly-exporter -token XXX -service-blocklist '.*TEST.*'

Built-in scalability

The service sharding feature allows you to horizontally scale your monitoring infrastructure as your Fastly footprint grows, without complex load balancing configurations.

# Distribute load across 3 exporter instances
$ fastly-exporter -token XXX -service-shard 1/3
$ fastly-exporter -token XXX -service-shard 2/3
$ fastly-exporter -token XXX -service-shard 3/3

Native Prometheus integration

The exporter provides both aggregate metrics and per-service endpoints, plus HTTP service discovery that integrates seamlessly with Prometheus' native service discovery mechanisms. Per-service metrics are available via /metrics?target=<service ID> An example Prometheus scrape config for the Fastly exporter follows.

scrape_configs:
  - job_name: fastly-exporter
    http_sd_configs:
      - url: http://127.0.0.1:8080/sd
    relabel_configs:
      - source_labels: [__address__]
        target_label: __param_target
      - source_labels: [__param_target]
        target_label: service
      - target_label: __address__
        replacement: 127.0.0.1:8080

Production-ready deployment options

Multiple deployment methods are supported, from simple binary execution to Kubernetes Helm charts, making it easy to integrate into existing infrastructure. Both AMD64 and ARM64 environments are supported. The exporter acts as a bridge, polling Fastly's Real-time Analytics API and exposing the data in Prometheus format. It maintains service metadata and automatically handles service lifecycle changes.

Quick start

Prerequisites

Before using the Fastly Exporter for Prometheus, be sure you have the following prerequisites in place:

  • Fastly API Token with appropriate permissions
  • Go 1.23+ (for source builds)
  • Docker (for containerized deployment)
  • Helm (for Helm chart installation)
# Pull the latest image
$ docker pull ghcr.io/fastly/fastly-exporter:latest


# Run with your API token
$ docker run -p 8080:8080 \
  -e FASTLY_API_TOKEN=your_token_here \
  ghcr.io/fastly/fastly-exporter:latest

Method 2: binary installation

# Download from releases page or build from source
$ git clone https://github.com/fastly/fastly-exporter
$ cd fastly-exporter
$ go build ./cmd/fastly-exporter


# Run the exporter
$ ./fastly-exporter -token your_token_here

Method 3: Helm chart

# Add the prometheus-community helm repository
$ helm repo add prometheus-community https://prometheus-community.github.io/helm-charts
$ helm repo update


# Install the chart
$ helm upgrade --install fastly-exporter \
  prometheus-community/prometheus-fastly-exporter \
  --namespace monitoring \
  --set token="your_token_here"

Verify installation

# Check metrics endpoint
$ curl http://localhost:8080/metrics


# Check service discovery endpoint
$ curl http://localhost:8080/sd

Docker Compose full-stack setup

The most comprehensive way to get started is using the full-stack Docker Compose setup from the fastly-dashboards repository. This provides a complete monitoring solution with Grafana dashboards and Slack alerting.

Environment setup

# Export required environment variables
$ export FASTLY_API_TOKEN="your_fastly_api_token"
$ export SLACK_API_URL="https://hooks.slack.com/services/YOUR/SLACK/WEBHOOK"
$ export SLACK_CONFIG_CHANNEL="#your-alerts-channel"


# Optional: Limit services for testing
$ export FASTLY_EXPORTER_OPTIONS="-service-shard 1/10"

Quick deployment

# Clone the dashboards repository
$ git clone https://github.com/fastly/fastly-dashboards.git
$ cd fastly-dashboards


# Start the full stack
$ docker compose up

Stack components

The Docker Compose setup includes:

ComponentPortPurpose
Fastly Exporter8080Metrics collection and exposition
Prometheus9090Time-series database and alerting
Alertmanager9093Alert routing and notification
Grafana3000Visualization and dashboards

Access points

  • Grafana Dashboard: http://localhost:3000 (Default username and password is admin. Change it!)
  • Prometheus: http://localhost:9090
  • Alertmanager: http://localhost:9093
  • Fastly Exporter Metrics: http://localhost:8080/metrics

Included dashboards

The setup provides some useful pre-configured Grafana dashboards:

  • Fastly Service Overview: comprehensive service-level metrics
  • Fastly Top Services: ranking and comparison across services
  • Fastly Top Datacenters: geographic performance analysis
  • Fastly Top Origins: backend performance monitoring

Slack integration

The stack includes pre-configured Slack alerting for:

  • Account level metrics
  • High error rates (4xx/5xx responses)
  • Origin metrics
  • Service availability issues
  • Fastly datacenter metrics

Example alert configuration:

# Automatically configured in prometheus/rules/service.yml
 - alert: fastlyService4xxPercent
      expr: |
        (
          max_over_time(
            min_over_time(fastly_service:4xx_ratio[10m])[30m:15s]
          ) > fastly_service:4xx_warn_ratio
        ) and (
          fastly_service:criteria_warning_recently
          or count(fastly_service:alerts_recently{alertname="fastlyService4xxPercent"}) by (service_id,service_name)
        )
      labels:
        job: 'fastlyService'
        severity: warning
      annotations:
        description: 'High ({{- $value | humanizePercentage }})'

Configuration options

The Fastly Exporter for Prometheus can be configured to include or exclude only a specific set of services and metrics. It also has options to tune the performance based on your requirements.

Service filtering

# Include specific services only
$ fastly-exporter -token XXX -service service_id_1 -service service_id_2


# Include services matching regex
$ fastly-exporter -token XXX -service-allowlist '^Production'


# Exclude services matching regex
$ fastly-exporter -token XXX -service-blocklist '.*TEST.*|.*STAGING.*'

Metric filtering

# Export only specific metrics
$ fastly-exporter -token XXX -metric-allowlist 'requests_total$|bytes_total$'


# Exclude noisy metrics
$ fastly-exporter -token XXX -metric-blocklist 'imgopto|websocket'

Performance tuning

# Use aggregate-only mode for large deployments
$ fastly-exporter -token XXX -aggregate-only


# Adjust polling intervals
$ fastly-exporter -token XXX -poll-interval 30s


# Configure timeouts
$ fastly-exporter -token XXX -timeout 10s

Production considerations

High availability setup

For production deployments, consider running multiple exporter instances:

# Primary exporter
$ fastly-exporter -token XXX -service-shard 1/2 -listen :8080


# Secondary exporter
$ fastly-exporter -token XXX -service-shard 2/2 -listen :8081

API rate limiting

Fastly's API has rate limits. For large accounts:

  • Use service sharding to distribute load
  • Monitor API rate limit headers
  • Consider polling interval adjustments

Troubleshooting

Common issues

API token issues

# Test API token
$ curl -H "Fastly-Token: YOUR_TOKEN" https://api.fastly.com/stats/service


# Check token permissions
$ curl -H "Fastly-Token: YOUR_TOKEN" https://api.fastly.com/tokens/self

No metrics appearing

# Check service discovery
$ curl http://localhost:8080/sd


# Verify service IDs
$ curl http://localhost:8080/metrics?target=SERVICE_ID

High resource usage

# Use filtering to reduce load
$ fastly-exporter -token XXX -service-allowlist "^Production" -aggregate-only


# Check metrics cardinality
$ curl -s http://localhost:8080/metrics | wc -l

Prometheus scraping issues

# prometheus.yml debugging
scrape_configs:
  - job_name: 'fastly-exporter'
    scrape_interval: 30s
    scrape_timeout: 10s
    http_sd_configs:
      - url: 'http://fastly-exporter:8080/sd'
        refresh_interval: 60s

Debugging commands

# Enable debug logging
$ fastly-exporter -token XXX -debug


# Check exporter health
$ curl http://localhost:8080/health


# View raw Fastly API response
$ curl -H "Fastly-Token: XXX" \
  "https://rt.fastly.com/v1/channel/SERVICE_ID/ts/0"

Support and resources

Fastly
© Fastly 2025