Blog
Building MetricsHub Community from Source
From setup to Prometheus integration, learn how to build MetricsHub Community from source, benefit from expert tips, avoid pitfalls, and make it your own.
Why Build It Yourself? Ask Olivier
Olivier, a system administrator at MetricsHub, is a true Linux enthusiast. For as long as anyone can remember, his professional laptop has always run on Linux, from Slackware 14.2 to his current Debian setup. When testing a new product, he doesn’t leave anything to chance: he wants full control over every step of the process. Don’t offer him a wizard or a user interface: he lives and breathes the command line!
So it came as no surprise that, instead of downloading the pre-built MetricsHub Community packages available on metricshub.com/downloads, Olivier decided to build MetricsHub Community from source. Let’s walk through his journey and the lessons he learned along the way.
Step 1: Preparing the Foundation
-
Read the How to Build the Project documentation.
Co-authored by Nassim Boutekedjiret and Olivier, this guide is the go-to resource for anyone embarking on the adventure of building MetricsHub Community from source. -
Install Maven and Java.
If you’re running Debian sid, use the stable version of Maven to avoid known issues.root@ole-mh:~# apt install openjdk-21-jre-headless:amd64 openjdk-21-jdk-headless:amd64 root@ole-mh:~# apt install maven -t stable root@ole-mh:~# mvn --version Apache Maven 3.9.9 Maven home: /usr/share/maven Java version: 21.0.8-ea, vendor: Debian, runtime: /usr/lib/jvm/java-21-openjdk-amd64 Default locale: en_US, platform encoding: UTF-8 OS name: "linux", version: "6.12.32-amd64", arch: "amd64", family: "unix"
Step 2: Cloning the Latest Version
Cloning MetricsHub community is straightforward:
-
Visit the metricshub-community GitHub repository
-
In your workspace (e.g., /data/blog), run:
patrol@ole-mh:~# cd /data/ patrol@ole-mh:/data# ls build src patrol@ole-mh:/data# mkdir blog patrol@ole-mh:/data# cd blog/ patrol@ole-mh:/data/blog# ls patrol@ole-mh:/data/blog# git clone https://github.com/MetricsHub/metricshub-community.git
💡 Tip: Clone into a clean directory to avoid build conflicts later.
Step 3: Building MetricsHub Community
Make sure your settings.xml file is properly configured, as explained in the How to Build the Project documentation.
Example:
patrol@ole-mh:/data/blog/metricshub-community$ cat ~/.m2/settings.xml
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd">
<pluginGroups>
<pluginGroup>com.sentrysoftware.maven</pluginGroup>
</pluginGroups>
<servers>
<server>
<id>github</id>
<username>XXXXXXXXXXXXXX</username>
<password>ghp_XXXXXXXXXXXXXX</password>
</server>
</servers>
<profiles>
<profile>
<id>GH</id>
<repositories>
<repository>
<id>github</id>
<name>GitHub JRE Builder Package</name>
<url>https://maven.pkg.github.com/metricshub/metricshub-jre-builder</url>
<releases>
<enabled>true</enabled>
</releases>
<snapshots>
<enabled>true</enabled>
</snapshots>
</repository>
<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>
<repository>
<id>sonatype-snapshots</id>
<url>https://oss.sonatype.org/content/repositories/snapshots</url>
<releases>
<enabled>false</enabled>
</releases>
<snapshots>
<enabled>true</enabled>
</snapshots>
</repository>
<repository>
<id>ossrh</id>
<url>https://s01.oss.sonatype.org/content/repositories/snapshots</url>
<releases>
<enabled>false</enabled>
</releases>
<snapshots>
<enabled>true</enabled>
</snapshots>
</repository>
</repositories>
<pluginRepositories>
<pluginRepository>
<id>sonatype-snapshots</id>
<url>https://oss.sonatype.org/content/repositories/snapshots</url>
<releases>
<enabled>false</enabled>
</releases>
<snapshots>
<enabled>true</enabled>
</snapshots>
</pluginRepository>
<pluginRepository>
<id>ossrh</id>
<url>https://s01.oss.sonatype.org/content/repositories/snapshots</url>
<releases>
<enabled>false</enabled>
</releases>
<snapshots>
<enabled>true</enabled>
</snapshots>
</pluginRepository>
</pluginRepositories>
</profile>
</profiles>
<activeProfiles>
<activeProfile>GH</activeProfile>
</activeProfiles>
</settings>
Replace
An error in the settings.xml file will result in the following error to be thrown:
Run the following command:
patrol@ole-mh:/data/blog/metricshub-community# mvn clean package
A successful build will result in the following message to be displayed:
Step 4: Creating the System Service
Run the following systemd script to create the system service:
root@ole-mh:~# cat /etc/systemd/system/metricshub.service
[Unit]
Description=MetricsHub (service)
[Service]
Environment="JAVA_HOME=/usr/lib/jvm/java/"
ExecStart=/opt/metricshub/bin/service -c /opt/metricshub/config/
Restart=on-failure
[Install]
WantedBy=multi-user.target
If you see the following error, check the -c option:
[ERROR][o.m.a.MetricsHubAgentApplication] Failed to start MetricsHub Agent. java.nio.file.NotDirectoryException: /opt/metricshub/config/metricshub.yaml
At the time of writing, MetricsHub expects -c to point to a directory containing one or more configuration files. In versions earlier than 1.05, -c pointed to a single YAML configuration file. Please note that the way MetricsHub handles configuration files may evolve in future releases.
Step 5: Installing from package
To install MetricsHub Community, extract the tar package into the required directory (/opt):
root@ole-mh:~# cd /opt
root@ole-mh:~# tar -zxvf /data/blog/m8b-community/metricshub-community-linux/target/metricshub-community-linux-1.0.06-SNAPSHOT.tar.gz
Then add symbolic link to logs and configuration:
root@ole-mh:/opt/metricshub# ls -l
total 12
drwxr-xr-x 2 root root 4096 Aug 5 06:15 bin
lrwxrwxrwx 1 root root 10 Jun 30 09:57 config -> lib/config
drwxr--r-- 3 root root 4096 Apr 18 23:05 data
drwxr-xr-x 10 root root 4096 Aug 5 06:15 lib
lrwxrwxrwx 1 root root 8 Apr 7 15:46 logs -> lib/logs
Step 6: Configuring MetricsHub Community
Instead of routing data through the OTel Collector, Olivier chose to send metrics directly from MetricsHub to Prometheus, using the configuration below:
otel:
otel.metrics.exporter: otlp
otel.exporter.otlp.metrics.endpoint: http://localhost:9090/api/v1/otlp/v1/metrics
otel.exporter.otlp.metrics.protocol: http/protobuf
otel.exporter.otlp.metrics.append_resource_attributes: true
In Prometheus, he defined the following defaults to enable data ingestion and set a 60-day retention period:
root@ole-mh:/opt/prometheus# cat prometheus-default
# Set the command-line arguments to pass to the server.
# Due to shell escaping, to pass backslashes for regexes, you need to double
# them (\\d for \d). If running under systemd, you need to double them again
# (\\\\d to mean \d), and escape newlines too.
ARGS="--config.file=/opt/prometheus/prometheus.yml --storage.tsdb.path=/opt/prometheus/data/ --web.enable-otlp-receiver --web.enable-remote-write-receiver --storage.tsdb.retention.time=60d --web.enable-lifecycle –enable-feature=exemplar-storage"
💡 Tip: If you encounter issues in Prometheus with underscores (_) and dots (.) in metric names, adjust the configuration as follows:
otlp:
# Ingest OTLP data keeping underscores and unit in metric names.
translation_strategy: UnderscoreEscapingWithSuffixes
Wrapping Up
By building MetricsHub Community from source, Olivier ensured he understood and controlled every part of the process, from code to service configuration to Prometheus integration.
Got lost along the way? Join us on Slack to ask questions, share your experience, and help shape the future of MetricsHub Community.