Merge branch 'master' into add-asn-metrics

Author: haad

README.md

@@ -26,6 +26,10 @@ Authentication towards the Cloudflare API can be done in two ways:
 The preferred way of authenticating is with an API token, for which the scope can be configured at the Cloudflare
 dashboard.
 
+**Important**: Cloudflare supports two types of API tokens:
+- **User-level tokens**: Can access all accounts the user has permissions for. These tokens auto-discover all accessible accounts.
+- **Account-scoped tokens**: Scoped to a specific account. When using account-scoped tokens, you **must** set the `CF_ACCOUNTS` environment variable with your account ID(s).
+
 Required authentication scopes:
 
 - `Zone/Analytics:Read` is required for zone-level metrics
@@ -37,9 +41,15 @@ Required authentication scopes:
 - `Account:Load Balancing: Monitors and Pools:Read` is required to fetch pools origin health status `cloudflare_pool_origin_health_status` metric
 - `Cloudflare Tunnel Read` is required to fetch Cloudflare Tunnel (Cloudflare Zero Trust) metrics
 
-To authenticate this way, only set `CF_API_TOKEN` (omit `CF_API_EMAIL` and `CF_API_KEY`)
+**To authenticate with a user-level token**:
+- Set `CF_API_TOKEN` (omit `CF_API_EMAIL` and `CF_API_KEY`)
+- The exporter will auto-discover all accounts you have access to
+- [Shortcut to create the API token](https://dash.cloudflare.com/profile/api-tokens?permissionGroupKeys=%5B%7B%22key%22%3A%22account_analytics%22%2C%22type%22%3A%22read%22%7D%2C%7B%22key%22%3A%22account_settings%22%2C%22type%22%3A%22read%22%7D%2C%7B%22key%22%3A%22analytics%22%2C%22type%22%3A%22read%22%7D%2C%7B%22key%22%3A%22firewall_services%22%2C%22type%22%3A%22read%22%7D%5D&name=Cloudflare+Exporter&accountId=*&zoneId=all)
 
-[Shortcut to create the API token](https://dash.cloudflare.com/profile/api-tokens?permissionGroupKeys=%5B%7B%22key%22%3A%22account_analytics%22%2C%22type%22%3A%22read%22%7D%2C%7B%22key%22%3A%22account_settings%22%2C%22type%22%3A%22read%22%7D%2C%7B%22key%22%3A%22analytics%22%2C%22type%22%3A%22read%22%7D%2C%7B%22key%22%3A%22firewall_services%22%2C%22type%22%3A%22read%22%7D%5D&name=Cloudflare+Exporter&accountId=*&zoneId=all)
+**To authenticate with an account-scoped token**:
+- Set `CF_API_TOKEN` with your account-scoped token
+- Set `CF_ACCOUNTS` with your account ID (find it in the Cloudflare dashboard URL: `https://dash.cloudflare.com/<ACCOUNT_ID>/...`)
+- Example: `CF_ACCOUNTS=abc123def456` or for multiple accounts: `CF_ACCOUNTS=abc123,def456`
 
 ### User email + API key
 
@@ -57,6 +67,7 @@ The exporter can be configured using env variables or command flags.
 | `CF_API_EMAIL` |  user email (see <https://support.cloudflare.com/hc/en-us/articles/200167836-Managing-API-Tokens-and-Keys>) |
 | `CF_API_KEY` |  API key associated with email (`CF_API_EMAIL` is required if this is set)|
 | `CF_API_TOKEN` |  API authentication token (recommended before API key + email. Version 0.0.5+. see <https://developers.cloudflare.com/analytics/graphql-api/getting-started/authentication/api-token-auth>) |
+| `CF_ACCOUNTS` |  (Required for account-scoped tokens) Cloudflare account IDs to monitor, comma delimited list. When using account-scoped API tokens, this must be set. User-level tokens can omit this to auto-discover all accessible accounts. |
 | `CF_ZONES` |  (Optional) cloudflare zones to export, comma delimited list of zone ids. If not set, all zones from account are exported |
 | `CF_EXCLUDE_ZONES` |  (Optional) cloudflare zones to exclude, comma delimited list of zone ids. If not set, no zones from account are excluded |
 | `CF_TIMEOUT` | Set cloudflare request timeout. Default 10 seconds |
@@ -67,6 +78,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` |
 
@@ -76,6 +88,7 @@ Corresponding flags:
   -cf_api_email="": cloudflare api email, works with api_key flag
   -cf_api_key="": cloudflare api key, works with api_email flag
   -cf_api_token="": cloudflare api token (version 0.0.5+, preferred)
+  -cf_accounts="": cloudflare accounts to monitor, comma delimited list (required for account-scoped API tokens)
   -cf_zones="": cloudflare zones to export, comma delimited list
   -cf_exclude_zones="": cloudflare zones to exclude, comma delimited list
   -cf_timeout="10s": cloudflare request timeout, default 10 seconds
@@ -86,6 +99,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 +133,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 +146,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

@@ -112,6 +112,24 @@ type zoneRespASN struct {
 }
 
 
+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"`
@@ -467,8 +485,37 @@ func fetchFirewallRules(zoneID string) map[string]string {
 	return firewallRulesMap
 }
 
-func fetchAccounts() []cfaccounts.Account {
+func fetchAccounts(targetAccountIDs []string) []cfaccounts.Account {
 	var cfAccounts []cfaccounts.Account
+
+	if len(targetAccountIDs) > 0 {
+		log.Info("Using provided account IDs (account-scoped token mode)")
+		for _, accountID := range targetAccountIDs {
+			accountID = strings.TrimSpace(accountID)
+			if accountID == "" {
+				continue
+			}
+
+			ctx, cancel := context.WithTimeout(context.Background(), cftimeout)
+			account, err := cfclient.Accounts.Get(ctx, cfaccounts.AccountGetParams{
+				AccountID: cf.F(accountID),
+			})
+			cancel()
+
+			if err != nil {
+				log.Warnf("Account %s details unavailable, using ID only: %v", accountID, err)
+				cfAccounts = append(cfAccounts, cfaccounts.Account{
+					ID: accountID,
+				})
+			} else {
+				cfAccounts = append(cfAccounts, *account)
+			}
+		}
+		log.Infof("Loaded %d account(s) from CF_ACCOUNTS", len(cfAccounts))
+		return cfAccounts
+	}
+
+	log.Info("Listing all accessible accounts (user-level token mode)")
 	ctx, cancel := context.WithTimeout(context.Background(), cftimeout)
 	defer cancel()
 	page := cfclient.Accounts.ListAutoPaging(ctx,
@@ -888,6 +935,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

@@ -39,6 +39,15 @@ var (
 // 	cfgMetricsDenylist = ""
 // )
 
+func getTargetAccounts() []string {
+	var accountIDs []string
+
+	if len(viper.GetString("cf_accounts")) > 0 {
+		accountIDs = strings.Split(viper.GetString("cf_accounts"), ",")
+	}
+	return accountIDs
+}
+
 func getTargetZones() []string {
 	var zoneIDs []string
 
@@ -105,7 +114,8 @@ func filterExcludedZones(all []cfzones.Zone, exclude []string) []cfzones.Zone {
 
 func fetchMetrics() {
 	var wg sync.WaitGroup
-	accounts := fetchAccounts()
+	targetAccounts := getTargetAccounts()
+	accounts := fetchAccounts(targetAccounts)
 
 	for _, a := range accounts {
 		wg.Add(1)
@@ -149,6 +159,9 @@ func fetchMetrics() {
 
 		wg.Add(1)
 		go fetchZoneASNAnalytics(filteredZones, &wg)
+    
+    wg.Add(1)
+		go fetchEdgeErrorsByPathAnalytics(filteredZones, &wg)
 	} else if zoneCount > cfgraphqlreqlimit {
 		for s := 0; s < zoneCount; s += cfgraphqlreqlimit {
 			e := s + cfgraphqlreqlimit
@@ -169,6 +182,9 @@ func fetchMetrics() {
 
 			wg.Add(1)
 			go fetchZoneASNAnalytics(filteredZones[s:e], &wg)
+      
+      wg.Add(1)
+			go fetchEdgeErrorsByPathAnalytics(filteredZones[s:e], &wg)
 		}
 	}
 
@@ -257,6 +273,10 @@ func main() {
 	flags.String("cf_api_token", "", "cloudflare api token (preferred)")
 	viper.BindEnv("cf_api_token")
 
+	flags.String("cf_accounts", "", "cloudflare accounts to monitor, comma delimited list of account ids (required for account-scoped API tokens)")
+	viper.BindEnv("cf_accounts")
+	viper.SetDefault("cf_accounts", "")
+
 	flags.String("cf_zones", "", "cloudflare zones to export, comma delimited list of zone ids")
 	viper.BindEnv("cf_zones")
 	viper.SetDefault("cf_zones", "")
@@ -293,6 +313,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,8 +63,9 @@ const (
 	tunnelHealthStatusMetricName                    MetricName = "cloudflare_tunnel_health_status"
 	tunnelConnectorInfoMetricName                   MetricName = "cloudflare_tunnel_connector_info"
 	tunnelConnectorActiveConnectionsMetricName      MetricName = "cloudflare_tunnel_connector_active_connections"
-	zoneRequestASNMetricName                     MetricName = "cloudflare_zone_requests_asn"
-	zoneBandwidthASNMetricName                   MetricName = "cloudflare_zone_bandwidth_asn"
+	zoneRequestASNMetricName                        MetricName = "cloudflare_zone_requests_asn"
+	zoneBandwidthASNMetricName                      MetricName = "cloudflare_zone_bandwidth_asn"
+	zoneEdgeErrorsByPathMetricName                  MetricName = "cloudflare_zone_edge_errors_by_path"
 )
 
 type MetricsSet map[MetricName]struct{}
@@ -346,6 +347,11 @@ var (
 		Name: zoneBandwidthASNMetricName.String(),
 		Help: "Bandwidth per ASN (Autonomous System Number) in bytes",
 	}, []string{"zone", "account", "asn", "asn_description"})
+  
+	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 {
@@ -358,6 +364,9 @@ func buildAllMetricsSet() MetricsSet {
 	allMetricsSet.Add(zoneRequestHTTPStatusMetricName)
 	allMetricsSet.Add(zoneRequestBrowserMapMetricName)
 	allMetricsSet.Add(zoneRequestOriginStatusCountryHostMetricName)
+	allMetricsSet.Add(zoneRequestOriginStatusCountryHostP50MetricName)
+	allMetricsSet.Add(zoneRequestOriginStatusCountryHostP95MetricName)
+	allMetricsSet.Add(zoneRequestOriginStatusCountryHostP99MetricName)
 	allMetricsSet.Add(zoneRequestStatusCountryHostMetricName)
 	allMetricsSet.Add(zoneBandwidthTotalMetricName)
 	allMetricsSet.Add(zoneBandwidthCachedMetricName)
@@ -391,6 +400,7 @@ func buildAllMetricsSet() MetricsSet {
 	allMetricsSet.Add(tunnelConnectorActiveConnectionsMetricName)
 	allMetricsSet.Add(zoneRequestASNMetricName)
 	allMetricsSet.Add(zoneBandwidthASNMetricName)
+	allMetricsSet.Add(zoneEdgeErrorsByPathMetricName)
 	return allMetricsSet
 }
 
@@ -542,6 +552,9 @@ func mustRegisterMetrics(deniedMetrics MetricsSet) {
 	}
 	if !deniedMetrics.Has(zoneBandwidthASNMetricName) {
 		prometheus.MustRegister(zoneBandwidthASN)
+  }
+	if !deniedMetrics.Has(zoneEdgeErrorsByPathMetricName) {
+		prometheus.MustRegister(zoneEdgeErrorsByPath)
 	}
 }
 
@@ -923,6 +936,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()