Prometheus Metrics (1.0.0)

All API queries require a CacheFly API token passed via the Authorization header.

# Basic auth (username is ignored)
curl -u prometheus:YOUR_TOKEN 'https://api.cachefly.com/api/2.6/prometheus/api/v1/query?query=...'

# Bearer auth
curl -H "Authorization: Bearer YOUR_TOKEN" 'https://api.cachefly.com/api/2.6/prometheus/api/v1/query?query=...'

---

Metric	Type	Unit	Description
cachefly_edge_requests	Gauge	count	Requests served by the CDN at the edge
cachefly_edge_bytes	Gauge	bytes	Data volume served by the CDN at the edge
cachefly_origin_requests	Gauge	count	Requests made from CDN to origin
cachefly_origin_bytes	Gauge	bytes	Data retrieved from origins
cachefly_origin_ttfb_avg_seconds	Gauge	seconds	Average time to first byte
cachefly_origin_ttfb_max_seconds	Gauge	seconds	Highest time to first byte
cachefly_origin_ttfb_min_seconds	Gauge	seconds	Lowest time to first byte

---

These metrics represent traffic served by CacheFly's CDN at the edge (closest to end users).

Labels

Label	Type	Description	Example Values
suid	UInt32	Service ID	42648, 43085
hit	String	Whether the response was served from cache	true, false
pop	String	Point of presence (datacenter location)	AMS, LAX, FRA, SIN

---

cachefly_edge_requests

Type: Gauge Description: Number of requests served by the CDN at the edge.

This is the primary metric for understanding request volume hitting your CDN distribution. Each data point represents the number of requests in a given time bucket, broken down by service, cache status, and POP.

Example Queries

# Total edge requests
cachefly_edge_requests

# Requests for a specific service
cachefly_edge_requests{suid="43085"}

# Cache hits only
cachefly_edge_requests{hit="true"}

# Cache misses only
cachefly_edge_requests{hit="false"}

# Requests by POP
sum by (pop) (cachefly_edge_requests)

# Total requests across all labels
sum(cachefly_edge_requests)

Common Use Cases

• Traffic monitoring: Track overall request volume to your CDN.
• Cache hit ratio: Compare hit="true" vs hit="false" to measure cache effectiveness.
• POP distribution: Identify which edge locations serve the most traffic.

Cache Hit Ratio

# Overall cache hit ratio (0 to 1)
sum(cachefly_edge_requests{hit="true"}) / sum(cachefly_edge_requests)

# Cache hit ratio per service
sum by (suid) (cachefly_edge_requests{hit="true"}) / sum by (suid) (cachefly_edge_requests)

# Cache hit ratio per POP
sum by (pop) (cachefly_edge_requests{hit="true"}) / sum by (pop) (cachefly_edge_requests)

---

cachefly_edge_bytes

Type: Gauge Unit: bytes Description: Volume of data served by the CDN at the edge.

Tracks bandwidth consumption at the edge. Each data point represents the number of bytes transferred in a given time bucket.

Example Queries

# Total edge bandwidth
cachefly_edge_bytes

# Bandwidth for a specific service
cachefly_edge_bytes{suid="43085"}

# Bandwidth served from cache vs origin
sum by (hit) (cachefly_edge_bytes)

# Bandwidth by POP
sum by (pop) (cachefly_edge_bytes)

# Total bandwidth in GB (divide by 1e9)
sum(cachefly_edge_bytes) / 1e9

Common Use Cases

• Bandwidth monitoring: Track data transfer volume across your CDN.
• Cache bandwidth savings: Compare cached vs uncached bytes to quantify savings.
• POP bandwidth distribution: Identify which edge locations transfer the most data.

Bandwidth Savings from Cache

# Bytes saved by cache (served from cache instead of origin)
sum(cachefly_edge_bytes{hit="true"})

# Cache bandwidth ratio
sum(cachefly_edge_bytes{hit="true"}) / sum(cachefly_edge_bytes)

# Bandwidth per POP in MB
sum by (pop) (cachefly_edge_bytes) / 1e6

---

These metrics represent traffic between CacheFly's CDN and your origin server(s). High origin traffic generally means more cache misses.

Labels

Label	Type	Description	Example Values
suid	UInt32	Service ID	42648, 43085
status	UInt32	HTTP response status code	200, 301, 404, 502, 503

Supported status codes: 101, 200, 201, 301, 302, 304, 400, 401, 403, 404, 405, 421, 500, 501, 502, 503, 504

---

cachefly_origin_requests

Type: Gauge Description: Number of requests made from CDN to origin.

Tracks how many requests the CDN forwards to your origin server. A high number of origin requests relative to edge requests indicates poor cache hit rates.

Example Queries

# All origin requests
cachefly_origin_requests

# Origin requests by HTTP status
sum by (status) (cachefly_origin_requests)

# Only successful origin requests
cachefly_origin_requests{status="200"}

# Origin errors (5xx)
sum(cachefly_origin_requests{status=~"5.."})

# Origin client errors (4xx)
sum(cachefly_origin_requests{status=~"4.."})

# Origin 502 Bad Gateway errors
cachefly_origin_requests{status="502"}

# Origin requests for a specific service
cachefly_origin_requests{suid="42978"}

Common Use Cases

• Origin load monitoring: Track how much traffic your origin handles.
• Error detection: Alert on rising 5xx responses from origin.
• Cache tuning: High origin requests suggest caching rules need adjustment.

Origin Error Rate

# Origin error rate (5xx / total)
sum(cachefly_origin_requests{status=~"5.."}) / sum(cachefly_origin_requests)

# Origin error rate per service
sum by (suid) (cachefly_origin_requests{status=~"5.."}) / sum by (suid) (cachefly_origin_requests)

# Breakdown of error types
sum by (status) (cachefly_origin_requests{status=~"[45].."})

---

cachefly_origin_bytes

Type: Gauge Unit: bytes Description: Volume of data retrieved into the CDN from all origins.

Tracks how much data the CDN pulls from your origin servers.

Example Queries

# Total origin bandwidth
cachefly_origin_bytes

# Origin bandwidth by service
sum by (suid) (cachefly_origin_bytes)

# Origin bandwidth by HTTP status
sum by (status) (cachefly_origin_bytes)

# Origin bandwidth for successful requests in GB
sum(cachefly_origin_bytes{status="200"}) / 1e9

Common Use Cases

• Origin bandwidth costs: Monitor data transfer from origin.
• CDN offload ratio: Compare origin bytes vs edge bytes to measure CDN effectiveness.

Cache Byte Ratio

# Cache byte ratio (proportion of edge bytes served from cache)
sum(cachefly_edge_bytes{hit="true"}) / sum(cachefly_edge_bytes)

---

cachefly_origin_ttfb_avg_seconds

Type: Gauge Unit: seconds Description: Average time to first byte (TTFB) for requests made to the origin.

Measures the average time between the CDN sending a request to origin and receiving the first byte of the response. This is a key indicator of origin performance.

Example Queries

# Average TTFB across all origins
cachefly_origin_ttfb_avg_seconds

# Average TTFB by service
cachefly_origin_ttfb_avg_seconds{suid="42978"}

# Average TTFB by HTTP status
avg by (status) (cachefly_origin_ttfb_avg_seconds)

# Average TTFB for successful requests only
cachefly_origin_ttfb_avg_seconds{status="200"}

Common Use Cases

• Origin performance monitoring: Track how fast your origin responds.
• SLA compliance: Alert when average TTFB exceeds thresholds.
• Performance regression detection: Spot slowdowns over time.

---

cachefly_origin_ttfb_max_seconds

Type: Gauge Unit: seconds Description: Highest time to first byte (TTFB) for requests made to the origin.

Captures the worst-case TTFB within each time bucket. Useful for identifying tail latency and outlier slow responses.

Example Queries

# Worst-case TTFB
cachefly_origin_ttfb_max_seconds

# Max TTFB by service
max by (suid) (cachefly_origin_ttfb_max_seconds)

# Max TTFB for 200 responses
cachefly_origin_ttfb_max_seconds{status="200"}

