# sladkoff/minecraft-prometheus-exporter architecture

> Architecture diagram of the GitHub repository sladkoff/minecraft-prometheus-exporter, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sladkoff/minecraft-prometheus-exporter
- Repository: https://github.com/sladkoff/minecraft-prometheus-exporter

## Overview

##### Main Components
- Plugin Core and Initialization: Represent the starting point of the plugin (e.g., MetricsServer.java, PrometheusExporter.kt). This is where the plugin is loaded into the Minecraft server.
- HTTP Endpoint Module: Separate components that expose the two primary endpoints:
- /metrics endpoint (using MetricsController.java)
- /health endpoint (using HealthController.java)
- Configuration Management: Show the configuration flow that the plugin follows (environment variables, system properties, then configuration file). This includes classes such as MetricConfig.java, PluginConfig.java, and PrometheusExporterConfig.java.
- Metrics Collection & Aggregation:
- Collectors (e.g., LoadedChunksCollector.java, TpsCollector.java, TickDurationCollector.java) and metric aggregation classes (e.g., MetricRegistry.java, various classes in the metrics package).
- Player-specific metrics collectors (in src/main/java/de/sldk/mc/metrics/player).
- Health Checks: Indicate the health check framework (HealthCheck.java and its implementations, e.g., ConcurrentHealthChecks.java, HealthChecks.java) that aggregates custom health checks.
- External Integration:
- Integration with Prometheus (via the Prometheus client libraries) and describe how Grafana dashboards (the JSON files in the dashboards directory) consume exposed metrics.
- Docker support (docker-compose.yml) for containerized deployments if relevant in deployment mode.

##### Relationships and Interactions
- How the Plugin Core initializes and wires together its configuration, metrics collection, and HTTP endpoint setup.
- Configuration flow – from environment variables (highest priority) through system properties, and finally to the plugin’s own configuration file.

##### Important Architectural Patterns and Principles
- Separation of Concerns: Distinguish between data collection (metrics, health checks), configuration management, and the HTTP API endpoints.
- Dependency Injection: Note that configuration and custom health checks are aggregated via service management (see how HealthChecks is loaded and enriched).
- Extensibility: Point out the capability for third-party integrations (both for custom metrics and health checks) as described in the README. For example, use of external libraries (prometheus simpleclient for metric registration) and integration of custom plugin health checks.
- Modularity: Emphasize the different packages corresponding to "collectors," "metrics," "config," "health," and "utils." Each package encapsulates a focused part of the functionality.

