How criteo/cassandra_exporter works
Project type and purpose
• This is an open-source, Java-based Prometheus exporter for Apache Cassandra.
• Its sole responsibility is to query Cassandra via JMX on a configured schedule, apply filtering and caching, and expose metrics over HTTP in Prometheus format.
• Ancillary components include Docker packaging, Grafana dashboards, Ansible roles for deployment, and CI/CD workflows.
File structure
• src/main/java: core exporter code (Config, Main, JmxScraper, EstimatedHistogram).
• src/test/java: unit tests for each core class.
• config.yml / config_minimal_dashboard.yml: sample YAML configurations (blacklist, scrape frequencies, JMX connection, listen port).
• docker/: Dockerfile, entrypoint script, container configuration.
• grafana/: JSON dashboard templates and generator script.
• ansible/roles/ansible-cassandra-exporter/: Ansible role to install and configure the exporter as a systemd service.
• .github/workflows: CI pipeline definitions (build, release).
• build.gradle / gradlew: Gradle build and wrapper.
README for insights
• The README emphasizes safety (cache results, standalone process) and maintainability (version-agnostic metrics, configurable frequencies, blacklist).
• Deployment instructions cover standalone JAR, Docker, Kubernetes (via Helm chart), Grafana dashboards.
• Configuration model: YAML-driven, two main blocks (blacklist + maxScrapFrequencyInSec).
Main components & their interactions
a. Components:
1. Configuration Loader (reads config.yml + ENV vars)
2. Scheduler (enforces per-metric scrape frequencies)
3. JMX Connector (opens JMX connection to Cassandra node)
4. JmxScraper (executes MBean queries, applies blacklist)
5. Metrics Processor (transforms raw JMX beans into Prometheus metrics, handles EstimatedHistogram)
6. Cache Store (in-process cache to avoid expensive JMX calls)
7. HTTP Server (embedded server exposing /metrics)
8. Label Enricher (injects additional labels from ENV regex)
9. Docker Container / Ansible Role (packaging & deployment layers)
10. Prometheus Server (external, scrapes exporter)
b. Relationships & data flows:
• On startup, Main loads the Configuration Loader, initializes the Scheduler, JmxScraper, Cache Store, HTTP Server, and Label Enricher.
• The Scheduler triggers the JmxScraper at configured intervals per metric.
• JmxScraper uses JMX Connector to fetch MBeans, passes raw data to Metrics Processor.
• Metrics Processor applies histogram logic, filters out blacklisted attributes, and stores results in Cache Store.
• HTTP Server, upon an HTTP GET to /metrics, reads from Cache Store, runs metrics through Label Enricher, and returns Prometheus-formatted payload.
• Prometheus scrapes the /metrics endpoint.
• Docker or Ansible provisions the exporter process on each Cassandra node.
c. Architectural patterns & principles:
• Standalone process (isolation)
• Scheduler with per-metric frequency (rate control)
• In-process caching (performance/safety)
• Modular layers (Config → Scraper → Processor → HTTP)
• Configuration-driven behavior (blacklist, frequencies, labels)
d. Key technologies & frameworks:
• Java 8+ (JMX, SLF4J)
• Gradle build system
• JMX API
• Embedded HTTP server (e.g., Simple or Jetty)
• Docker / Systemd (via Ansible role)
• Prometheus exposition format
• Grafana JSON dashboards
• GitHub Actions for CI/CD
Detailed capture of essential elements
• Do not omit the cache layer and scheduler logic, as they embody critical safety features.
• Label Enricher to document ENV-based dynamic metadata injection.
• blacklist & frequency config as an input artifact feeding into both the Scheduler and the Scraper.
• unit testing is in place (optional annotation), and CI workflows are triggered on commit.