MetricsHub
MetricsHub Enterprise 1.0.00
-
Home
- Guides
Quick Start - Windows
This quick start guide provides step-by-step instructions for operating MetricsHub and Prometheus in a Windows 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
-
Download the latest package,
metricshub-windows-0.9.06.zip
, from the MetricsHub Releases[1] page -
Right-click on the archive, select Extract All…, enter
C:\Program Files\
, and click Extract. This will place theMetricsHub
directory inC:\Program Files\
.
Note: You will need administrative privileges to unzip into
C:\Program Files
.
Step 2: Install Prometheus
-
Download prometheus-{version}.windows-{architecture}.zip[2]
-
Right-click the archive, select Extract All…", enter
C:\Program Files\
, and click Extract. This will place theprometheus-{version}.windows-{architecture}
directory inC:\Program Files\
-
Under
C:\Program Files\
, rename theprometheus-{version}.windows-{architecture}
directory toPrometheus
.
Note: Make sure to use the corresponding Prometheus version and CPU architecture for
{version}
and{architecture}
. For example,prometheus-2.52.0.windows-amd64
for version2.52.0
andamd64
architecture.
Step 3: Configure the MetricsHub Agent
Create your configuration file
-
Before creating your configuration file (
metricshub.yaml
), ensure that the required directories exist. If they do not, open a Command Prompt and run the following commands to create them:mkdir C:\ProgramData\MetricsHub mkdir C:\ProgramData\MetricsHub\config
-
Copy the configuration example
metricshub-example.yaml
available inC:\Program Files\MetricsHub\config\
, paste it intoC:\ProgramData\MetricsHub\config\
and rename the file tometricshub.yaml
.
Configure localhost monitoring
The metricshub-example.yaml
file you copied already contains the necessary configuration to monitor your localhost through WMI. The relevant section should look like this:
resources:
localhost:
attributes:
host.name: localhost
host.type: windows
protocols:
wmi:
timeout: 120
Open the C:\ProgramData\MetricsHub\config\metricshub.yaml
file and search for the above section to verify that the configuration is active.
If you wish to use a protocol other than WMI
(such as HTTP
, PING
, SNMP
, SSH
, IPMI
, WBEM
, or WinRM
), refer to the configuration examples provided in C:\ProgramData\MetricsHub\config\metricshub.yaml
.
Configure Metrics Exporter
In the same configuration file (C:\ProgramData\MetricsHub\config\metricshub.yaml
), 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
Step 4: Start Prometheus and MetricsHub
Start Prometheus
-
Run the below command as administrator to access the directory where Prometheus is installed:
cd "C:\Program Files\Prometheus"
-
Run the below command to start Prometheus:
prometheus.exe --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
-
Type localhost:9090[3] in your Web browser.
Start the MetricsHub Agent
Run the below command as administrator to start the MetricsHub Agent:
cd "C:\Program Files\MetricsHub"
MetricsHubServiceManager.exe
Step 5: Perform Last Checks
Verify that metrics are sent to Prometheus
In Prometheus[3], search for any metrics starting with metricshub_
or hw_
to confirm that data is actually received.
Check Logs
Several log files are created under C:\Users\{Username}\AppData\Local\metricshub\logs
as soon as the MetricsHub Agent is started:
- a global
MetricsHub
log file - one log file per configured host.
You can configure the log level in the C:\ProgramData\MetricsHub\config\metricshub.yaml
file by setting the loggerLevel
parameter to:
info
for high level informationwarn
for logging warning messages that indicate potential issues which are not immediately criticalall
,trace
, ordebug
for more comprehensive detailserror
orfatal
for identifying critical issues.
The most common errors you may encounter are:
-
Incorrect Indentation
An incorrect indentation in the
metricshub.yaml
file prevents the MetricsHub Agent from starting and generates the following exception in themetricshub-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
-
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.
-
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.