--- title: Monitoring with the Fastly Exporter for Prometheus summary: null url: https://www.fastly.com/documentation/reference/tools/fastly-exporter --- 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](https://www.fastly.com/documentation/reference/api/metrics-stats/realtime/) - Origin Inspector and Domain Inspector metrics on accounts entitled to those products - 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 - Filtering by service name and by metric name ## 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. ```term copy # 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](https://www.fastly.com/documentation/reference/api/metrics-stats/realtime/), automatically exposing all available metrics while providing powerful filtering capabilities. ```term copy nolinenums # 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. ```term copy nolinenums # 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=` An example Prometheus scrape config for the Fastly exporter follows. ```yaml 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.25+ (for source builds) - Docker (for containerized deployment) - Helm (for Helm chart installation) ### Method 1: Docker (Recommended) ```term copy nolinenums # 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 ```term copy nolinenums # 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 ```term copy nolinenums # 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 ```term copy nolinenums # 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](https://github.com/fastly/fastly-dashboards) repository. This provides a complete monitoring solution with Grafana dashboards and Slack alerting. ### Environment setup ```term copy nolinenums # 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 ```term copy nolinenums # 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: | Component | Port | Purpose | | ------------------- | ---- | --------------------------------- | | **Fastly Exporter** | 8080 | Metrics collection and exposition | | **Prometheus** | 9090 | Time-series database and alerting | | **Alertmanager** | 9093 | Alert routing and notification | | **Grafana** | 3000 | Visualization and dashboards | ### Access points - **Grafana Dashboard**: http://localhost:3000 (the login form is disabled and you're granted anonymous admin access, so restrict this port before running the stack anywhere shared) - **Prometheus**: http://localhost:9090 - **Alertmanager**: http://localhost:9093 - **Fastly Exporter Metrics**: http://localhost:8080/metrics ### Included dashboards The setup provides several pre-configured Grafana dashboards: - **Fastly Home:** an index linking to the others - **Fastly Dashboard:** account-wide traffic, cache and bandwidth - **Fastly Service:** per-service detail with a service picker - **Fastly Compute:** request volume, execution time and guest errors for Compute services - **Fastly Security:** WAF, bot and DDoS counters - **Fastly Thresholds & Health:** account error and latency ratios against alert thresholds - **Fastly Top Services:** ranking and comparison across services - **Fastly Top POPs:** per-POP traffic and errors - **Fastly Top Origins:** origin latency, status codes and bandwidth - **Fastly Top Domains:** per-domain traffic, cache hit ratio, errors and protocol mix Fastly Top Origins and Fastly Top Domains need the matching product entitlement, described below. Without it those two have no data to show, and the rest are unaffected. ### 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 POP metrics Example alert configuration: ```yaml # 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 }})' ``` ## Origin Inspector and Domain Inspector If your account is entitled to [Origin Inspector](https://docs.fastly.com/products/origin-inspector) or [Domain Inspector](https://docs.fastly.com/products/domain-inspector), the exporter polls their real-time APIs alongside the standard real-time stats and exports the results. This export runs automatically. At startup and then every `-product-refresh` interval (10 minutes by default), the exporter calls `GET https://api.fastly.com/entitled-products/{product}` for each product and starts one additional subscriber per service for each product the account can access. The log records this as `type=origin_inspector subscriber=create` and `type=domain_inspector subscriber=create`. Run with `-debug` to see the entitlement result itself: ```term nolinenums product=origin_inspector hasAccess=true ``` Both products are enabled per service, so services without the product enabled produce no origin or domain metrics. ### Origin Inspector metrics Origin metrics use the `origin` subsystem, so they're named `fastly_origin_*` under the default namespace. Every metric contains the labels `service_id`, `service_name`, `datacenter`, `origin`, and `source`. `source` is one of `delivery`, `compute`, or `waf`, identifying which part of the Fastly platform made the origin request. | Metric | Type | Additional labels | | --------------------------------------- | --------- | ----------------- | | `fastly_origin_responses_total` | counter | | | `fastly_origin_resp_body_bytes_total` | counter | | | `fastly_origin_resp_header_bytes_total` | counter | | | `fastly_origin_status_code_total` | counter | `status_code` | | `fastly_origin_status_group_total` | counter | `status_group` | | `fastly_origin_latency_seconds` | histogram | | ### Domain Inspector metrics Domain metrics use the `domain` subsystem, so they're named `fastly_domain_*`. Every metric contains the labels `service_id`, `service_name`, `datacenter`, and `domain`. | Metric | Type | Additional labels | | ---------------------------------------------- | ------- | ----------------- | | `fastly_domain_requests_total` | counter | | | `fastly_domain_edge_requests_total` | counter | | | `fastly_domain_edge_hit_requests_total` | counter | | | `fastly_domain_edge_miss_requests_total` | counter | | | `fastly_domain_edge_hit_ratio` | gauge | | | `fastly_domain_resp_body_bytes_total` | counter | | | `fastly_domain_resp_header_bytes_total` | counter | | | `fastly_domain_edge_resp_body_bytes_total` | counter | | | `fastly_domain_edge_resp_header_bytes_total` | counter | | | `fastly_domain_bereq_body_bytes_total` | counter | | | `fastly_domain_bereq_header_bytes_total` | counter | | | `fastly_domain_origin_fetches` | counter | | | `fastly_domain_origin_fetch_resp_body_bytes` | counter | | | `fastly_domain_origin_fetch_resp_header_bytes` | counter | | | `fastly_domain_origin_offload` | gauge | | | `fastly_domain_status_code_total` | counter | `status_code` | | `fastly_domain_status_group_total` | counter | `status_group` | | `fastly_domain_origin_status_code_total` | counter | `status_code` | | `fastly_domain_origin_status_group_total` | counter | `status_group` | | `fastly_domain_http2_total` | counter | | | `fastly_domain_http3_total` | counter | | | `fastly_domain_tls_total` | counter | `tls_version` | ### Controlling cardinality Origin metrics are emitted per POP, per origin, and per source. Domain metrics are emitted per POP and per domain. On a service with many origins or domains, this multiplies the size of the `/metrics` response by the number of Fastly POPs. The options below run from least to most aggressive. ```term copy nolinenums # Drop the per-POP breakdown and keep only aggregated values $ fastly-exporter -token XXX -aggregate-only # Keep origin metrics, drop domain metrics $ fastly-exporter -token XXX -metric-blocklist '^fastly_domain_' # Keep only the domain metrics you chart $ fastly-exporter -token XXX -metric-allowlist '^fastly_domain_(requests|edge_hit_ratio)' ``` ## 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 ```term copy nolinenums # 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 ```term copy nolinenums # 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 The exporter reads real-time stats from a long-polling endpoint, so there's no interval to tune for metrics collection itself. What you can adjust is how often it refreshes metadata from `api.fastly.com`, and the HTTP timeouts for each of the two hosts it talks to. ```term copy nolinenums # Use aggregate-only mode for large deployments $ fastly-exporter -token XXX -aggregate-only # Refresh the service list every 5 minutes instead of every minute (15s to 10m) $ fastly-exporter -token XXX -service-refresh 5m # Timeout for api.fastly.com requests (5s to 60s, default 15s) $ fastly-exporter -token XXX -api-timeout 30s # Timeout for rt.fastly.com requests (45s to 120s, default 45s) $ fastly-exporter -token XXX -rt-timeout 120s ``` Other refresh intervals follow the same pattern: `-product-refresh` for Origin Inspector and Domain Inspector entitlement, `-datacenter-refresh` for POP metadata, `-certificate-refresh` for TLS certificate metadata, and `-dictionary-refresh` for dictionary metadata. Run `fastly-exporter -h` for the full list with defaults and accepted ranges. ## Production considerations ### High availability setup For production deployments, consider running multiple exporter instances: ```term copy nolinenums # 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 ```term copy nolinenums # Check the token is valid and see its scopes $ curl -H "Fastly-Key: YOUR_TOKEN" https://api.fastly.com/tokens/self # Check the token can see the services you expect $ curl -H "Fastly-Key: YOUR_TOKEN" https://api.fastly.com/service ``` #### No metrics appearing ```term copy nolinenums # Check service discovery $ curl http://localhost:8080/sd # Verify service IDs $ curl http://localhost:8080/metrics?target=SERVICE_ID ``` #### High resource usage ```term copy nolinenums # 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 ```yaml # 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 ```term copy nolinenums # Enable debug logging $ fastly-exporter -token XXX -debug # List the endpoints the exporter serves, including one per discovered service $ curl http://localhost:8080/ # View raw Fastly API response $ curl -H "Fastly-Key: XXX" \ "https://rt.fastly.com/v1/channel/SERVICE_ID/ts/0" ``` The exporter serves `/`, `/metrics`, `/metrics?target=`, and `/sd`. There's no separate health endpoint. To check whether a given service is still reporting, read the `fastly_rt_last_successful_response` gauge from `/metrics`, which holds the Unix timestamp of the last response the exporter received for that service. ## Support and resources - **Official repository**: - **Dashboards repository**: - **Fastly metrics and stats API reference**: - **Prometheus documentation**: