Merge pull request #193 from Kaitou786/tk/add-cf-edge-error-by-path

Add opt-in cloudflare_zone_edge_errors_by_path metric

Author: haad

README.md

@@ -67,6 +67,7 @@ The exporter can be configured using env variables or command flags.
 | `SCRAPE_INTERVAL` | scrape interval in seconds (will query cloudflare every SCRAPE_INTERVAL seconds), default `60` |
 | `METRICS_DENYLIST` | (Optional) cloudflare-exporter metrics to not export, comma delimited list of cloudflare-exporter metrics. If not set, all metrics are exported |
 | `ENABLE_PPROF` | (Optional) enable pprof profiling endpoints at `/debug/pprof/`. Accepts `true` or `false`, default `false`. **Warning**: Only enable in development/debugging environments |
+| `ENABLE_EDGE_ERRORS_BY_PATH` | (Optional) enable edge errors by path metric. Accepts `true` or `false`, default `false`. See [Edge Errors by Path Metric](#edge-errors-by-path-metric-opt-in) |
 | `ZONE_<NAME>` |  `DEPRECATED since 0.0.5` (optional) Zone ID. Add zones you want to scrape by adding env vars in this format. You can find the zone ids in Cloudflare dashboards. |
 | `LOG_LEVEL` | Set loglevel. Options are error, warn, info, debug. default `error` |
 
@@ -86,6 +87,7 @@ Corresponding flags:
   -scrape_interval=60: scrape interval in seconds, defaults to 60
   -metrics_denylist="": cloudflare-exporter metrics to not export, comma delimited list
   -enable_pprof=false: enable pprof profiling endpoints at /debug/pprof/
+  -enable_edge_errors_by_path=false: enable edge errors by path metric (high cardinality, opt-in)
   -log_level="error": log level(error,warn,info,debug)
 ```
 
@@ -119,6 +121,7 @@ Note: `ZONE_<name>` configuration is not supported as flag.
 # HELP cloudflare_zone_requests_status_country_host Count of requests for zone per edge HTTP status per country per host
 # HELP cloudflare_zone_requests_browser_map_page_views_count Number of successful requests for HTML pages per zone
 # HELP cloudflare_zone_requests_total Number of requests for zone
+# HELP cloudflare_zone_edge_errors_by_path Number of edge errors (4xx and 5xx) by request path
 # HELP cloudflare_zone_threats_country Threats per zone per country
 # HELP cloudflare_zone_threats_total Threats per zone
 # HELP cloudflare_zone_uniques_total Uniques per zone
@@ -131,6 +134,14 @@ Note: `ZONE_<name>` configuration is not supported as flag.
 # HELP cloudflare_r2_storage_total_bytes Total storage used by R2
 ```
 
+### Edge Errors by Path Metric (Opt-in)
+
+The `cloudflare_zone_edge_errors_by_path` metric tracks edge errors (4xx/5xx) by request path. This enables path-based filtering in alerts to exclude known-noisy endpoints while catching real issues.
+
+**Disabled by default** due to high cardinality. Enable with `ENABLE_EDGE_ERRORS_BY_PATH=true`.
+
+Paths are normalized to reduce cardinality (e.g., `/users/123` → `/users/:id`, UUIDs → `:uuid`).
+
 ## Helm chart repository
 
 To deploy the exporter into Kubernetes, we recommend using our manager Helm repository:

cloudflare.go

@@ -85,6 +85,24 @@ type cloudflareResponseLogpushZone struct {
 	} `json:"viewer"`
 }
 
+type cloudflareResponseEdgeErrorsByPath struct {
+	Viewer struct {
+		Zones []zoneRespEdgeErrorsByPath `json:"zones"`
+	} `json:"viewer"`
+}
+
+type zoneRespEdgeErrorsByPath struct {
+	ZoneTag                    string `json:"zoneTag"`
+	HTTPRequestsAdaptiveGroups []struct {
+		Count      uint64 `json:"count"`
+		Dimensions struct {
+			EdgeResponseStatus    uint16 `json:"edgeResponseStatus"`
+			ClientRequestHTTPHost string `json:"clientRequestHTTPHost"`
+			ClientRequestPath     string `json:"clientRequestPath"`
+		} `json:"dimensions"`
+	} `json:"httpRequestsAdaptiveGroups"`
+}
+
 type logpushResponse struct {
 	LogpushHealthAdaptiveGroups []struct {
 		Count uint64 `json:"count"`
@@ -861,6 +879,53 @@ func fetchLogpushZone(zoneIDs []string) (*cloudflareResponseLogpushZone, error)
 	return &resp, nil
 }
 
+func fetchEdgeErrorsByPath(zoneIDs []string) (*cloudflareResponseEdgeErrorsByPath, error) {
+	request := graphql.NewRequest(`
+	query ($zoneIDs: [String!], $mintime: Time!, $maxtime: Time!, $limit: Int!) {
+		viewer {
+			zones(filter: { zoneTag_in: $zoneIDs }) {
+				zoneTag
+				httpRequestsAdaptiveGroups(
+					limit: $limit
+					filter: {
+						datetime_geq: $mintime
+						datetime_lt: $maxtime
+						edgeResponseStatus_geq: 400
+					}
+				) {
+					count
+					dimensions {
+						edgeResponseStatus
+						clientRequestHTTPHost
+						clientRequestPath
+					}
+				}
+			}
+		}
+	}
+`)
+
+	now, now1mAgo := GetTimeRange()
+	request.Var("limit", gqlQueryLimit)
+	request.Var("maxtime", now)
+	request.Var("mintime", now1mAgo)
+	request.Var("zoneIDs", zoneIDs)
+
+	gql.Mu.RLock()
+	defer gql.Mu.RUnlock()
+
+	ctx, cancel := context.WithTimeout(context.Background(), cftimeout)
+	defer cancel()
+
+	var resp cloudflareResponseEdgeErrorsByPath
+	if err := gql.Client.Run(ctx, request, &resp); err != nil {
+		log.Errorf("failed to fetch edge errors by path, err:%v", err)
+		return nil, err
+	}
+
+	return &resp, nil
+}
+
 func fetchR2Account(accountID string) (*cloudflareResponseR2Account, error) {
 	request := graphql.NewRequest(`query($accountID: String!, $limit: Int!, $date: String!) {
 		viewer {

main.go

@@ -146,6 +146,9 @@ func fetchMetrics() {
 
 		wg.Add(1)
 		go fetchLogpushAnalyticsForZone(filteredZones, &wg)
+
+		wg.Add(1)
+		go fetchEdgeErrorsByPathAnalytics(filteredZones, &wg)
 	} else if zoneCount > cfgraphqlreqlimit {
 		for s := 0; s < zoneCount; s += cfgraphqlreqlimit {
 			e := s + cfgraphqlreqlimit
@@ -163,6 +166,9 @@ func fetchMetrics() {
 
 			wg.Add(1)
 			go fetchLogpushAnalyticsForZone(filteredZones[s:e], &wg)
+
+			wg.Add(1)
+			go fetchEdgeErrorsByPathAnalytics(filteredZones[s:e], &wg)
 		}
 	}
 
@@ -287,6 +293,10 @@ func main() {
 	viper.BindEnv("enable_pprof")
 	viper.SetDefault("enable_pprof", false)
 
+	flags.Bool("enable_edge_errors_by_path", false, "enable edge errors by path metric (high cardinality)")
+	viper.BindEnv("enable_edge_errors_by_path")
+	viper.SetDefault("enable_edge_errors_by_path", false)
+
 	viper.BindPFlags(flags)
 
 	logLevel := viper.GetString("log_level")

prometheus.go

@@ -63,6 +63,7 @@ const (
 	tunnelHealthStatusMetricName                    MetricName = "cloudflare_tunnel_health_status"
 	tunnelConnectorInfoMetricName                   MetricName = "cloudflare_tunnel_connector_info"
 	tunnelConnectorActiveConnectionsMetricName      MetricName = "cloudflare_tunnel_connector_active_connections"
+	zoneEdgeErrorsByPathMetricName                  MetricName = "cloudflare_zone_edge_errors_by_path"
 )
 
 type MetricsSet map[MetricName]struct{}
@@ -334,6 +335,11 @@ var (
 		Name: tunnelConnectorActiveConnectionsMetricName.String(),
 		Help: "Reports number of active connections for a Cloudflare Tunnel connector",
 	}, []string{"account", "tunnel_id", "client_id"})
+
+	zoneEdgeErrorsByPath = prometheus.NewCounterVec(prometheus.CounterOpts{
+		Name: zoneEdgeErrorsByPathMetricName.String(),
+		Help: "Number of edge errors (4xx and 5xx) by request path",
+	}, []string{"zone", "account", "status", "host", "path"})
 )
 
 func buildAllMetricsSet() MetricsSet {
@@ -377,6 +383,7 @@ func buildAllMetricsSet() MetricsSet {
 	allMetricsSet.Add(tunnelHealthStatusMetricName)
 	allMetricsSet.Add(tunnelConnectorInfoMetricName)
 	allMetricsSet.Add(tunnelConnectorActiveConnectionsMetricName)
+	allMetricsSet.Add(zoneEdgeErrorsByPathMetricName)
 	return allMetricsSet
 }
 
@@ -523,6 +530,9 @@ func mustRegisterMetrics(deniedMetrics MetricsSet) {
 	if !deniedMetrics.Has(tunnelConnectorActiveConnectionsMetricName) {
 		prometheus.MustRegister(tunnelConnectorActiveConnections)
 	}
+	if !deniedMetrics.Has(zoneEdgeErrorsByPathMetricName) {
+		prometheus.MustRegister(zoneEdgeErrorsByPath)
+	}
 }
 
 func fetchLoadblancerPoolsHealth(account cfaccounts.Account, wg *sync.WaitGroup) {
@@ -903,6 +913,54 @@ func addHTTPAdaptiveGroups(z *zoneResp, name string, account string) {
 	}
 }
 
+func fetchEdgeErrorsByPathAnalytics(zones []cfzones.Zone, wg *sync.WaitGroup) {
+	defer wg.Done()
+
+	if !viper.GetBool("enable_edge_errors_by_path") {
+		return
+	}
+
+	if viper.GetBool("free_tier") {
+		return
+	}
+
+	zoneIDs := extractZoneIDs(zones)
+	if len(zoneIDs) == 0 {
+		return
+	}
+
+	r, err := fetchEdgeErrorsByPath(zoneIDs)
+	if err != nil {
+		log.Error("failed to fetch edge errors by path: ", err)
+		return
+	}
+
+	for _, z := range r.Viewer.Zones {
+		name, account := findZoneAccountName(zones, z.ZoneTag)
+		addEdgeErrorsByPath(&z, name, account)
+	}
+}
+
+func addEdgeErrorsByPath(z *zoneRespEdgeErrorsByPath, name string, account string) {
+	if len(z.HTTPRequestsAdaptiveGroups) == 0 {
+		return
+	}
+
+	label := prometheus.Labels{"zone": name, "account": account}
+	zoneEdgeErrorsByPath.DeletePartialMatch(label)
+
+	for _, g := range z.HTTPRequestsAdaptiveGroups {
+		zoneEdgeErrorsByPath.With(
+			prometheus.Labels{
+				"zone":    name,
+				"account": account,
+				"status":  strconv.Itoa(int(g.Dimensions.EdgeResponseStatus)),
+				"host":    g.Dimensions.ClientRequestHTTPHost,
+				"path":    normalizePath(g.Dimensions.ClientRequestPath),
+			}).Add(float64(g.Count))
+	}
+}
+
 func fetchLoadBalancerAnalytics(zones []cfzones.Zone, wg *sync.WaitGroup) {
 	defer wg.Done()
 

utils.go

@@ -2,6 +2,8 @@ package main
 
 import (
 	"encoding/json"
+	"regexp"
+	"strings"
 	"time"
 
 	"github.com/spf13/viper"
@@ -21,3 +23,33 @@ func jsonStringToMap(fields string) (map[string]interface{}, error) {
 	err := json.Unmarshal([]byte(fields), &extraFields)
 	return extraFields, err
 }
+
+var (
+	numericIDPattern = regexp.MustCompile(`^[0-9]+$`)
+	uuidPattern      = regexp.MustCompile(`^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$`)
+	hexIDPattern     = regexp.MustCompile(`^[0-9a-fA-F]{8,}$`)
+)
+
+func normalizePath(path string) string {
+	if path == "" || path == "/" {
+		return path
+	}
+
+	path = strings.Split(path, "?")[0]
+
+	segments := strings.Split(path, "/")
+	for i, segment := range segments {
+		if segment == "" {
+			continue
+		}
+		if numericIDPattern.MatchString(segment) {
+			segments[i] = ":id"
+		} else if uuidPattern.MatchString(segment) {
+			segments[i] = ":uuid"
+		} else if hexIDPattern.MatchString(segment) {
+			segments[i] = ":id"
+		}
+	}
+
+	return strings.Join(segments, "/")
+}

utils_test.go

@@ -0,0 +1,30 @@
+package main
+
+import "testing"
+
+func TestNormalizePath(t *testing.T) {
+	tests := []struct {
+		input    string
+		expected string
+	}{
+		{"", ""},
+		{"/", "/"},
+		{"/health", "/health"},
+		{"/api/v1/users", "/api/v1/users"},
+		{"/users/123", "/users/:id"},
+		{"/users/123/orders/456", "/users/:id/orders/:id"},
+		{"/orders/550e8400-e29b-41d4-a716-446655440000", "/orders/:uuid"},
+		{"/items/5f3a2b1c9d", "/items/:id"},
+		{"/search?q=test&page=1", "/search"},
+		{"/api/v1/users/123?include=orders", "/api/v1/users/:id"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.input, func(t *testing.T) {
+			result := normalizePath(tt.input)
+			if result != tt.expected {
+				t.Errorf("normalizePath(%q) = %q, want %q", tt.input, result, tt.expected)
+			}
+		})
+	}
+}