Skip to main content

Quick Start - Community Edition

This quick start guide provides step-by-step instructions for operating MetricsHub Community Edition and Prometheus in your environment, ensuring you can efficiently monitor your systems.

After completing this quick start, you will have:

  • MetricsHub and Prometheus installed on your machine
  • The MetricsHub Agent configured to collect hardware metrics from your local host and push data to Prometheus
  • MetricsHub and Prometheus up and running
  • Hardware metrics available in Prometheus.

Step 1: Install MetricsHub​

  1. Download the latest .deb package from metricshub.com/download

  2. Install it:

    sudo dpkg -i metricshub-community_*_amd64.deb

Step 2: Install Prometheus​

Download the latest Prometheus package from the Prometheus download site matching your OS and architecture.

  1. Download the prometheus-*.linux-*.tar.gz package

  2. Extract it into /opt/prometheus:

    sudo mkdir -p /opt/prometheus && sudo tar -xzvf prometheus-*.linux-*.tar.gz -C /opt/prometheus --strip-components=1

Step 3: Configure the MetricsHub Agent​

Create your configuration file​

sudo cp /opt/metricshub/lib/config/metricshub-example.yaml /opt/metricshub/lib/config/metricshub.yaml

Configure localhost monitoring​

The metricshub-example.yaml file already contains the necessary configuration to monitor your localhost. Verify the relevant section:

resources:
  localhost:
    attributes:
      host.name: localhost
      host.type: linux
    protocols:
      osCommand:
        timeout: 120

Open /opt/metricshub/lib/config/metricshub.yaml to verify the configuration.

For other protocols (HTTP, PING, SNMP, SSH, IPMI, WBEM, or WinRM), refer to the configuration examples in the file.

Configure Metrics Exporter​

Add the below configuration under the otel section to push metrics to Prometheus:

otel:
  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

Step 4: Start Prometheus and MetricsHub​

Start Prometheus​

cd /opt/prometheus
sudo ./prometheus --config.file=prometheus.yml --web.console.templates=consoles --web.console.libraries=console_libraries --storage.tsdb.retention.time=2h --web.enable-lifecycle --web.enable-remote-write-receiver --web.route-prefix=/ --enable-feature=exemplar-storage --enable-feature=otlp-write-receiver

Open localhost:9090 in your browser to verify Prometheus is running.

Start the MetricsHub Agent​

cd /opt/metricshub/bin
sudo ./service

Step 5: Perform Last Checks​

Verify that metrics are sent to Prometheus​

In Prometheus, search for any metrics starting with metricshub_ or hw_ to confirm that data is actually received.

Check Logs​

Several log files are created as soon as the MetricsHub Agent is started:

  • a global MetricsHub log file
  • one log file per configured host.

The log files are stored in the following locations, depending on the environment:

  • Linux: /opt/metricshub/lib/logs
  • Windows:
    • ./logs (relative to the working directory, if writable)
    • %LOCALAPPDATA%\MetricsHub\logs (if ./logs is not writable)

You can configure the log level in the metricshub.yaml file by setting the loggerLevel parameter to:

  • info for high level information
  • warn for logging warning messages that indicate potential issues which are not immediately critical
  • all, trace, or debug for more comprehensive details
  • error or fatal for identifying critical issues.

metricshub.yaml is stored in:

  • /opt/metricsHub/lib/config/(Linux environments)
  • or C:\ProgramData\MetricsHub\config\ (Windows environments).

The most common errors you may encounter are:

  1. Incorrect Indentation

    An incorrect indentation in the metricshub.yaml file prevents the MetricsHub Agent from starting and generates the following exception in the metricshub-agent-global-error-{timestamp}.log file:

    [2024-04-30T15:56:16,944][ERROR][o.s.m.a.MetricsHubAgentApplication] Failed to start MetricsHub Agent.
    com.fasterxml.jackson.dataformat.yaml.snakeyaml.error.MarkedYAMLException: mapping values are not allowed here in 'reader', line 29, column 16:
        host.type:windows

  2. Wrong Host Configuration

    The following entry will be created in the metricshub-agent-{hostname}-{timestamp}.log file if the host configured cannot be reached:

    [o.s.m.e.c.h.NetworkHelper] Hostname {hostname} - Could not resolve the hostname to a valid IP address. The host is considered remote.

    If the host is correctly configured, ensure it is reachable by pinging it and testing your network.

  3. Failure to export metrics

The following error occurs if a local OTLP receiver is unavailable to collect MetricsHub logs:

Feb 27, 2024 1:24:26 PM io.opentelemetry.sdk.internal.ThrottlingLogger doLog WARNING: Failed to export metrics.
Server responded with gRPC status code 2. Error message: Failed to connect to localhost/[0:0:0:0:0:0:0:1]:4317

To solve this problem, ensure that the OTLP receiver and more specifically the otel.exporter.otlp.metrics.endpoint and otel.exporter.otlp.logs.endpoint parameters are correctly set in the metricshub.yaml configuration file.

Next Steps​