##### Additional Details for the Engineer
- Listing Java/Kotlin as the main technologies and Maven as the build tool (pom.xml is used for dependency management).
- External integrations like Prometheus's scraping and Grafana dashboards (dashboard JSON files are provided).
- Testing and continuous integration aspects (GitHub workflows related to testing and releasing) to show how deployment integrity is maintained.
- That while it is modular, most of the operational logic revolves around two primary endpoints (/metrics & /health) which act as the main interface for monitoring.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Environment
    subgraph "External Environment"
        MS("Minecraft Server"):::external
    end

    %% Plugin Core / Bootstrap
    subgraph "Plugin Core / Bootstrap"
        PS("MetricsServer"):::plugin
        PE("PrometheusExporter"):::plugin
    end

    %% Configuration Management
    subgraph "Configuration Management"
        MCC("MetricConfig"):::config
        PC("PluginConfig"):::config
        PEC("PrometheusExporterConfig"):::config
        CF("ConfigFlow(Env>Sys>File)"):::config
    end

    %% Metrics Collection & Aggregation
    subgraph "Metrics Collection & Aggregation"
        LC("LoadedChunksCollector"):::metrics
        TC("TpsCollector"):::metrics
        TDC("TickDurationCollector"):::metrics
        MR("MetricRegistry"):::metrics
        MP("MetricsPackage"):::metrics
        PMC("PlayerMetricsCollectors"):::metrics
    end

    %% Health Checks
    subgraph "Health Checks"
        HC("HealthCheck"):::health
        CHC("ConcurrentHealthChecks"):::health
        HCS("HealthChecks"):::health
    end

    %% HTTP Endpoints
    subgraph "HTTP Endpoints"
        MC("MetricsController(/metrics)"):::endpoints
        HC2("HealthController(/health)"):::endpoints
    end

    %% External Integrations
    subgraph "External Integrations"
        P("Prometheus"):::external
        G("Grafana"):::external
        DC("DockerCompose"):::external
    end

    %% Connections
    MS -->|"loads"| PS
    MS -->|"loads"| PE

    PS -->|"initializes"| CF
    PE -->|"initializes"| CF

    CF -->|"configures"| MCC
    CF --> PC
    CF --> PEC

    CF -->|"sets up"| LC
    CF --> TC
    CF --> TDC
    CF --> MR
    CF --> MP
    CF --> PMC
    CF --> HC
    CF --> CHC
    CF --> HCS

    LC -->|"provides data"| MC
    TC --> MC
    TDC --> MC
    MR --> MC

    HC -->|"reports status"| HC2
    CHC --> HC2
    HCS --> HC2

    MC -->|"scraped by"| P
    MC -->|"visualized by"| G

    PE -->|"deployed via"| DC

    %% Click Events
    click PS "https://github.com/sladkoff/minecraft-prometheus-exporter/blob/master/src/main/java/de/sldk/mc/MetricsServer.java"
    click PE "https://github.com/sladkoff/minecraft-prometheus-exporter/blob/master/src/main/kotlin/de/sldk/mc/PrometheusExporter.kt"
    click MC "https://github.com/sladkoff/minecraft-prometheus-exporter/blob/master/src/main/java/de/sldk/mc/MetricsController.java"
    click HC2 "https://github.com/sladkoff/minecraft-prometheus-exporter/blob/master/src/main/java/de/sldk/mc/HealthController.java"
    click MCC "https://github.com/sladkoff/minecraft-prometheus-exporter/blob/master/src/main/java/de/sldk/mc/config/MetricConfig.java"
    click PC "https://github.com/sladkoff/minecraft-prometheus-exporter/blob/master/src/main/java/de/sldk/mc/config/PluginConfig.java"
    click PEC "https://github.com/sladkoff/minecraft-prometheus-exporter/blob/master/src/main/java/de/sldk/mc/config/PrometheusExporterConfig.java"
    click LC "https://github.com/sladkoff/minecraft-prometheus-exporter/blob/master/src/main/java/de/sldk/mc/collectors/LoadedChunksCollector.java"
    click TC "https://github.com/sladkoff/minecraft-prometheus-exporter/blob/master/src/main/java/de/sldk/mc/collectors/TpsCollector.java"
    click TDC "https://github.com/sladkoff/minecraft-prometheus-exporter/blob/master/src/main/java/de/sldk/mc/metrics/tick_duration/TickDurationCollector.java"
    click MR "https://github.com/sladkoff/minecraft-prometheus-exporter/blob/master/src/main/java/de/sldk/mc/MetricRegistry.java"
    click MP "https://github.com/sladkoff/minecraft-prometheus-exporter/tree/master/src/main/java/de/sldk/mc/metrics"
    click PMC "https://github.com/sladkoff/minecraft-prometheus-exporter/tree/master/src/main/java/de/sldk/mc/metrics/player"
    click HC "https://github.com/sladkoff/minecraft-prometheus-exporter/blob/master/src/main/java/de/sldk/mc/health/HealthCheck.java"
    click CHC "https://github.com/sladkoff/minecraft-prometheus-exporter/blob/master/src/main/java/de/sldk/mc/health/ConcurrentHealthChecks.java"
    click HCS "https://github.com/sladkoff/minecraft-prometheus-exporter/blob/master/src/main/java/de/sldk/mc/health/HealthChecks.java"
    click G "https://github.com/sladkoff/minecraft-prometheus-exporter/tree/master/dashboards"
    click DC "https://github.com/sladkoff/minecraft-prometheus-exporter/blob/master/docker-compose.yml"

    %% Styles
    classDef plugin fill:#C8E6C9,stroke:#388E3C,stroke-width:2px;
    classDef endpoints fill:#BBDEFB,stroke:#1976D2,stroke-width:2px;
    classDef config fill:#FFECB3,stroke:#F57C00,stroke-width:2px;
    classDef metrics fill:#E1BEE7,stroke:#8E24AA,stroke-width:2px;
    classDef health fill:#FFCDD2,stroke:#D32F2F,stroke-width:2px;
    classDef external fill:#CFD8DC,stroke:#607D8B,stroke-width:2px;
```