# Services with max TTFB over 1 second
cachefly_origin_ttfb_max_seconds > 1

Common Use Cases

• Tail latency monitoring: Detect outlier slow responses from origin.
• Capacity planning: Persistent high max TTFB may indicate origin needs scaling.
• Alerting: Fire alerts when max TTFB spikes above acceptable thresholds.

---

cachefly_origin_ttfb_min_seconds

Type: Gauge Unit: seconds Description: Smallest time to first byte (TTFB) for requests made to the origin.

Captures the best-case TTFB within each time bucket. Useful as a baseline for what your origin is capable of.

Example Queries

# Best-case TTFB
cachefly_origin_ttfb_min_seconds

# Min TTFB by service
min by (suid) (cachefly_origin_ttfb_min_seconds)

# Compare min vs max TTFB to see variance
cachefly_origin_ttfb_max_seconds - cachefly_origin_ttfb_min_seconds

Common Use Cases

• Baseline performance: Understand the best possible origin response time.
• TTFB variance: Large gap between min and max indicates inconsistent origin performance.

---

Overall CDN Health Dashboard

# Cache hit ratio
sum(cachefly_edge_requests{hit="true"}) / sum(cachefly_edge_requests)

# Origin error rate
sum(cachefly_origin_requests{status=~"5.."}) / sum(cachefly_origin_requests)

# Average origin TTFB
avg(cachefly_origin_ttfb_avg_seconds{status="200"})

# Total edge throughput in Gbps (assuming 5-minute intervals)
sum(cachefly_edge_bytes) * 8 / 1e9

Per-Service Breakdown

# Edge requests per service
sum by (suid) (cachefly_edge_requests)

# Origin requests per service
sum by (suid) (cachefly_origin_requests)

# Cache hit ratio per service
sum by (suid) (cachefly_edge_requests{hit="true"}) / sum by (suid) (cachefly_edge_requests)

# Origin TTFB per service
avg by (suid) (cachefly_origin_ttfb_avg_seconds)

Alerting Examples

# Alert: cache hit ratio drops below 80%
sum(cachefly_edge_requests{hit="true"}) / sum(cachefly_edge_requests) < 0.8

# Alert: origin 5xx error rate exceeds 5%
sum(cachefly_origin_requests{status=~"5.."}) / sum(cachefly_origin_requests) > 0.05

# Alert: origin TTFB exceeds 2 seconds
cachefly_origin_ttfb_avg_seconds > 2

# Alert: max TTFB spike above 10 seconds
cachefly_origin_ttfb_max_seconds > 10

---

To add CacheFly as a Prometheus data source in Grafana:

1. Open Grafana and navigate to Data Sources.

2. Click Add data source and select Prometheus.

3. In the Connection section, set the URL:

   https://api.cachefly.com/api/2.6/prometheus/
   

4. In the Authentication section:

   Authentication Mode: Basic authentication
   Username: prometheus
   Password: <your-cachefly-api-token>
   

   You can generate a new API token in the CacheFly Portal.

5. Optionally, under Advanced settings:

   Manage alerts via Alerting UI: false
   Scrape interval: 15s
   Query timeout: 180s
   Prometheus type: Prometheus
   HTTP method: POST
   

Notes:

• Compatible with Prometheus version 3.1.
• The username field is ignored — only the token (password) matters.
• Both Basic and Bearer auth formats are supported. Basic is recommended for Grafana.

---

Endpoint	Method	Description
/api/v1/query	GET/POST	Instant query at a single point in time
/api/v1/query_range	GET/POST	Range query over a time window
/api/v1/labels	GET/POST	List all available label names
/api/v1/label/<name>/values	GET	List values for a specific label
/api/v1/metadata	GET	List all metric metadata
/-/healthy	GET	Health check
/-/ready	GET	Readiness probe

Range Query Parameters

Parameter	Description	Example
query	PromQL expression	cachefly_edge_requests{hit="true"}
start	Start timestamp (RFC3339 or unix)	2026-03-18T00:00:00Z
end	End timestamp (RFC3339 or unix)	2026-03-18T01:00:00Z
step	Query resolution step	5m, 1h, 30s