# datastax/metric-collector-for-apache-cassandra architecture

> Architecture diagram of the GitHub repository datastax/metric-collector-for-apache-cassandra, 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/datastax/metric-collector-for-apache-cassandra
- Repository: https://github.com/datastax/metric-collector-for-apache-cassandra

## Overview

##### Project type and purpose
- This is an open-source monitoring agent/tool, not a full-stack web app.
- It consists of:
- A Java “agent” jar that you attach to Cassandra nodes
- Configuration templates & scripts for collectd
- A built-in Prometheus exporter endpoint
- Dashboards (Grafana + Prometheus) with demo deployment

##### File structure
- src/main/java/...: Core Java agent code
- com.datastax.mcac.Agent – entry point loaded by the JVM
- CollectdController, UnixSocketClient – send metrics/events to collectd
- interceptors/insights/metrics utils – transform Cassandra metrics & diagnostic events
- config/: default YAML and collectd.conf templates
- dashboards/:
- demo/ – docker-compose for quick start
- grafana/ – jsonnet templates & generated dashboards
- prometheus/ – prometheus.yaml + target list
- k8s-build/ – Helm-style templating for Kubernetes
- scripts/datalog-parser.py – post-processing of on-node JSON logs

##### Key components
A. Cassandra Node
- Cassandra JVM
- MCAC Java agent jar (injected via -javaagent)
- Local disk for “datalog” files (optional)
- Metric interceptors (CassandraDaemonInterceptor)
- Insight/event generator
- FilteringRule & ConfigurationLoader
- UnixSocketClient → Collectd
- Embedded Prometheus exporter (HTTP server on port 9103)
C. Collectd daemon (external process on same host)
- Uses config/collectd.conf.tmpl + plugin set
- Gathers OS metrics + receives metrics over local Unix socket
D. Monitoring Backend
- Prometheus server (scrapes MCAC exporter & Collectd if configured)
- Grafana (dashboards from dashboards/grafana)
- Docker-Compose or k8s resources that stand up:
- Cassandra cluster containers (with agent)
- Prometheus container
- Grafana container
F. Optional: Datalog parser script (post-agent JSON logs → human analysis / jq)

##### Relationships & data flow
1. Cassandra JVM emits metrics/events → MCAC Agent interceptors
2. MCAC Agent formats metrics/events → writes to local collectd via Unix socket
3. Collectd collects OS + C* metrics → (optional) pushes to other backends OR via Prometheus plugin
4. MCAC Agent’s embedded HTTP exporter → Prometheus scrapes on port 9103
5. Prometheus stores time series → Grafana queries Prometheus
6. Grafana renders dashboards

##### Architectural patterns / design principles
- Agent-based instrumentation (drop-in JVM agent)
- Adapter layer: Cassandra metrics → collectd format → Prometheus metrics
- Plug-in driven (collectd plugins, jsonnet dashboards, k8s templates)
- Config-driven (YAML for filtering rules, collectd, dashboards)

##### Technologies / frameworks to call out
- Java agent (javaagent API)
- collectd (with Unix socket plugin)
- Prometheus exporter library (embedded in agent)
- Grafana + jsonnet for dashboard generation
- Docker‐Compose / Kubernetes manifests for deployment
- Python script for datalog parsing

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Host Components"
        C["Cassandra JVM"]:::onhost
        subgraph "MCAC Agent Internals"
            A0["MCAC Agent (datastax-mcac-agent.jar)"]:::onhost
            A1["Agent Entry Point (Agent.java)"]:::onhost
            A2["CassandraDaemonInterceptor"]:::onhost
            A3["Insight Generator (Insight.java)"]:::onhost
            A4["Insight Events (InsightsClientStarted.java)"]:::onhost
            A5["Metric Types (metrics)"]:::onhost
            A6["ConfigurationLoader"]:::onhost
            A7["FilteringRule"]:::onhost
            A9["CollectdController"]:::onhost
            A8["UnixSocketClient"]:::onhost
            A10["Embedded HTTP Exporter (port 9103)"]:::onhost
        end
        MTC["metric-collector.yaml"]:::onhost
        CCT["collectd.conf.tmpl"]:::onhost
        D["Collectd Daemon"]:::onhost
    end

    subgraph "Monitoring Backend"
        P["Prometheus"]:::backend
        G["Grafana"]:::backend
        PY["prometheus.yaml"]:::backend
        GJSONNET["dashboards-jsonnet"]:::backend
        GGEN["generated-dashboards"]:::backend
        GCONF["prometheus-datasource.yaml & grafana.ini"]:::backend
    end

    subgraph "Optional Demo/K8s Overlay" style dashed
        DC["docker-compose.yml"]:::optional
        K8s["k8s-build/templates"]:::optional
    end

    C -->|"emits metrics/events"| A2
    A2 -->|"generates insights"| A3
    A3 -->|"events"| A4
    A2 -->|"collect metrics"| A5
    A6 -->|"loads config"| A7
    A0 -->|"initializes"| A6
    A5 -->|"passes to"| A9
    A9 -->|"formats & sends"| A8
    A8 -->|"writes to"| D
    A10 -->|"HTTP metrics"| P
    D -->|"collectd plugin scrape"| P
    P -->|"queries metrics"| G

    DC -.-> C
    DC -.-> P
    DC -.-> G
    K8s -.-> C
    K8s -.-> P
    K8s -.-> G

    click A1 "https://github.com/datastax/metric-collector-for-apache-cassandra/blob/master/src/main/java/com/datastax/mcac/Agent.java"
    click A2 "https://github.com/datastax/metric-collector-for-apache-cassandra/blob/master/src/main/java/com/datastax/mcac/interceptors/CassandraDaemonInterceptor.java"
    click A3 "https://github.com/datastax/metric-collector-for-apache-cassandra/blob/master/src/main/java/com/datastax/mcac/insights/Insight.java"
    click A4 "https://github.com/datastax/metric-collector-for-apache-cassandra/blob/master/src/main/java/com/datastax/mcac/insights/events/InsightsClientStarted.java"
    click A5 "https://github.com/datastax/metric-collector-for-apache-cassandra/tree/master/src/main/java/com/datastax/mcac/insights/metrics"
    click A6 "https://github.com/datastax/metric-collector-for-apache-cassandra/blob/master/src/main/java/com/datastax/mcac/ConfigurationLoader.java"
    click A7 "https://github.com/datastax/metric-collector-for-apache-cassandra/blob/master/src/main/java/com/datastax/mcac/FilteringRule.java"
    click A8 "https://github.com/datastax/metric-collector-for-apache-cassandra/blob/master/src/main/java/com/datastax/mcac/UnixSocketClient.java"
    click A9 "https://github.com/datastax/metric-collector-for-apache-cassandra/blob/master/src/main/java/com/datastax/mcac/CollectdController.java"
    click A0 "https://github.com/datastax/metric-collector-for-apache-cassandra/blob/master/src/main/java/com/datastax/mcac/Agent.java"
    click MTC "https://github.com/datastax/metric-collector-for-apache-cassandra/blob/master/config/metric-collector.yaml"
    click CCT "https://github.com/datastax/metric-collector-for-apache-cassandra/blob/master/config/collectd.conf.tmpl"
    click PY "https://github.com/datastax/metric-collector-for-apache-cassandra/blob/master/dashboards/prometheus/prometheus.yaml"
    click GJSONNET "https://github.com/datastax/metric-collector-for-apache-cassandra/tree/master/dashboards/grafana/dashboards-jsonnet"
    click GGEN "https://github.com/datastax/metric-collector-for-apache-cassandra/tree/master/dashboards/grafana/generated-dashboards"
    click GCONF "https://github.com/datastax/metric-collector-for-apache-cassandra/blob/master/dashboards/grafana/prometheus-datasource.yaml"
    click DC "https://github.com/datastax/metric-collector-for-apache-cassandra/blob/master/dashboards/demo/docker-compose.yml"
    click K8s "https://github.com/datastax/metric-collector-for-apache-cassandra/tree/master/dashboards/k8s-build/templates"

    classDef onhost fill:#e0f7fa,stroke:#00838f,color:#004d40
    classDef backend fill:#e8f5e9,stroke:#2e7d32,color:#1b5e20
    classDef optional fill:none,stroke:#757575,stroke-dasharray: 5, color:#424242
```
