nulltix/cloudflare-prometheus-exporter repository overview

⁠Cloudflare Prometheus Exporter

A Prometheus exporter for Cloudflare Analytics metrics, providing real-time HTTP and DNS analytics data from your Cloudflare zones.

⁠Features

• Multi-Zone Support: Monitor multiple Cloudflare zones.
• Thread-Safe Metric Collection: Ensures safe data handling in multi-threaded environments.
• Structured JSON Logging: Provides logs in a structured format for easier analysis.
• Configurable via Environment Variables: Flexible configuration options for deployment.
• Prometheus Metrics Exposure: Exposes HTTP, firewall, and quota metrics for monitoring.
• Error Handling: Robust handling of API errors during metrics collection.
• Health Checks: Monitors the status of the metrics server.

⁠Data Sampling

⁠Configuration

Configuration is handled via environment variables or .env file:

⁠Cloudflare Metadata Boundary (CMB) Compliance

This exporter supports Cloudflare's data residency requirements through CMB regions. For a complete list of available datasets and their regional availability, see Cloudflare CMB GraphQL Datasets documentation⁠.

Choose the appropriate CF_CMB_REGION based on your compliance requirements.

⁠Required Permissions

The Cloudflare API token needs the following permissions:

Account:

• Analytics:Read
• Account Settings:Read
• Billing:Read

Zone:

• Analytics:Read
• Firewall Services:Read

⁠Supported Metrics

Generic Labels for All Metrics:

• zone - Cloudflare zone name
• account - Cloudflare account name
• account_id - Cloudflare account ID

⁠Usage

# Start the exporter
uv run python -m cloudflare_exporter.main

The exporter will start serving metrics on http://localhost:8080/metrics (or configured port).

⁠Docker

# Build the image
docker buildx build --platform linux/amd64,linux/arm64 -t cloudflare-exporter:latest .

# Run the container
docker run -p 8080:8080 --env-file .env cloudflare-exporter

⁠Helm Chart

The Cloudflare Prometheus Exporter Helm chart is available for download from our GitHub Pages repository:

• Download Helm Chart⁠

You can install the chart using the following command:

helm repo add cloudflare-exporter https://n0zz.github.io/cloudflare-prometheus-exporter
helm install my-release cloudflare-exporter/cloudflare-prometheus-exporter

⁠Development

⁠Prerequisites

• Python 3.13⁠
• uv⁠ - Python package manager
• just⁠ - Command runner
• Helm⁠ - Kubernetes package manager (optional, for chart development)
• yq⁠ - YAML processor (optional, for chart template validation)
• Trivy⁠ - Vulnerability scanner (optional, for local security scans)

⁠Setup

# Install dependencies
uv sync

# List available commands
just

⁠Commands

# Run unit tests
just unit-test

# Run integration tests (requires valid Cloudflare token, see below)
just integration-test

# Run type checking
just typecheck

# Format code
just format

# Run linting
just lint

# Run security checks (dependencies and code analysis)
just security-check

# Run Trivy vulnerability scan on repo
just trivy-scan

# Run Trivy vulnerability scan on Docker image
just trivy-image

# Build the Helm chart
just build-helm-chart

# Build Docker image
just build-docker-image

⁠Integration Tests

Integration tests run against the real Cloudflare API and require a valid CF_API_TOKEN.

Locally: Create a .env file with your token and run just integration-test.

CI: Integration tests run automatically in GitHub Actions if the CF_API_TOKEN secret is configured in the repository settings. If the secret is not set, the job is skipped gracefully. To enable them in your fork, add a CF_API_TOKEN repository secret under Settings > Secrets and variables > Actions.

⁠Security

This project includes several security scanning tools:

1. Trivy - Scans for:

   • Container vulnerabilities
   • Infrastructure as Code issues
   • Git repository secrets
   • Software composition analysis (SCA)

2. Bandit - Static application security testing (SAST) for Python code

3. Zizmor - GitHub Actions workflow security auditing (action pinning, injection risks, permissions)

Security scans run:

• On every push to main
• On every pull request
• Weekly (scheduled) for the main branch
• Manually via just security-check

Results are available in the GitHub Security tab.

⁠Prometheus Configuration

When deployed via Helm, the chart includes a ServiceMonitor resource — no additional configuration is needed if you use Prometheus Operator.

For standalone Prometheus without the operator, add a scrape config to your prometheus.yml:

scrape_configs:
  - job_name: 'cloudflare'
    static_configs:
      - targets: ['localhost:8080']
    scrape_interval: 60s

⁠Grafana Dashboard

Grafana dashboard: Grafana Cloud⁠

⁠Further Reading

• Cloudflare Analytics API⁠ documentation
• Prometheus Python Client⁠
• Python Cloudflare⁠ library
• Cloudflare CMB GraphQL Datasets⁠ - Official documentation of available datasets and their regional availability

⁠Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Install dependencies: uv sync
4. Run tests and linting: just test and just lint
5. Commit your changes following the commit lint guidelines (git commit -m 'feat: add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

⁠License

This project is licensed under the MIT License - see the LICENSE⁠ file for details.

⁠Support

For support, please open an issue on the GitHub repository or contact the maintainers.