MetricsHub®, is an open-source metrics collection tool that leverages OpenTelemetry for vendor-neutral observability.

curl -fsSL https://get.metricshub.com | bash

This is a multi-module project:

• /: The root (parent of all submodules)
• metricshub-engine: The brain, the heart of this project. It houses the core logic and essential functionalities that power the entire system. It also loads each extension in its own dedicated class loader, so one extension's libraries and service registrations can never conflict with another's; extensions declare dependencies on sibling extensions through the MetricsHub-Extension-Requires manifest attribute.
• metricshub-agent: The MetricsHub Agent module includes a Command-Line Interface (CLI) and is responsible for interacting with the MetricsHub engine. It acts as an entry point, collecting and transmitting data to the OpenTelemetry Collector.
• metricshub-ipmi-extension: Provides support for the Intelligent Platform Management Interface (IPMI) to monitor and manage hardware at the firmware level.
• metricshub-oscommand-extension: Allows execution of OS-level commands and scripts to gather metrics and other data from the operating system.
• metricshub-snmp-extension-common: Contains common functionalities and utilities used by SNMP-based extensions.
• metricshub-snmp-extension: Enables Simple Network Management Protocol (SNMP) for monitoring and managing network devices.
• metricshub-snmpv3-extension: Adds support for SNMPv3, which includes enhanced security features like authentication and encryption.
• metricshub-internaldb-extension: Executes internal database queries using MetricsHub's internal database engine.
• metricshub-win-extension-common: Contains common functionalities and utilities used by Windows-specific extensions.
• metricshub-wmi-extension: Provides support for Windows Management Instrumentation (WMI) to gather detailed information about Windows systems.
• metricshub-winrm-extension: Enables the use of Windows Remote Management (WinRM) for remote management and monitoring of Windows-based systems.
• metricshub-wbem-extension: Supports the Web-Based Enterprise Management (WBEM) standard for accessing management information.
• metricshub-ping-extension: Enables testing the reachability of hosts using ICMP-based ping commands.
• metricshub-jawk-extension: Allows execution of Jawk scripts.
• metricshub-jdbc-extension: Provides support for monitoring SQL databases.
• metricshub-jmx-extension: Enables monitoring of Java applications through JMX (Java Management Extensions).
• metricshub-emulation-extension: Replays recorded protocol exchanges (HTTP, SNMP, WMI, WBEM, SSH, IPMI, JDBC, JMX) from local files, enabling offline testing and development without live infrastructure.
• metricshub-hardware: Hardware Energy and Sustainability module, dedicated to managing and monitoring hardware-related metrics, focusing on energy consumption and sustainability aspects.
• metricshub-opamp-client: In-house minimal OpAMP (Open Agent Management Protocol) client embedded in the MetricsHub Agent for remote management: status, identity and health reporting over HTTP polling, plus package-offer handling for automatic upgrades.
• metricshub-yaml-configuration-extension: Extension that loads configuration fragments from YAML files located in a configuration directory. The UI-managed metricshub-ui.yaml file is handled separately: it is always merged last, after the fragments of every configuration provider, so settings configured through the web UI override every other configuration source.
• metricshub-programmable-configuration-extension: Provides a programmable configuration mechanism, allowing users to define custom configurations through Apache Velocity scripts. Whitespace around Velocity directives in the generated YAML defaults to the lines mode, which prevents lines made only of #set, #if, #foreach or #end directives from producing blank lines, while preserving the indentation of the surrounding content. This default can be overridden with the parser.space_gobbling JVM system property, set through the JVM options of the MetricsHub launcher, for example -Dparser.space_gobbling=structured. The accepted values are none, bc, lines and structured; any other value is rejected with a warning and falls back to lines.
• metricshub-web: Provides a user interface for interacting with MetricsHub features and functionalities.
• metricshub-it-common: Contains common code and utilities used by integration tests across various modules.
• metricshub-assets: Generates the assets required to package MetricsHub Community for Windows, Debian, RedHat, and Docker platforms.

• Have Maven 3.x properly installed and configured.
• Latest LTS Release of JDK 25 (Temurin).

MetricsHub Community ships with a custom runtime built with jlink from Eclipse Temurin. The Temurin version is defined in the root pom.xml as metricshub-jre.version and is downloaded from the Adoptium API during packaging (see metricshub-assets scripts).

To access snapshot artifacts from Maven Central Snapshots, you need to explicitly configure the repository in your Maven ~/.m2/settings.xml.

Add the following <repository> entry:

