# metricshub/metricshub-community architecture

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

- Interactive diagram: https://gitdiagram.com/metricshub/metricshub-community
- Repository: https://github.com/metricshub/metricshub-community

## Overview

MetricsHub is an OpenTelemetry-based monitoring agent and engine. Users configure resources and connectors through files, the CLI, or the web UI; the agent schedules monitoring, the engine discovers and collects data through protocol extensions, and telemetry is exported to an OpenTelemetry Collector. The repository also includes web/MCP querying, remote OpAMP management and upgrades, tunneling, and hardware sustainability processing. Relationships for unsampled subsystems are included only where the README documents them; the supplied tree and excerpts do not expose all runtime wiring.

Main entry points: [`metricshub-agent/src/main/java/org/metricshub/agent/MetricsHubAgentApplication.java`](https://github.com/metricshub/metricshub-community/blob/main/metricshub-agent/src/main/java/org/metricshub/agent/MetricsHubAgentApplication.java) (Agent runtime), [`metricshub-engine`](https://github.com/metricshub/metricshub-community/tree/main/metricshub-engine) (MetricsHub engine), [`metricshub-engine/src/main/java/org/metricshub/engine/extension/ExtensionManager.java`](https://github.com/metricshub/metricshub-community/blob/main/metricshub-engine/src/main/java/org/metricshub/engine/extension/ExtensionManager.java) (Protocol extensions), [`metricshub-agent/src/main/java/org/metricshub/agent/opamp/OpAmpService.java`](https://github.com/metricshub/metricshub-community/blob/main/metricshub-agent/src/main/java/org/metricshub/agent/opamp/OpAmpService.java) (OpAMP management)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_configuration["Configuration and control"]
  node_agent["Agent runtime"]
  node_configuration_service["Configuration service"]
  node_reload["Configuration reload"]
  node_agent_context["Active agent context"]
end

subgraph group_collection["Monitoring and collection"]
  node_scheduler["Monitoring scheduler"]
  node_monitoring_task["Monitoring tasks"]
  node_engine["MetricsHub engine"]
  node_extension_manager["Protocol extensions"]
  node_protocols["Protocol connectors"]
  node_os_commands["OS commands"]
  node_telemetry_manager["Monitor telemetry"]
  node_hardware["Energy enrichment"]
end

subgraph group_telemetry["Telemetry output"]
  node_otel_export["OpenTelemetry export"]
end

subgraph group_management["Remote management"]
  node_opamp["OpAMP management<br/>[OpAmpService.java]"]
  node_opamp_client["OpAMP client<br/>[OpampClient.java]"]
  node_upgrade["Automatic upgrades"]
  node_tunnel["Remote tunnel<br/>[TunnelService.java]"]
end

subgraph group_interaction["User interfaces"]
  node_web_server["Web server"]
  node_web_controllers["Web API"]
  node_web_ui["Web UI<br/>[App.jsx]"]
  node_mcp_tools["MCP query tools"]
  node_cli["Command-line interface"]
end

node_operator(("Operator"))
node_otel_collector["OTel Collector"]

node_operator -->|"configures"| node_web_ui
node_operator -->|"configures"| node_cli
node_web_ui -.->|"uses"| node_web_server
node_web_server -.->|"serves"| node_web_controllers
node_web_controllers -.->|"reads context"| node_agent_context
node_agent -.->|"loads config"| node_configuration_service
node_configuration_service -.->|"supports reload"| node_reload
node_reload -->|"publishes context"| node_agent_context
node_agent -.->|"starts scheduling"| node_scheduler
node_scheduler -.->|"schedules"| node_monitoring_task
node_monitoring_task -.->|"invokes monitoring"| node_engine
node_engine -->|"loads extensions"| node_extension_manager
node_extension_manager -.->|"dispatches queries"| node_protocols
node_extension_manager -.->|"dispatches commands"| node_os_commands
node_os_commands -.->|"queries host"| node_operator
node_engine -.->|"records monitors"| node_telemetry_manager
node_telemetry_manager -->|"enriches metrics"| node_hardware
node_agent -->|"exports metrics"| node_otel_export
node_otel_export -->|"sends telemetry"| node_otel_collector
node_web_controllers -.->|"offers queries"| node_mcp_tools
node_mcp_tools -->|"resolves context"| node_agent_context
node_mcp_tools -->|"executes HTTP"| node_protocols
node_agent -.->|"runs management"| node_opamp
node_opamp -.->|"uses client"| node_opamp_client
node_opamp -->|"handles offers"| node_upgrade
node_agent -.->|"provides tunneling"| node_tunnel

click node_agent "https://github.com/metricshub/metricshub-community/blob/main/metricshub-agent/src/main/java/org/metricshub/agent/MetricsHubAgentApplication.java"
click node_configuration_service "https://github.com/metricshub/metricshub-community/blob/main/metricshub-agent/src/main/java/org/metricshub/agent/service/ConfigurationService.java"
click node_reload "https://github.com/metricshub/metricshub-community/blob/main/metricshub-agent/src/main/java/org/metricshub/agent/service/ConfigurationReloadService.java"
click node_scheduler "https://github.com/metricshub/metricshub-community/blob/main/metricshub-agent/src/main/java/org/metricshub/agent/service/TaskSchedulingService.java"
click node_monitoring_task "https://github.com/metricshub/metricshub-community/blob/main/metricshub-agent/src/main/java/org/metricshub/agent/service/task/MonitoringTask.java"
click node_engine "https://github.com/metricshub/metricshub-community/tree/main/metricshub-engine"
click node_extension_manager "https://github.com/metricshub/metricshub-community/blob/main/metricshub-engine/src/main/java/org/metricshub/engine/extension/ExtensionManager.java"
click node_protocols "https://github.com/metricshub/metricshub-community/blob/main/metricshub-http-extension/src/main/java/org/metricshub/extension/http/HttpRequestExecutor.java"
click node_os_commands "https://github.com/metricshub/metricshub-community/blob/main/metricshub-oscommand-extension/src/main/java/org/metricshub/extension/oscommand/OsCommandService.java"
click node_telemetry_manager "https://github.com/metricshub/metricshub-community/blob/main/metricshub-engine/src/main/java/org/metricshub/engine/telemetry/TelemetryManager.java"
click node_hardware "https://github.com/metricshub/metricshub-community/blob/main/metricshub-hardware/src/main/java/org/metricshub/hardware/HardwareEnergyPostExecutionService.java"
click node_otel_export "https://github.com/metricshub/metricshub-community/blob/main/metricshub-agent/src/main/java/org/metricshub/agent/opentelemetry/MetricsExporter.java"
click node_web_server "https://github.com/metricshub/metricshub-community/blob/main/metricshub-agent/src/main/java/org/metricshub/web/MetricsHubAgentServer.java"
click node_web_controllers "https://github.com/metricshub/metricshub-community/tree/main/metricshub-agent/src/main/java/org/metricshub/web/controller"
click node_web_ui "https://github.com/metricshub/metricshub-community/blob/main/metricshub-web/react/src/App.jsx"
click node_mcp_tools "https://github.com/metricshub/metricshub-community/blob/main/metricshub-agent/src/main/java/org/metricshub/web/mcp/ExecuteHttpQueryService.java"
click node_agent_context "https://github.com/metricshub/metricshub-community/blob/main/metricshub-agent/src/main/java/org/metricshub/web/AgentContextHolder.java"
click node_opamp "https://github.com/metricshub/metricshub-community/blob/main/metricshub-agent/src/main/java/org/metricshub/agent/opamp/OpAmpService.java"
click node_opamp_client "https://github.com/metricshub/metricshub-community/blob/main/metricshub-opamp-client/src/main/java/org/metricshub/opamp/client/OpampClient.java"
click node_upgrade "https://github.com/metricshub/metricshub-community/blob/main/metricshub-agent/src/main/java/org/metricshub/agent/upgrade/UpgradeManager.java"
click node_tunnel "https://github.com/metricshub/metricshub-community/blob/main/metricshub-agent/src/main/java/org/metricshub/agent/tunnel/TunnelService.java"
click node_cli "https://github.com/metricshub/metricshub-community/blob/main/metricshub-agent/src/main/java/org/metricshub/cli/MetricsHubCliApplication.java"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_agent,node_configuration_service,node_reload,node_agent_context toneBlue
class node_scheduler,node_monitoring_task,node_engine,node_extension_manager,node_protocols,node_os_commands,node_telemetry_manager,node_hardware toneAmber
class node_otel_export toneMint
class node_opamp,node_opamp_client,node_upgrade,node_tunnel toneRose
class node_web_server,node_web_controllers,node_web_ui,node_mcp_tools,node_cli,node_operator,node_otel_collector toneIndigo
```

## Components

### Configuration and control

- [Agent runtime](https://github.com/metricshub/metricshub-community/blob/main/metricshub-agent/src/main/java/org/metricshub/agent/MetricsHubAgentApplication.java): `metricshub-agent/src/main/java/org/metricshub/agent/MetricsHubAgentApplication.java`
- [Configuration service](https://github.com/metricshub/metricshub-community/blob/main/metricshub-agent/src/main/java/org/metricshub/agent/service/ConfigurationService.java): `metricshub-agent/src/main/java/org/metricshub/agent/service/ConfigurationService.java`
- [Configuration reload](https://github.com/metricshub/metricshub-community/blob/main/metricshub-agent/src/main/java/org/metricshub/agent/service/ConfigurationReloadService.java): `metricshub-agent/src/main/java/org/metricshub/agent/service/ConfigurationReloadService.java`
- [Active agent context](https://github.com/metricshub/metricshub-community/blob/main/metricshub-agent/src/main/java/org/metricshub/web/AgentContextHolder.java): `metricshub-agent/src/main/java/org/metricshub/web/AgentContextHolder.java`

### Monitoring and collection

- [Monitoring scheduler](https://github.com/metricshub/metricshub-community/blob/main/metricshub-agent/src/main/java/org/metricshub/agent/service/TaskSchedulingService.java): `metricshub-agent/src/main/java/org/metricshub/agent/service/TaskSchedulingService.java`
- [Monitoring tasks](https://github.com/metricshub/metricshub-community/blob/main/metricshub-agent/src/main/java/org/metricshub/agent/service/task/MonitoringTask.java): `metricshub-agent/src/main/java/org/metricshub/agent/service/task/MonitoringTask.java`
- [MetricsHub engine](https://github.com/metricshub/metricshub-community/tree/main/metricshub-engine): `metricshub-engine`
- [Protocol extensions](https://github.com/metricshub/metricshub-community/blob/main/metricshub-engine/src/main/java/org/metricshub/engine/extension/ExtensionManager.java): `metricshub-engine/src/main/java/org/metricshub/engine/extension/ExtensionManager.java`
- [Protocol connectors](https://github.com/metricshub/metricshub-community/blob/main/metricshub-http-extension/src/main/java/org/metricshub/extension/http/HttpRequestExecutor.java): `metricshub-http-extension/src/main/java/org/metricshub/extension/http/HttpRequestExecutor.java`
- [OS commands](https://github.com/metricshub/metricshub-community/blob/main/metricshub-oscommand-extension/src/main/java/org/metricshub/extension/oscommand/OsCommandService.java): `metricshub-oscommand-extension/src/main/java/org/metricshub/extension/oscommand/OsCommandService.java`
- [Monitor telemetry](https://github.com/metricshub/metricshub-community/blob/main/metricshub-engine/src/main/java/org/metricshub/engine/telemetry/TelemetryManager.java): `metricshub-engine/src/main/java/org/metricshub/engine/telemetry/TelemetryManager.java`
- [Energy enrichment](https://github.com/metricshub/metricshub-community/blob/main/metricshub-hardware/src/main/java/org/metricshub/hardware/HardwareEnergyPostExecutionService.java): `metricshub-hardware/src/main/java/org/metricshub/hardware/HardwareEnergyPostExecutionService.java`

### Telemetry output

- [OpenTelemetry export](https://github.com/metricshub/metricshub-community/blob/main/metricshub-agent/src/main/java/org/metricshub/agent/opentelemetry/MetricsExporter.java): `metricshub-agent/src/main/java/org/metricshub/agent/opentelemetry/MetricsExporter.java`

### Remote management

- [OpAMP management](https://github.com/metricshub/metricshub-community/blob/main/metricshub-agent/src/main/java/org/metricshub/agent/opamp/OpAmpService.java): `metricshub-agent/src/main/java/org/metricshub/agent/opamp/OpAmpService.java`
- [OpAMP client](https://github.com/metricshub/metricshub-community/blob/main/metricshub-opamp-client/src/main/java/org/metricshub/opamp/client/OpampClient.java): `metricshub-opamp-client/src/main/java/org/metricshub/opamp/client/OpampClient.java`
- [Automatic upgrades](https://github.com/metricshub/metricshub-community/blob/main/metricshub-agent/src/main/java/org/metricshub/agent/upgrade/UpgradeManager.java): `metricshub-agent/src/main/java/org/metricshub/agent/upgrade/UpgradeManager.java`
- [Remote tunnel](https://github.com/metricshub/metricshub-community/blob/main/metricshub-agent/src/main/java/org/metricshub/agent/tunnel/TunnelService.java): `metricshub-agent/src/main/java/org/metricshub/agent/tunnel/TunnelService.java`

### User interfaces

- [Web server](https://github.com/metricshub/metricshub-community/blob/main/metricshub-agent/src/main/java/org/metricshub/web/MetricsHubAgentServer.java): `metricshub-agent/src/main/java/org/metricshub/web/MetricsHubAgentServer.java`
- [Web API](https://github.com/metricshub/metricshub-community/tree/main/metricshub-agent/src/main/java/org/metricshub/web/controller): `metricshub-agent/src/main/java/org/metricshub/web/controller`
- [Web UI](https://github.com/metricshub/metricshub-community/blob/main/metricshub-web/react/src/App.jsx): `metricshub-web/react/src/App.jsx`
- [MCP query tools](https://github.com/metricshub/metricshub-community/blob/main/metricshub-agent/src/main/java/org/metricshub/web/mcp/ExecuteHttpQueryService.java): `metricshub-agent/src/main/java/org/metricshub/web/mcp/ExecuteHttpQueryService.java`
- [Command-line interface](https://github.com/metricshub/metricshub-community/blob/main/metricshub-agent/src/main/java/org/metricshub/cli/MetricsHubCliApplication.java): `metricshub-agent/src/main/java/org/metricshub/cli/MetricsHubCliApplication.java`

### Other components

- **Operator**
- **OTel Collector**

## Connections

- Operator → Web UI: configures
- Operator → Command-line interface: configures
- Web UI → Web server: uses
- Web server → Web API: serves
- Web API → Active agent context: reads context
- Agent runtime → Configuration service: loads config
- Configuration service → Configuration reload: supports reload
- Configuration reload → Active agent context: publishes context (evidence: `metricshub-agent/src/main/java/org/metricshub/web/AgentContextHolder.java`)
- Agent runtime → Monitoring scheduler: starts scheduling
- Monitoring scheduler → Monitoring tasks: schedules
- Monitoring tasks → MetricsHub engine: invokes monitoring
- MetricsHub engine → Protocol extensions: loads extensions (evidence: `metricshub-engine/src/main/java/org/metricshub/engine/extension/ExtensionManager.java`)
- Protocol extensions → Protocol connectors: dispatches queries
- Protocol extensions → OS commands: dispatches commands
- OS commands → Operator: queries host
- MetricsHub engine → Monitor telemetry: records monitors (evidence: `metricshub-engine/src/main/java/org/metricshub/engine/extension/ExtensionManager.java`)
- Monitor telemetry → Energy enrichment: enriches metrics (evidence: `metricshub-hardware/src/main/java/org/metricshub/hardware/HardwareEnergyPostExecutionService.java`)
- Agent runtime → OpenTelemetry export: exports metrics
- OpenTelemetry export → OTel Collector: sends telemetry
- Web API → MCP query tools: offers queries
- MCP query tools → Active agent context: resolves context (evidence: `metricshub-agent/src/main/java/org/metricshub/web/mcp/ExecuteHttpQueryService.java`)
- MCP query tools → Protocol connectors: executes HTTP (evidence: `metricshub-agent/src/main/java/org/metricshub/web/mcp/ExecuteHttpQueryService.java`)
- Agent runtime → OpAMP management: runs management
- OpAMP management → OpAMP client: uses client
- OpAMP management → Automatic upgrades: handles offers
- Agent runtime → Remote tunnel: provides tunneling
