# criteo/cassandra_exporter architecture

> Architecture diagram of the GitHub repository criteo/cassandra_exporter, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/criteo/cassandra_exporter
- Repository: https://github.com/criteo/cassandra_exporter

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Exporter Process
    subgraph "Exporter Process"
        direction TB
        ConfigFile["Config YAML / ENV"]:::external
        ConfigLoader["Configuration Loader"]:::inProc
        Scheduler["Scheduler"]:::inProc
        JmxScraper["JmxScraper"]:::inProc
        JMXConnector["JMX Connector"]:::inProc
        MetricsProcessor["Metrics Processor\n(EstimatedHistogram)"]:::inProc
        CacheStore["Cache Store"]:::inProc
        HTTPServer["HTTP Server\n(/metrics endpoint)"]:::inProc
        LabelEnricher["Label Enricher"]:::inProc

        ConfigFile -->|"load config"| ConfigLoader
        ConfigLoader -->|"init"| Scheduler
        ConfigLoader -->|"init"| JmxScraper
        Scheduler -->|"trigger scrape"| JmxScraper
        JmxScraper -->|"connect & fetch"| JMXConnector
        JMXConnector -->|"MBeans data"| MetricsProcessor
        MetricsProcessor -->|"process metrics"| CacheStore
        HTTPServer -->|"read cache"| CacheStore
        HTTPServer -->|"enrich labels"| LabelEnricher
        LabelEnricher -->|"serve metrics"| HTTPServer
    end

    %% External Systems
    subgraph "External Systems"
        direction TB
        Cassandra["Cassandra (JMX)"]:::external
        Prometheus["Prometheus"]:::external
        Grafana["Grafana Dashboards"]:::external

        Cassandra -->|JMX queries| JmxScraper
        HTTPServer -->|scrape /metrics| Prometheus
        Prometheus -->|visualize data| Grafana
    end

    %% Deployment & CI
    subgraph "Deployment & CI"    
        direction TB
        Docker["Docker Packaging"]:::deploy
        Ansible["Ansible Role"]:::deploy
        CI["CI/CD Workflows"]:::deploy
        GrafanaGen["Grafana Dashboards & Generator"]:::deploy

        Docker -->|package exporter| Docker
        Ansible -->|provision & configure| Ansible
        CI -->|build & release| CI
        GrafanaGen -->|dashboard templates| Grafana
    end

    %% Click Events
    click ConfigLoader "https://github.com/criteo/cassandra_exporter/blob/master/src/main/java/com/criteo/nosql/cassandra/exporter/Config.java"
    click ConfigLoader "https://github.com/criteo/cassandra_exporter/blob/master/src/main/java/com/criteo/nosql/cassandra/exporter/Config.java"
    click Scheduler "https://github.com/criteo/cassandra_exporter/blob/master/src/main/java/com/criteo/nosql/cassandra/exporter/JmxScraper.java"
    click JmxScraper "https://github.com/criteo/cassandra_exporter/blob/master/src/main/java/com/criteo/nosql/cassandra/exporter/JmxScraper.java"
    click MetricsProcessor "https://github.com/criteo/cassandra_exporter/blob/master/src/main/java/com/criteo/nosql/cassandra/exporter/EstimatedHistogram.java"
    click ConfigLoader "https://github.com/criteo/cassandra_exporter/blob/master/src/test/java/com/criteo/nosql/cassandra/exporter/ConfigTest.java"
    click JmxScraper "https://github.com/criteo/cassandra_exporter/blob/master/src/test/java/com/criteo/nosql/cassandra/exporter/JmxScraperTest.java"
    click HTTPServer "https://github.com/criteo/cassandra_exporter/blob/master/src/test/java/com/criteo/nosql/cassandra/exporter/MainTest.java"
    click ConfigFile "https://github.com/criteo/cassandra_exporter/blob/master/config.yml"
    click ConfigFile "https://github.com/criteo/cassandra_exporter/blob/master/config_minimal_dashboard.yml"
    click Docker "https://github.com/criteo/cassandra_exporter/tree/master/docker/Dockerfile"
    click Docker "https://github.com/criteo/cassandra_exporter/blob/master/docker/run.sh"
    click Docker "https://github.com/criteo/cassandra_exporter/blob/master/docker/config.yml"
    click GrafanaGen "https://github.com/criteo/cassandra_exporter/blob/master/grafana/Cassandra_template.json"
    click GrafanaGen "https://github.com/criteo/cassandra_exporter/blob/master/grafana/cassandra_default.json"
    click GrafanaGen "https://github.com/criteo/cassandra_exporter/blob/master/grafana/cassandra_kubernetes.json"
    click GrafanaGen "https://github.com/criteo/cassandra_exporter/blob/master/grafana/generate.py"
    click Ansible "https://github.com/criteo/cassandra_exporter/tree/master/ansible/roles/ansible-cassandra-exporter"
    click CI "https://github.com/criteo/cassandra_exporter/blob/master/.github/workflows/build.yml"
    click CI "https://github.com/criteo/cassandra_exporter/blob/master/.github/workflows/release.yml"
    click CI "https://github.com/criteo/cassandra_exporter/blob/master/build.gradle"
    click CI "https://github.com/criteo/cassandra_exporter/tree/master/gradlew"
    click CI "https://github.com/criteo/cassandra_exporter/blob/master/gradlew.bat"
    click CI "https://github.com/criteo/cassandra_exporter/tree/master/gradle/wrapper/"

    %% Styles
    classDef inProc fill:#B3CDE0,stroke:#03396C,color:#03396C
    classDef external fill:#C7E9C0,stroke:#006400,color:#006400
    classDef deploy fill:#FDD0A2,stroke:#EF8A62,color:#A63603
```