<repositories>
    ...
    <repository>
        <id>central-snapshots</id>
        <name>Maven Repository Switchboard</name>
        <url>https://central.sonatype.com/repository/maven-snapshots</url>
        <releases>
            <enabled>false</enabled>
        </releases>
        <snapshots>
            <enabled>true</enabled>
        </snapshots>
    </repository>
    ...
</repositories>

💡 This is required if your build depends on snapshot versions of dependencies hosted on Maven Central’s snapshots repository.

To build the MetricsHub package, from ./metricshub:

$ mvn clean package

• Host: Windows
• Prerequisites: WiX Toolset 3.11 configured in the PATH
• Execute the mvn package command within the MetricsHub root directory (metricshub).
• Execute the metricshub-assets\target\assets-local\build-windows.cmd command. The command will create a packages sub-directory containing the unsigned .msi file and the MetricsHub application folder.

• Host: Windows
• Prerequisites: Docker Desktop with QEMU enabled for multi-arch builds
• Execute the mvn package command within the MetricsHub root directory (metricshub).
• Execute the metricshub-assets\target\assets-local\build-docker-linux.cmd command. The command will create a packages sub-directory containing the x86 and arm64 .deb and .rpm files and the metricshub application folder.

• Host: Linux
• Debian Prerequisites: The following packages must be installed fakeroot and gcc-multilib (for x86)
• RedHat Prerequisites: The following package must be installed rpm-build
• Execute the mvn package command within the MetricsHub root directory (metricshub).
• Execute the metricshub-assets/target/assets-local/build-linux.sh command. The command will create a packages sub-directory containing the .deb or .rpm file and the metricshub application folder for your Linux distribution and CPU architecture.

In this project, we use Checkstyle to ensure consistent and clean Java code across our codebase.

Maven Checkstyle Plugin is configured globally in the main pom.xml file, and it verifies the Java code during the build process:

	<plugin>
		<artifactId>maven-checkstyle-plugin</artifactId>
		<version>3.3.0</version>
		<configuration>
			<sourceEncoding>${project.build.sourceEncoding}</sourceEncoding>
			<configLocation>checkstyle.xml</configLocation>
		</configuration>
		<executions>
			<execution>
				<id>validate</id>
				<phase>validate</phase>
				<goals>
					<goal>checkstyle</goal>
					<goal>check</goal>
				</goals>
			</execution>
		</executions>
	</plugin>

The Checkstyle rules that govern our code quality and style are defined in the ./checkstyle.xml file. It's important to adhere to these rules to maintain code consistency and quality throughout the project.

The build will fail if one or more Checkstyle rules are violated.

To perform Checkstyle analysis and generate a report on violations, navigate to the directory of the Maven project you wish check and run the following mvn command:

mvn checkstyle:checkstyle

All the encountered Checkstyle issues are reported under the target/site directory.

To perform Checkstyle analysis and output violations to the console, navigate to the directory of the Maven project you wish check and run the following mvn command:

mvn checkstyle:check

In this project, we maintain code formatting using prettier-java, a tool that helps ensure clean and consistent Java code. It automatically formats your code according to a predefined set of rules.

To automatically format the Java code in a specific Maven module, navigate to the directory of the Maven project you wish to format and run the following mvn command:

mvn prettier:write

To validate the formatted code, navigate to the directory of the Maven project you wish to check and run the following mvn command:

mvn prettier:check

The build will fail if you forgot to run Prettier.

Before you submit a PR, make sure to use the available tools for code formatting, and ensure that the style checks and unit tests pass.

License is GNU Affero General Public License v3.0. Each source file must include the AGPL-3.0 header (build will fail otherwise). To update source files with the proper header, simply execute the below command:

mvn license:update-file-header

The agent can be managed by a MetricsHub Central server over two outbound channels, both declared under the single central: section of metricshub.yaml and both disabled by default:

• OpAMP — the agent polls the server, reporting its identity, status and health, and performs the automatic package upgrades the server offers (Debian, RPM and Windows MSI installations).
• The Central tunnel — a persistent outbound WebSocket over which the agent advertises the troubleshooting tools it exposes and the hosts it actually monitors, so the Central can run those tools against any monitored host from a single assistant.

Neither channel needs an inbound firewall rule: the agent always dials out, and every server instruction is an offer the agent validates against its own local policy before acting on it.

See Fleet Management — OpAMP and the Central Tunnel for the central: configuration reference, the workflows and the security decisions, and Central Tunnel Protocol for the wire format.

The official MetricsHub product documentation is available at:

https://metricshub.com/docs/latest

The following documents are intended for internal use or as intermediary technical references within the repository.

TECHNICAL_NOTES.md collects the behavior and configuration details that have no document of their own: