diff --git a/metricshub-doc/pom.xml b/metricshub-doc/pom.xml index 5b73ace89..50a9f20fa 100644 --- a/metricshub-doc/pom.xml +++ b/metricshub-doc/pom.xml @@ -105,7 +105,22 @@ org.apache.maven.plugins maven-project-info-reports-plugin - 3.4.5 + 3.5.0 + + + + ci-management + dependencies + dependency-info + distribution-management + issue-management + licenses + plugins + scm + summary + + + diff --git a/metricshub-doc/src/site/markdown/configuration/configure-monitoring.md b/metricshub-doc/src/site/markdown/configuration/configure-monitoring.md index 873943b4b..42adcc8ec 100644 --- a/metricshub-doc/src/site/markdown/configuration/configure-monitoring.md +++ b/metricshub-doc/src/site/markdown/configuration/configure-monitoring.md @@ -109,7 +109,7 @@ resourceGroups: ``` -> Note: Refer to the [sustainability metrics page](../sustainability/configure-sustainability-metrics.md#example-for-distributed-infrastructure) to configure MetricsHub for sustainability metrics reporting. +> Note: Refer to the [sustainability metrics page](../guides/configure-sustainability-metrics.md#example-for-distributed-infrastructure) to configure MetricsHub for sustainability metrics reporting. ### Centralized infrastructure @@ -127,7 +127,7 @@ resources: ``` -> Note: Refer to the [sustainability metrics page](../sustainability/configure-sustainability-metrics.md#example-for-centralized-infrastructure) to configure MetricsHub for sustainability metrics reporting. +> Note: Refer to the [sustainability metrics page](../guides/configure-sustainability-metrics.md#example-for-centralized-infrastructure) to configure MetricsHub for sustainability metrics reporting. ### Unique vs. shared characteristics @@ -629,7 +629,7 @@ service-group: #### Enterprise Edition authentication -In the Enterprise Edition, the **MetricsHub**'s internal `OTLP Exporter` authenticates itself with the _OpenTelemetry Collector_'s [OTLP gRPC Receiver](send-data.md#OTLP_gRPC) by including the HTTP `Authorization` request header with the credentials. +In the Enterprise Edition, the **MetricsHub**'s internal `OTLP Exporter` authenticates itself with the _OpenTelemetry Collector_'s [OTLP gRPC Receiver](send-telemetry.md#otlp-grpc) by including the HTTP `Authorization` request header with the credentials. These settings are already configured in the `config/metricshub.yaml` file of **MetricsHub Enterprise Edition**. Changing them is **not recommended** unless you are familiar with managing communication between the **MetricsHub** `OTLP Exporter` and the _OpenTelemetry Collector_'s `OTLP Receiver`. @@ -651,7 +651,7 @@ resourceGroups: # ... where `` credentials are built by first joining your username and password with a colon (`myUsername:myPassword`) and then encoding the value in `base64`. -> **Warning**: If you update the *Basic Authentication Header*, you must generate a new `.htpasswd` file for the [OpenTelemetry Collector Basic Authenticator](send-data.md#Basic_Authenticator). +> **Warning**: If you update the *Basic Authentication Header*, you must generate a new `.htpasswd` file for the [OpenTelemetry Collector Basic Authenticator](send-telemetry.md#basic-authenticator). #### Community Edition authentication @@ -803,7 +803,7 @@ resourceGroups: The core engine will perform automatic detection on connectors categorized under `hardware`, excluding the `MIB2` connector. -To know which connectors are available, refer to [Community Connector Platforms](../platform-requirements.html#!). +To know which connectors are available, refer to [Connectors Directory](../metricshub-connectors-directory.html). Otherwise, you can list the available connectors using the below command: @@ -811,7 +811,7 @@ Otherwise, you can list the available connectors using the below command: $ metricshub -l ``` -For more information about the `metricshub` command, refer to [MetricsHub CLI (metricshub)](../troubleshooting/cli.md). +For more information about the `metricshub` command, refer to [MetricsHub CLI (metricshub)](../guides/cli.md). #### Patch Connectors diff --git a/metricshub-doc/src/site/markdown/configuration/send-telemetry.md b/metricshub-doc/src/site/markdown/configuration/send-telemetry.md index a290ba909..fbe7930e2 100644 --- a/metricshub-doc/src/site/markdown/configuration/send-telemetry.md +++ b/metricshub-doc/src/site/markdown/configuration/send-telemetry.md @@ -35,9 +35,9 @@ To configure the OpenTelemetry Collector of **MetricsHub Enterprise**, edit the > **Warning**: Only update this section if you customized the [MetricsHub Agent settings](configure-monitoring.html#a-28optional-29-additional-settings). The **MetricsHub Agent** pushes the collected data to the [`OTLP Receiver`](https://github.com/open-telemetry/opentelemetry-collector/tree/main/receiver/otlpreceiver) via [gRPC](https://grpc.io/) on port **TCP/4317**. -The `OTLP Receiver` is configured by default with the self-signed certificate `security/otel.crt` and the private key `security/otel.key` to enable the TLS protocol. If you wish to set your own certificate file, configure the **MetricsHub Agent** with the correct [Trusted Certificates File](send-data.html#trusted-certificates-file). Because the `OTLP Exporter` of the **MetricsHub Agent** performs hostname verification, you will also have to add the `localhost` entry (`DNS:localhost,IP:127.0.0.1`) to the `Subject Alternative Name (SAN)` extension of the new generated certificate. +The `OTLP Receiver` is configured by default with the self-signed certificate `security/otel.crt` and the private key `security/otel.key` to enable the TLS protocol. If you wish to set your own certificate file, configure the **MetricsHub Agent** with the correct [Trusted Certificates File](send-telemetry.html#trusted-certificates-file). Because the `OTLP Exporter` of the **MetricsHub Agent** performs hostname verification, you will also have to add the `localhost` entry (`DNS:localhost,IP:127.0.0.1`) to the `Subject Alternative Name (SAN)` extension of the new generated certificate. -Clients requests are authenticated with the [Basic Authenticator extension](configure-monitoring.html#basic-authentication-header). +Clients requests are authenticated with the [Basic Authenticator extension](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/extension/basicauthextension). ```yaml otlp: @@ -106,7 +106,7 @@ You can configure several exporters in the same instance of the *OpenTelemetry C The [healthcheck](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/extension/healthcheckextension) extension checks the status of **MetricsHub Enterprise** . It is activated by default and runs on port 13133 ([`http://localhost:13133`](http://localhost:13133)). -Refer to [Check the collector is up and running](../troubleshooting/status.html#Check_collector_is_up_and_running) for more details. +Refer to [Check the collector is up and running](../guides/status.html#check-the-collector-is-up-and-running) for more details. #### zpages @@ -116,7 +116,7 @@ The **zpages** extension provides debug information about all the different comp * details about the active pipeline * activity details of each receiver and exporter configured in the pipeline. -Refer to [Check the pipelines status](../troubleshooting/status.html#check-the-pipelines-status) for more details. +Refer to [Check the pipelines status](../guides/status.html#check-the-pipelines-status) for more details. #### Basic Authenticator @@ -131,7 +131,7 @@ Refer to the [Apache htpasswd](https://httpd.apache.org/docs/2.4/programs/htpass The `.htpasswd` file is stored in the `security` directory. -> **Warning**: If a different password is specified in the `.htpasswd` file, update the [Basic Authentication Header](configure-monitoring.html#basic-authentication-header) of the **MetricsHub Agent**. +> **Warning**: If a different password is specified in the `.htpasswd` file, update the [Basic Authentication Header](configure-monitoring.html#enterprise-edition-authentication) of the **MetricsHub Agent**. ### The Pipeline @@ -188,7 +188,7 @@ otel: where `` should be replaced with the hostname or IP address of the server where *Prometheus* is running. > **Note:** -> For specific configuration details, refer to the [OpenTelemetry Auto-Configure documentation](https://github.com/open-telemetry/opentelemetry-java/tree/main/sdk-extensions/autoconfigure). This resource provides information about the properties to be configured depending on your deployment requirements. +> For specific configuration details, refer to the [OpenTelemetry Auto-Configure documentation](https://opentelemetry.io/docs/languages/java/configuration/). This resource provides information about the properties to be configured depending on your deployment requirements. #### Trusted certificates file diff --git a/metricshub-doc/src/site/markdown/troubleshooting/cli.md b/metricshub-doc/src/site/markdown/guides/cli.md similarity index 97% rename from metricshub-doc/src/site/markdown/troubleshooting/cli.md rename to metricshub-doc/src/site/markdown/guides/cli.md index 47af238ac..e6af727ed 100644 --- a/metricshub-doc/src/site/markdown/troubleshooting/cli.md +++ b/metricshub-doc/src/site/markdown/guides/cli.md @@ -1,305 +1,305 @@ -keywords: cli -description: The MetricsHub CLI is the core MetricsHub's engine wrapped in a command line interface. System administrators can easily invoke this tool in a shell to discover and report problems related to the specified resources, including hardware, systems, applications, services, etc. - -# MetricsHub CLI (`metricshub`) - - - -## Overview - -The `metricshub` CLI is the core **MetricsHub**'s engine wrapped in a command line interface. System administrators can easily invoke this tool in a shell to discover and report problems related to the specified resources, including hardware, systems, applications, services, etc. - -The detailed list of systems supported by the **MetricsHub** community (manufacturer and product family and the required instrumentation stack) is listed in [Community Connectors Library](../platform-requirements.html). - -The quantity and quality of the information that **MetricsHub** will gather depends on the instrumentation stack available on the targeted resource (host). - -![Output example for an Hitachi system](../images/metricshub-hitachi.png) - -Only a few options are required to run the `metricshub` command: - -* Hostname or IP address of the device to be monitored -* Device type -* Protocols to be used: - * HTTP - * IPMI-over-LAN - * SSH - * SNMP - * SNMPV3 - * WBEM - * WMI (on Windows only) -* Credentials - -![Usage of MetricsHub](../images/metricshub-usage.png) - -The `metricshub` command can be used to troubleshoot the monitoring performed by the **MetricsHub Agent** (the core engine). - -## The Basics - -The `metricshub` command invokes the *MetricsHub Engine* against one resource and performs 3 tasks: - -1. Detection of the instrumentation stack on the targeted resource (host) -2. Discovery of the resource's components -3. Collection of metrics and status for each resource's component - -The `metricshub` command requires a few parameters to run: - -* the hostname to connect to -* the type of the resource (Windows, Linux, Management, Storage, Network, AIX, HP-UX, Solaris) -* the protocols to use to gather information from the resource (HTTP, IPMI, SNMP, SNMPV3, SSH, WBEM or WMI) -* the credentials - -Example: - -```batch -$ metricshub server01 -t win --snmp 1 --community secret -``` - -The above command will connect to `server01` (a `Win`dows system), and will detect which instrumentation stack responds to `SNMP` version `1` with the `secret` community. - -Assuming **server01** is an *Hitachi* server, the `metricshub` output will look like: - -![Monitoring the server01 Windows system with SNMP](../images/metricshub-hitachi.png) - -To learn more about the various options available, simply run the below command: - -```batch -$ metricshub -h -``` - -### Verbose Modes - -To get additional details about the operations performed by the *MetricsHub Engine*, run: - -* `-v` to display internal warning messages (**WARN**) -* `-vv` to get details about each operation performed (**INFO**) -* `-vvv` to get initialization and connections details (**DEBUG**) -* `-vvvv` to get full visibility about what is happening (**TRACE**) - -## Examples - -### Storage System, REST API - -```batch -$ metricshub STOR01 -t storage --https -u USER -``` - -This command will connect to the `STOR01` `storage` system in `HTTPS` (port 443 by default) and check whether a known REST API responds with the `USER` credentials. The password will be asked for interactively. Use the `-p P4SSW0RD` option to specify the password directly in the command line (**not secure!**). - -### Linux, SNMP v1 - -```batch -$ metricshub HOST02 -t linux --snmp 1 --community COMM02 -``` - -This command will connect to the `HOST02` `Linux` system using `SNMP` version `1` and the `COMM02` community. If a known SNMP agent is running on this host, `metricshub` will leverage it to discover the physical components of the system and collect various metrics. - -> Note: If no SNMP community is specified, **public** is assumed by default. - -### Storage System, SNMP v2c - -```batch -$ metricshub CISC03 -t sto --snmp 2 -``` - -This command will connect to the `CISC03` SAN switch (`sto`rage) using `SNMP` version `2`. - -> Note: SAN switches fall into the **Storage** category of systems, like disk arrays and tape libraries, and not in the ~~Network~~ category, like network switches and IP routers. - -### Storage System, SNMP v3 - -```batch -$ metricshub STOR02 -t storage --snmpv3 --snmpv3-auth SHA --snmpv3-username USERA --snmpv3-password MySECRET --snmpv3-privacy DES --snmpv3-retryIntervals 5,10,15 --snmpv3-privacy-password MyPrivacySECRET -``` - -This command will connect to the `STOR02` storage system (`storage`) using `SNMP` version `3`. - -### Windows, WMI and SNMP v2c - -```batch -C:\Program Files\MetricsHub> metricshub WIN04 -t win --snmp 2 --wmi -``` - -This command will connect to the `WIN04` `Win`dows system using `SNMP` version `2` with the **public** (default) community, and `WMI` as the current. - -> Note: The WMI protocol can only be used from a Windows system to monitor another Windows system. - -### Windows, WMI and WBEM (Alternate Credentials) - -```batch -C:\Program Files\MetricsHub> metricshub WIN05 -t win --wbem --wbem-username USERA --wmi --wmi-username WINUSER -``` - -This command will connect to the `WIN05` `Win`dows system using `WBEM` as `USERA`, and `WMI` as `WINUSER`. The WBEM and WIM passwords will be asked for interactively. - -> Note: Instead of using the common `-u` or `--username` options, we had to use the `--wbem-username` and `--wmi-username` options to specify different credentials for WBEM and WMI. - -### Ouf-of-band Management Card, IPMI-over-LAN - -```batch -$ metricshub MGMT06 -t oob --ipmi -u USER -``` - -This command will connect to the `MGMT06` out-of-band `management` card (typically a BMC chip) using the `IPMI`-over-LAN protocol as `USER`. - -### Solaris, SSH - -```batch -$ metricshub SOLAR08 -t sol --ssh -u USER --sudo-command-list /usr/sbin/dladm,/usr/sbin/ndd -``` - -This command will connect to the `SOLAR08` `Solaris` system using the `SSH` protocol (port 22 by default) to execute commands as `USER`. `sudo` will be used to execute the `/usr/sbin/dladm` and `/usr/sbin/ndd` commands, as they require root privileges. - -> Note: The system must have been configured to allow `USER` to execute these commands with `sudo`. - -### WinRM - -```batch -$ metricshub WIN09 -t mgmt --winrm --winrm-username USER --winrm-password MYSECRET -``` - -This command will connect to the `WIN09` system using the `WinRM` protocol to execute commands as `USER`. - -## Automatic Detection vs Manual Selection - -**MetricsHub** is bundled with **Community Connector Library**, a library which consists of a list of *connectors* that describe how to discover resource components (such as hardware, service and application components) and detect failures in a given system, with a specific instrumentation stack. - -Examples of connectors: - -* Dell OpenManage Server Administrator (SNMP) -* Network Cards on Windows (WMI) -* IBM AIX physical disks, using system commands -* etc. - -When running the `metricshub` command, the connectors are automatically selected based on the specified system type and the protocol enabled. This is the detection phase. - -You can however specify manually which connectors must be used to monitor the specified host, or exclude some connectors from the list that will be tested during the detection phase. - -### Configure connectors - -The connectors are automatically selected based on the device type provided and the enabled protocols. However, you have the flexibility to specify which connectors should be utilized or omitted. - -The `--connectors` CLI option allows you to force, select, or exclude specific connectors. Connector identifiers or category tags should be separated by commas, as illustrated in the example below: - -```batch -$ metricshub SERVER01 -t oob --snmp v2c --community public --connectors +MIB2,#hardware,!Windows -``` - -- To force a connector, precede the connector identifier with a plus sign (`+`), as in `+MIB2`. -- To exclude a connector from automatic detection, precede the connector identifier with an exclamation mark (`!`), like `!Windows`. -- To stage a connector for processing by automatic detection, configure the connector identifier, for instance, `MIB2`. -- To stage a category of connectors for processing by automatic detection, precede the category tag with a hash (`#`), such as `#hardware` or `#system`. -- To exclude a category of connectors from automatic detection, precede the category tag to be excluded with an exclamation mark and a hash sign (`!#`), such as `!#system`. - -#### Examples - -- Example 1: - ```batch - $ metricshub SERVER01 -t win --snmp v2c --community public --connectors "#hardware" - ``` - The core engine will automatically detect connectors categorized under `hardware`. - -- Example 2: - ```batch - $ metricshub SERVER01 -t win --wmi --connectors !#hardware,#system - ``` - The core engine will perform automatic detection on connectors categorized under `system`, excluding those categorized under `hardware`. - -- Example 3: - ```batch - $ metricshub SERVER01 -t win --snmp v2c --community public --wmi --connectors MIB2NT,MIB2,#system - ``` - The core engine will automatically detect connectors named `MIB2NT`, `MIB2`, and all connectors under the `system` category. - -- Example 4: - ```batch - $ metricshub SERVER01 -t win --snmp v2c --community public --wmi --connectors +DiskPart,MIB2,#system - ``` - The core engine will force the execution of the `DiskPart` connector and then proceed with the automatic detection of `MIB2` and all connectors under the `system` category. - -- Example 5: - ```batch - $ metricshub SERVER01 -t win --wmi --connectors DiskPart,!#system - ``` - The core engine will perform automatic detection exclusively on the `DiskPart` connector. - -- Example 6: - ```batch - $ metricshub SERVER01 -t win --snmp v2c --community public --connectors +Windows,MIB2 - ``` - The core engine will force the execution of the `Windows` connector and subsequently perform automatic detection on the `MIB2` connector. - -- Example 7: - ```batch - metricshub SERVER01 -t win --snmp v2c --community public --connectors !Linux - ``` - The core engine will perform automatic detection on all connectors except the `Linux` connector. - -- Example 8: - ```batch - metricshub SERVER01 -t win --snmp v2c --community public --connectors "#hardware,!MIB2" - ``` - The core engine will perform automatic detection on connectors categorized under `hardware`, excluding the `MIB2` connector. - - -To get the list of connectors bundled in **MetricsHub** and their corresponding internal name (**id**), you can run the below command: - -```batch -$ metricshub --list -``` - -This will provide a list as below: - -![Output of the metricshub --list command, listing all connectors, their ID, categories, applicable system types and display name](../images/metricshub-list.png) - -This list displays the internal name (**id**) of each connector, its applicable system types and its display name. - -### Patch Connectors - -By default, **MetricsHub** loads connectors from the `connectors` subdirectory within its installation directory. However, you can extend this functionality by configuring a custom directory for additional connectors. This can be done by specifying the `--patch-directory` option as bellow: - -```batch -$ metricshub SERVER01 -t linux --snmp v2c --community public --patch-directory /opt/patch/connectors -``` - -## Sequential Mode - -By default, the *MetricsHub Engine* sends the queries simultaneously to the host resource. Although the parallel transmission is faster than the sequential one, too many requests at the same time can lead to the failure of the targeted host resource. - -Use the `--sequential` option to force all the requests to be executed in a sequential order, thus the monitored host is not overloaded. - -```batch -$ metricshub SERVER01 -t linux --snmp 1 --community COMM02 --sequential -``` - -## Iterations - -You can run the collect operation many times (e.g: to compute energy or rate metrics, you need to run it at least twice). - -Use `--iterations` option to define the number of times the collect operation will be executed and `--sleep-iteration` to define the -duration in seconds of the pause between two collect operations. - -```batch -$ metricshub SERVER01 -t oob --snmp v2c --community public --iterations 2 --sleep-iteration 5 -``` -## Filtering Monitor Types - -Use the `--monitors` option to filter the monitor types according to the specified inclusion or exclusion criteria. - -> **Note:** If both inclusion and exclusion are configured, the inclusion (`+`) has priority over exclusion (`!`). - -### Example 1: Display Only a Set of Monitor Types - -To display only specific monitor types, use the `--monitors` option with a `+` sign before each monitor type you want to include. For example, to display only memory and file system monitors: - -```batch -$ metricshub STOR02 -t storage --snmpv3 --snmpv3-auth SHA --snmpv3-username USERA --snmpv3-password MySECRET --snmpv3-privacy DES --snmpv3-retryIntervals 5,10,15 --snmpv3-privacy-password MyPrivacySECRET --monitors +memory,+file_system -``` - -### Example 2: Exclude a Set of Monitor Types - -To exclude specific monitor types, use the `--monitors` option with a `!` sign before each monitor type you want to exclude. For example, to exclude CPU and disk monitors: - -```batch -$ metricshub STOR02 -t storage --snmpv3 --snmpv3-auth SHA --snmpv3-username USERA --snmpv3-password MySECRET --snmpv3-privacy DES --snmpv3-retryIntervals 5,10,15 --snmpv3-privacy-password MyPrivacySECRET --monitors !cpu,!disk -``` - +keywords: cli +description: The MetricsHub CLI is the core MetricsHub's engine wrapped in a command line interface. System administrators can easily invoke this tool in a shell to discover and report problems related to the specified resources, including hardware, systems, applications, services, etc. + +# MetricsHub CLI (`metricshub`) + + + +## Overview + +The `metricshub` CLI is the core **MetricsHub**'s engine wrapped in a command line interface. System administrators can easily invoke this tool in a shell to discover and report problems related to the specified resources, including hardware, systems, applications, services, etc. + +The detailed list of systems supported by the **MetricsHub** community (manufacturer and product family and the required instrumentation stack) is listed in [Connectors Directory](../metricshub-connectors-directory.html). + +The quantity and quality of the information that **MetricsHub** will gather depends on the instrumentation stack available on the targeted resource (host). + +![Output example for an Hitachi system](../images/metricshub-hitachi.png) + +Only a few options are required to run the `metricshub` command: + +* Hostname or IP address of the device to be monitored +* Device type +* Protocols to be used: + * HTTP + * IPMI-over-LAN + * SSH + * SNMP + * SNMPV3 + * WBEM + * WMI (on Windows only) +* Credentials + +![Usage of MetricsHub](../images/metricshub-usage.png) + +The `metricshub` command can be used to troubleshoot the monitoring performed by the **MetricsHub Agent** (the core engine). + +## The Basics + +The `metricshub` command invokes the *MetricsHub Engine* against one resource and performs 3 tasks: + +1. Detection of the instrumentation stack on the targeted resource (host) +2. Discovery of the resource's components +3. Collection of metrics and status for each resource's component + +The `metricshub` command requires a few parameters to run: + +* the hostname to connect to +* the type of the resource (Windows, Linux, Management, Storage, Network, AIX, HP-UX, Solaris) +* the protocols to use to gather information from the resource (HTTP, IPMI, SNMP, SNMPV3, SSH, WBEM or WMI) +* the credentials + +Example: + +```batch +$ metricshub server01 -t win --snmp 1 --community secret +``` + +The above command will connect to `server01` (a `Win`dows system), and will detect which instrumentation stack responds to `SNMP` version `1` with the `secret` community. + +Assuming **server01** is an *Hitachi* server, the `metricshub` output will look like: + +![Monitoring the server01 Windows system with SNMP](../images/metricshub-hitachi.png) + +To learn more about the various options available, simply run the below command: + +```batch +$ metricshub -h +``` + +### Verbose Modes + +To get additional details about the operations performed by the *MetricsHub Engine*, run: + +* `-v` to display internal warning messages (**WARN**) +* `-vv` to get details about each operation performed (**INFO**) +* `-vvv` to get initialization and connections details (**DEBUG**) +* `-vvvv` to get full visibility about what is happening (**TRACE**) + +## Examples + +### Storage System, REST API + +```batch +$ metricshub STOR01 -t storage --https -u USER +``` + +This command will connect to the `STOR01` `storage` system in `HTTPS` (port 443 by default) and check whether a known REST API responds with the `USER` credentials. The password will be asked for interactively. Use the `-p P4SSW0RD` option to specify the password directly in the command line (**not secure!**). + +### Linux, SNMP v1 + +```batch +$ metricshub HOST02 -t linux --snmp 1 --community COMM02 +``` + +This command will connect to the `HOST02` `Linux` system using `SNMP` version `1` and the `COMM02` community. If a known SNMP agent is running on this host, `metricshub` will leverage it to discover the physical components of the system and collect various metrics. + +> Note: If no SNMP community is specified, **public** is assumed by default. + +### Storage System, SNMP v2c + +```batch +$ metricshub CISC03 -t sto --snmp 2 +``` + +This command will connect to the `CISC03` SAN switch (`sto`rage) using `SNMP` version `2`. + +> Note: SAN switches fall into the **Storage** category of systems, like disk arrays and tape libraries, and not in the ~~Network~~ category, like network switches and IP routers. + +### Storage System, SNMP v3 + +```batch +$ metricshub STOR02 -t storage --snmpv3 --snmpv3-auth SHA --snmpv3-username USERA --snmpv3-password MySECRET --snmpv3-privacy DES --snmpv3-retryIntervals 5,10,15 --snmpv3-privacy-password MyPrivacySECRET +``` + +This command will connect to the `STOR02` storage system (`storage`) using `SNMP` version `3`. + +### Windows, WMI and SNMP v2c + +```batch +C:\Program Files\MetricsHub> metricshub WIN04 -t win --snmp 2 --wmi +``` + +This command will connect to the `WIN04` `Win`dows system using `SNMP` version `2` with the **public** (default) community, and `WMI` as the current. + +> Note: The WMI protocol can only be used from a Windows system to monitor another Windows system. + +### Windows, WMI and WBEM (Alternate Credentials) + +```batch +C:\Program Files\MetricsHub> metricshub WIN05 -t win --wbem --wbem-username USERA --wmi --wmi-username WINUSER +``` + +This command will connect to the `WIN05` `Win`dows system using `WBEM` as `USERA`, and `WMI` as `WINUSER`. The WBEM and WIM passwords will be asked for interactively. + +> Note: Instead of using the common `-u` or `--username` options, we had to use the `--wbem-username` and `--wmi-username` options to specify different credentials for WBEM and WMI. + +### Ouf-of-band Management Card, IPMI-over-LAN + +```batch +$ metricshub MGMT06 -t oob --ipmi -u USER +``` + +This command will connect to the `MGMT06` out-of-band `management` card (typically a BMC chip) using the `IPMI`-over-LAN protocol as `USER`. + +### Solaris, SSH + +```batch +$ metricshub SOLAR08 -t sol --ssh -u USER --sudo-command-list /usr/sbin/dladm,/usr/sbin/ndd +``` + +This command will connect to the `SOLAR08` `Solaris` system using the `SSH` protocol (port 22 by default) to execute commands as `USER`. `sudo` will be used to execute the `/usr/sbin/dladm` and `/usr/sbin/ndd` commands, as they require root privileges. + +> Note: The system must have been configured to allow `USER` to execute these commands with `sudo`. + +### WinRM + +```batch +$ metricshub WIN09 -t mgmt --winrm --winrm-username USER --winrm-password MYSECRET +``` + +This command will connect to the `WIN09` system using the `WinRM` protocol to execute commands as `USER`. + +## Automatic Detection vs Manual Selection + +**MetricsHub** is bundled with **Community Connector Library**, a library which consists of a list of *connectors* that describe how to discover resource components (such as hardware, service and application components) and detect failures in a given system, with a specific instrumentation stack. + +Examples of connectors: + +* Dell OpenManage Server Administrator (SNMP) +* Network Cards on Windows (WMI) +* IBM AIX physical disks, using system commands +* etc. + +When running the `metricshub` command, the connectors are automatically selected based on the specified system type and the protocol enabled. This is the detection phase. + +You can however specify manually which connectors must be used to monitor the specified host, or exclude some connectors from the list that will be tested during the detection phase. + +### Configure connectors + +The connectors are automatically selected based on the device type provided and the enabled protocols. However, you have the flexibility to specify which connectors should be utilized or omitted. + +The `--connectors` CLI option allows you to force, select, or exclude specific connectors. Connector identifiers or category tags should be separated by commas, as illustrated in the example below: + +```batch +$ metricshub SERVER01 -t oob --snmp v2c --community public --connectors +MIB2,#hardware,!Windows +``` + +- To force a connector, precede the connector identifier with a plus sign (`+`), as in `+MIB2`. +- To exclude a connector from automatic detection, precede the connector identifier with an exclamation mark (`!`), like `!Windows`. +- To stage a connector for processing by automatic detection, configure the connector identifier, for instance, `MIB2`. +- To stage a category of connectors for processing by automatic detection, precede the category tag with a hash (`#`), such as `#hardware` or `#system`. +- To exclude a category of connectors from automatic detection, precede the category tag to be excluded with an exclamation mark and a hash sign (`!#`), such as `!#system`. + +#### Examples + +- Example 1: + ```batch + $ metricshub SERVER01 -t win --snmp v2c --community public --connectors "#hardware" + ``` + The core engine will automatically detect connectors categorized under `hardware`. + +- Example 2: + ```batch + $ metricshub SERVER01 -t win --wmi --connectors !#hardware,#system + ``` + The core engine will perform automatic detection on connectors categorized under `system`, excluding those categorized under `hardware`. + +- Example 3: + ```batch + $ metricshub SERVER01 -t win --snmp v2c --community public --wmi --connectors MIB2NT,MIB2,#system + ``` + The core engine will automatically detect connectors named `MIB2NT`, `MIB2`, and all connectors under the `system` category. + +- Example 4: + ```batch + $ metricshub SERVER01 -t win --snmp v2c --community public --wmi --connectors +DiskPart,MIB2,#system + ``` + The core engine will force the execution of the `DiskPart` connector and then proceed with the automatic detection of `MIB2` and all connectors under the `system` category. + +- Example 5: + ```batch + $ metricshub SERVER01 -t win --wmi --connectors DiskPart,!#system + ``` + The core engine will perform automatic detection exclusively on the `DiskPart` connector. + +- Example 6: + ```batch + $ metricshub SERVER01 -t win --snmp v2c --community public --connectors +Windows,MIB2 + ``` + The core engine will force the execution of the `Windows` connector and subsequently perform automatic detection on the `MIB2` connector. + +- Example 7: + ```batch + metricshub SERVER01 -t win --snmp v2c --community public --connectors !Linux + ``` + The core engine will perform automatic detection on all connectors except the `Linux` connector. + +- Example 8: + ```batch + metricshub SERVER01 -t win --snmp v2c --community public --connectors "#hardware,!MIB2" + ``` + The core engine will perform automatic detection on connectors categorized under `hardware`, excluding the `MIB2` connector. + + +To get the list of connectors bundled in **MetricsHub** and their corresponding internal name (**id**), you can run the below command: + +```batch +$ metricshub --list +``` + +This will provide a list as below: + +![Output of the metricshub --list command, listing all connectors, their ID, categories, applicable system types and display name](../images/metricshub-list.png) + +This list displays the internal name (**id**) of each connector, its applicable system types and its display name. + +### Patch Connectors + +By default, **MetricsHub** loads connectors from the `connectors` subdirectory within its installation directory. However, you can extend this functionality by configuring a custom directory for additional connectors. This can be done by specifying the `--patch-directory` option as bellow: + +```batch +$ metricshub SERVER01 -t linux --snmp v2c --community public --patch-directory /opt/patch/connectors +``` + +## Sequential Mode + +By default, the *MetricsHub Engine* sends the queries simultaneously to the host resource. Although the parallel transmission is faster than the sequential one, too many requests at the same time can lead to the failure of the targeted host resource. + +Use the `--sequential` option to force all the requests to be executed in a sequential order, thus the monitored host is not overloaded. + +```batch +$ metricshub SERVER01 -t linux --snmp 1 --community COMM02 --sequential +``` + +## Iterations + +You can run the collect operation many times (e.g: to compute energy or rate metrics, you need to run it at least twice). + +Use `--iterations` option to define the number of times the collect operation will be executed and `--sleep-iteration` to define the +duration in seconds of the pause between two collect operations. + +```batch +$ metricshub SERVER01 -t oob --snmp v2c --community public --iterations 2 --sleep-iteration 5 +``` +## Filtering Monitor Types + +Use the `--monitors` option to filter the monitor types according to the specified inclusion or exclusion criteria. + +> **Note:** If both inclusion and exclusion are configured, the inclusion (`+`) has priority over exclusion (`!`). + +### Example 1: Display Only a Set of Monitor Types + +To display only specific monitor types, use the `--monitors` option with a `+` sign before each monitor type you want to include. For example, to display only memory and file system monitors: + +```batch +$ metricshub STOR02 -t storage --snmpv3 --snmpv3-auth SHA --snmpv3-username USERA --snmpv3-password MySECRET --snmpv3-privacy DES --snmpv3-retryIntervals 5,10,15 --snmpv3-privacy-password MyPrivacySECRET --monitors +memory,+file_system +``` + +### Example 2: Exclude a Set of Monitor Types + +To exclude specific monitor types, use the `--monitors` option with a `!` sign before each monitor type you want to exclude. For example, to exclude CPU and disk monitors: + +```batch +$ metricshub STOR02 -t storage --snmpv3 --snmpv3-auth SHA --snmpv3-username USERA --snmpv3-password MySECRET --snmpv3-privacy DES --snmpv3-retryIntervals 5,10,15 --snmpv3-privacy-password MyPrivacySECRET --monitors !cpu,!disk +``` + diff --git a/metricshub-doc/src/site/markdown/sustainability/configure-sustainability-metrics.md b/metricshub-doc/src/site/markdown/guides/configure-sustainability-metrics.md similarity index 100% rename from metricshub-doc/src/site/markdown/sustainability/configure-sustainability-metrics.md rename to metricshub-doc/src/site/markdown/guides/configure-sustainability-metrics.md diff --git a/metricshub-doc/src/site/markdown/troubleshooting/debug.md b/metricshub-doc/src/site/markdown/guides/debug.md similarity index 97% rename from metricshub-doc/src/site/markdown/troubleshooting/debug.md rename to metricshub-doc/src/site/markdown/guides/debug.md index ea46f736c..43238cf58 100644 --- a/metricshub-doc/src/site/markdown/troubleshooting/debug.md +++ b/metricshub-doc/src/site/markdown/guides/debug.md @@ -1,56 +1,56 @@ -keywords: debug -description: How to enable the debug mode of the MetricsHub Agent (core engine). - -# Debugging - - - -The **MetricsHub Agent** automatically sets its internal logging system to `error` to capture and record any error that may arise during operation. Important errors are therefore readily available in the `metricshub-agent-*-$timestamp.log` files. - -If you need more comprehensive details to troubleshoot your issues, you can enable the debug mode to obtain these logs: - -* `metricshub-agent-global-error-$timestamp.log`: this file logs all fatal errors such as an application crash upon start-up -* `metricshub-agent-global-$timestamp.log`: this file provides the agent global information (agent status, user, version, scheduler, yaml parser, etc.) -* `metricshub-agent-$resourceId-$timestamp.log`: this file logs information about the monitored resource. - -## Enabling the debug mode - -In the **config/metricshub.yaml** file, add the `loggerLevel` parameter just before the `resourceGroups` section: - -```yaml -loggerLevel: debug - -resourceGroups: - : - resources: - # [...] -``` - -Set the `loggerLevel` parameter to: - -* `all`, `trace`, or `debug` to get more comprehensive details -* `error` or `fatal` to focus on identifying critical issues. - -The debug output files are saved by default in the **logs** directory located under the **MetricsHub** directory: - -* On Windows, the output files are stored in the **%LOCALAPPDATA%\MetricsHub** folder of the account running the application: - * When the Local System account starts the MetricsHub Agent service, the output files are stored under **C:\Windows\System32\config\systemprofile\AppData\Local\MetricsHub\logs**. - * When a specific user starts the MetricsHub Agent service, the output files are stored under **C:\Users\\\AppData\Local\MetricsHub\logs**. - -* On Linux, the output files are stored in the installation directory: **/opt/metricshub/logs**. - -To specify a different output directory, edit the **metricshub.yaml** file and add the `outputDirectory` parameter before the `resourceGroups` section: - -```yaml -loggerLevel: debug -outputDirectory: C:\Users\\AppData\Local\Temp\logs2021 - -resourceGroups: - : - resources: - # [...] -``` - -## Disabling the debug mode - +keywords: debug +description: How to enable the debug mode of the MetricsHub Agent (core engine). + +# Debugging + + + +The **MetricsHub Agent** automatically sets its internal logging system to `error` to capture and record any error that may arise during operation. Important errors are therefore readily available in the `metricshub-agent-*-$timestamp.log` files. + +If you need more comprehensive details to troubleshoot your issues, you can enable the debug mode to obtain these logs: + +* `metricshub-agent-global-error-$timestamp.log`: this file logs all fatal errors such as an application crash upon start-up +* `metricshub-agent-global-$timestamp.log`: this file provides the agent global information (agent status, user, version, scheduler, yaml parser, etc.) +* `metricshub-agent-$resourceId-$timestamp.log`: this file logs information about the monitored resource. + +## Enabling the debug mode + +In the **config/metricshub.yaml** file, add the `loggerLevel` parameter just before the `resourceGroups` section: + +```yaml +loggerLevel: debug + +resourceGroups: + : + resources: + # [...] +``` + +Set the `loggerLevel` parameter to: + +* `all`, `trace`, or `debug` to get more comprehensive details +* `error` or `fatal` to focus on identifying critical issues. + +The debug output files are saved by default in the **logs** directory located under the **MetricsHub** directory: + +* On Windows, the output files are stored in the **%LOCALAPPDATA%\MetricsHub** folder of the account running the application: + * When the Local System account starts the MetricsHub Agent service, the output files are stored under **C:\Windows\System32\config\systemprofile\AppData\Local\MetricsHub\logs**. + * When a specific user starts the MetricsHub Agent service, the output files are stored under **C:\Users\\\AppData\Local\MetricsHub\logs**. + +* On Linux, the output files are stored in the installation directory: **/opt/metricshub/logs**. + +To specify a different output directory, edit the **metricshub.yaml** file and add the `outputDirectory` parameter before the `resourceGroups` section: + +```yaml +loggerLevel: debug +outputDirectory: C:\Users\\AppData\Local\Temp\logs2021 + +resourceGroups: + : + resources: + # [...] +``` + +## Disabling the debug mode + Set `loggerlevel` to `off` to disable the debug mode. \ No newline at end of file diff --git a/metricshub-doc/src/site/markdown/quick-start-community-prometheus-linux.md b/metricshub-doc/src/site/markdown/guides/quick-start-community-prometheus-linux.md similarity index 94% rename from metricshub-doc/src/site/markdown/quick-start-community-prometheus-linux.md rename to metricshub-doc/src/site/markdown/guides/quick-start-community-prometheus-linux.md index 781081807..ae1964f3d 100644 --- a/metricshub-doc/src/site/markdown/quick-start-community-prometheus-linux.md +++ b/metricshub-doc/src/site/markdown/guides/quick-start-community-prometheus-linux.md @@ -1,168 +1,168 @@ -keywords: quick start, getting started -description: Short step-by-step instructions to follow for installing and configuring MetricsHub in a Linux environment. - -# Quick Start - Linux - - - -This quick start guide provides step-by-step instructions for operating MetricsHub and Prometheus in a Linux 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 package `metricshub-linux-${communityVersion}.tar.gz` using `wget` and save it under `/tmp`: - - ```shell - sudo wget -O /tmp/metricshub-linux-${communityVersion}.tar.gz https://github.com/sentrysoftware/metricshub/releases/download/v${communityVersion}/metricshub-linux-${communityVersion}.tar.gz - ``` - -2. Run the below command to unzip `/tmp/metricshub-linux-${communityVersion}.tar.gz` under `/opt`: - - ```shell - sudo tar -xzvf /tmp/metricshub-linux-${communityVersion}.tar.gz -C /opt/ - ``` - -There is no need to create a specific subdirectory for `metricshub` as the archive already contains a `metricshub` directory. - -## Step 2: Install Prometheus - -1. Run the below command to download Prometheus: - - ```shell - sudo wget -O /tmp/prometheus-{version}.linux-{architecture}.tar.gz https://github.com/prometheus/prometheus/releases/download/v{version}/prometheus-{version}.linux-{architecture}.tar.gz - ``` - - where `{version}` and `{architecture}` should be replaced by the prometheus version and processor architecture. - -2. Run the below command to extract the package into `/opt/prometheus`: - - ```shell - sudo mkdir -p /opt/prometheus && sudo tar -xzvf /tmp/prometheus-{version}.linux-{architecture}.tar.gz -C /opt/prometheus --strip-components=1 - ``` - -> Note: Make sure to use the corresponding Prometheus version and CPU architecture for `{version}` and `{architecture}`. For example, `prometheus-2.52.0.linux-amd64` for version `2.52.0` and `amd64` architecture. Refer to the [Prometheus download site](https://prometheus.io/download/) to find the right Prometheus package. - -## Step 3: Configure the MetricsHub Agent - -### Create your configuration file - -Run the below command to create your configuration file: - - ```shell - sudo cp /opt/metricshub/lib/config/metricshub-example.yaml /opt/metricshub/lib/config/metricshub.yaml - ``` - -### Configure localhost monitoring - -The `metricshub-example.yaml` file you copied already contains the necessary configuration to monitor your localhost through OS Command. The relevant section should look like this: - -```yaml -resources: - localhost: - attributes: - host.name: localhost - host.type: linux - protocols: - osCommand: - timeout: 120 -``` - -Open the `/opt/metricshub/lib/config/metricshub.yaml` file and search for the above section to verify that this configuration is active. - -If you wish to use a protocol other than `osCommand` (such as `HTTP`, `PING`, `SNMP`, `SSH`, `IPMI`, `WBEM` or `WinRM`), refer to the configuration examples provided in `/opt/metricshub/lib/config/metricshub.yaml`. - -### Configure Prometheus to receive MetricsHub data - -Add the below configuration under the `otel` section to push metrics to Prometheus: - -```yaml -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 - -1. Run the below command to access the directory where Prometheus is installed: - - ```shell - cd "/opt/prometheus" - ``` - -1. Run the below command to start Prometheus: - ```shell - 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 - ``` - -4. Type [localhost:9090](http://localhost:9090) in your Web browser. - -### Start the Metricshub Agent - -Run the below command to start the **MetricsHub Agent**: - -```shell -cd /opt/metricsHub/bin -sudo ./service -``` - -## Step 5: Perform Last Checks - -### Verify that metrics are sent to Prometheus - -In [Prometheus](http://localhost:9090), search for any metrics starting with `metricshub_` or `hw_` to confirm that data is actually received. - -### Check Logs - -Several logs are created as soon as the **MetricsHub Agent** is started: - -* a global `MetricsHub` log file -* one log file per configured host. - -They are stored in `makefile /opt/metricshub/lib/logs`. - -You can configure the log level in the `/opt/metricsHub/lib/config/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. - -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:linux - ``` - -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: - - ```css - [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](../configuration/configure-agent.html#configure-the-otlp-receiver) in the `metricshub.yaml` configuration file. +keywords: quick start, getting started +description: Short step-by-step instructions to follow for installing and configuring MetricsHub in a Linux environment. + +# Quick Start - Linux + + + +This quick start guide provides step-by-step instructions for operating MetricsHub and Prometheus in a Linux 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 package `metricshub-linux-${communityVersion}.tar.gz` using `wget` and save it under `/tmp`: + + ```shell + sudo wget -O /tmp/metricshub-linux-${communityVersion}.tar.gz https://github.com/sentrysoftware/metricshub/releases/download/v${communityVersion}/metricshub-linux-${communityVersion}.tar.gz + ``` + +2. Run the below command to unzip `/tmp/metricshub-linux-${communityVersion}.tar.gz` under `/opt`: + + ```shell + sudo tar -xzvf /tmp/metricshub-linux-${communityVersion}.tar.gz -C /opt/ + ``` + +There is no need to create a specific subdirectory for `metricshub` as the archive already contains a `metricshub` directory. + +## Step 2: Install Prometheus + +1. Run the below command to download Prometheus: + + ```shell + sudo wget -O /tmp/prometheus-{version}.linux-{architecture}.tar.gz https://github.com/prometheus/prometheus/releases/download/v{version}/prometheus-{version}.linux-{architecture}.tar.gz + ``` + + where `{version}` and `{architecture}` should be replaced by the prometheus version and processor architecture. + +2. Run the below command to extract the package into `/opt/prometheus`: + + ```shell + sudo mkdir -p /opt/prometheus && sudo tar -xzvf /tmp/prometheus-{version}.linux-{architecture}.tar.gz -C /opt/prometheus --strip-components=1 + ``` + +> Note: Make sure to use the corresponding Prometheus version and CPU architecture for `{version}` and `{architecture}`. For example, `prometheus-2.52.0.linux-amd64` for version `2.52.0` and `amd64` architecture. Refer to the [Prometheus download site](https://prometheus.io/download/) to find the right Prometheus package. + +## Step 3: Configure the MetricsHub Agent + +### Create your configuration file + +Run the below command to create your configuration file: + + ```shell + sudo cp /opt/metricshub/lib/config/metricshub-example.yaml /opt/metricshub/lib/config/metricshub.yaml + ``` + +### Configure localhost monitoring + +The `metricshub-example.yaml` file you copied already contains the necessary configuration to monitor your localhost through OS Command. The relevant section should look like this: + +```yaml +resources: + localhost: + attributes: + host.name: localhost + host.type: linux + protocols: + osCommand: + timeout: 120 +``` + +Open the `/opt/metricshub/lib/config/metricshub.yaml` file and search for the above section to verify that this configuration is active. + +If you wish to use a protocol other than `osCommand` (such as `HTTP`, `PING`, `SNMP`, `SSH`, `IPMI`, `WBEM` or `WinRM`), refer to the configuration examples provided in `/opt/metricshub/lib/config/metricshub.yaml`. + +### Configure Metrics Exporter + +Add the below configuration under the `otel` section to push metrics to Prometheus: + +```yaml +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 + +1. Run the below command to access the directory where Prometheus is installed: + + ```shell + cd "/opt/prometheus" + ``` + +1. Run the below command to start Prometheus: + ```shell + 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 + ``` + +4. Type [localhost:9090](http://localhost:9090) in your Web browser. + +### Start the MetricsHub Agent + +Run the below command to start the **MetricsHub Agent**: + +```shell +cd /opt/metricsHub/bin +sudo ./service +``` + +## Step 5: Perform Last Checks + +### Verify that metrics are sent to Prometheus + +In [Prometheus](http://localhost:9090), search for any metrics starting with `metricshub_` or `hw_` to confirm that data is actually received. + +### Check Logs + +Several logs are created as soon as the **MetricsHub Agent** is started: + +* a global `MetricsHub` log file +* one log file per configured host. + +They are stored in `makefile /opt/metricshub/lib/logs`. + +You can configure the log level in the `/opt/metricsHub/lib/config/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. + +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:linux + ``` + +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: + + ```css + [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](#configure-metrics-exporter) in the `metricshub.yaml` configuration file. diff --git a/metricshub-doc/src/site/markdown/quick-start-community-prometheus-windows.md b/metricshub-doc/src/site/markdown/guides/quick-start-community-prometheus-windows.md similarity index 94% rename from metricshub-doc/src/site/markdown/quick-start-community-prometheus-windows.md rename to metricshub-doc/src/site/markdown/guides/quick-start-community-prometheus-windows.md index 908c2f9d7..e3fd95aa3 100644 --- a/metricshub-doc/src/site/markdown/quick-start-community-prometheus-windows.md +++ b/metricshub-doc/src/site/markdown/guides/quick-start-community-prometheus-windows.md @@ -1,156 +1,156 @@ -keywords: quick start, getting started -description: Short step-by-step instructions to follow for installing and configuring MetricsHub in a Windows environment. - -# 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 - -1. Download the latest package, `metricshub-windows-${communityVersion}.zip`, from the [MetricsHub Releases](https://github.com/sentrysoftware/metricshub/releases/) page - -2. Right-click on the archive, select **Extract All...**, enter `C:\Program Files\`, and click **Extract**. This will place the `MetricsHub` directory in `C:\Program Files\`. - -> Note: You will need administrative privileges to unzip into `C:\Program Files`. - -## Step 2: Install Prometheus - -1. Download [prometheus-{version}.windows-{architecture}.zip](https://prometheus.io/download/) - -2. Right-click the archive, select **Extract All...**", enter `C:\Program Files\`, and click **Extract**. This will place the `prometheus-{version}.windows-{architecture}` directory in `C:\Program Files\` - -3. Under `C:\Program Files\`, rename the `prometheus-{version}.windows-{architecture}` directory to `Prometheus`. - -> 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 version `2.52.0` and `amd64` architecture. - -## Step 3: Configure the MetricsHub Agent - -### Create your configuration file - -1. 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: - - ```shell - mkdir C:\ProgramData\MetricsHub - mkdir C:\ProgramData\MetricsHub\config - ``` - -2. Copy the configuration example `metricshub-example.yaml` available in `C:\Program Files\MetricsHub\config\`, paste it into `C:\ProgramData\MetricsHub\config\` and rename the file to `metricshub.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: - -```yaml -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 Prometheus to receive MetricsHub data - -In the same configuration file (`C:\ProgramData\MetricsHub\config\metricshub.yaml`), add the below configuration under the `otel` section to push metrics to Prometheus: - -```yaml -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 - -1. Run the below command **as administrator** to access the directory where Prometheus is installed: - - ```shell - cd "C:\Program Files\Prometheus" - ``` - -2. Run the below command to start Prometheus: - - ```shell - 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 - ``` - -3. Type [localhost:9090](http://localhost:9090) in your Web browser. - -### Start the Metricshub Agent - -Run the below command **as administrator** to start the MetricsHub Agent: - -```shell -cd "C:\Program Files\MetricsHub" -MetricsHubServiceManager.exe -``` - -## Step 5: Perform Last Checks - -### Verify that metrics are sent to Prometheus - -In [Prometheus](http://localhost:9090), 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 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. - -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: - - ```css - [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](../configuration/configure-agent.html#configure-the-otlp-receiver) in the `metricshub.yaml` configuration file. +keywords: quick start, getting started +description: Short step-by-step instructions to follow for installing and configuring MetricsHub in a Windows environment. + +# 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 + +1. Download the latest package, `metricshub-windows-${communityVersion}.zip`, from the [MetricsHub Releases](https://github.com/sentrysoftware/metricshub/releases/) page + +2. Right-click on the archive, select **Extract All...**, enter `C:\Program Files\`, and click **Extract**. This will place the `MetricsHub` directory in `C:\Program Files\`. + +> Note: You will need administrative privileges to unzip into `C:\Program Files`. + +## Step 2: Install Prometheus + +1. Download [prometheus-{version}.windows-{architecture}.zip](https://prometheus.io/download/) + +2. Right-click the archive, select **Extract All...**", enter `C:\Program Files\`, and click **Extract**. This will place the `prometheus-{version}.windows-{architecture}` directory in `C:\Program Files\` + +3. Under `C:\Program Files\`, rename the `prometheus-{version}.windows-{architecture}` directory to `Prometheus`. + +> 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 version `2.52.0` and `amd64` architecture. + +## Step 3: Configure the MetricsHub Agent + +### Create your configuration file + +1. 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: + + ```shell + mkdir C:\ProgramData\MetricsHub + mkdir C:\ProgramData\MetricsHub\config + ``` + +2. Copy the configuration example `metricshub-example.yaml` available in `C:\Program Files\MetricsHub\config\`, paste it into `C:\ProgramData\MetricsHub\config\` and rename the file to `metricshub.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: + +```yaml +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: + +```yaml +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 + +1. Run the below command **as administrator** to access the directory where Prometheus is installed: + + ```shell + cd "C:\Program Files\Prometheus" + ``` + +2. Run the below command to start Prometheus: + + ```shell + 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 + ``` + +3. Type [localhost:9090](http://localhost:9090) in your Web browser. + +### Start the MetricsHub Agent + +Run the below command **as administrator** to start the MetricsHub Agent: + +```shell +cd "C:\Program Files\MetricsHub" +MetricsHubServiceManager.exe +``` + +## Step 5: Perform Last Checks + +### Verify that metrics are sent to Prometheus + +In [Prometheus](http://localhost:9090), 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 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. + +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: + + ```css + [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](#configure-metrics-exporter) in the `metricshub.yaml` configuration file. diff --git a/metricshub-doc/src/site/markdown/troubleshooting/status.md b/metricshub-doc/src/site/markdown/guides/status.md similarity index 96% rename from metricshub-doc/src/site/markdown/troubleshooting/status.md rename to metricshub-doc/src/site/markdown/guides/status.md index c9f055beb..58e7e19a3 100644 --- a/metricshub-doc/src/site/markdown/troubleshooting/status.md +++ b/metricshub-doc/src/site/markdown/guides/status.md @@ -83,7 +83,7 @@ otelcol_process_runtime_total_sys_memory_bytes{service_instance_id="xxxxxxxxx-xx The above processor time utilization and memory consumption metrics pertain to the `otelcol-contrib` process only, and do not represent the activity of the internal **MetricsHub Agent**. -You can choose to integrate these internal metrics in the pipeline of the *OpenTelemetry Collector* to push them to the platform of your choice. To do so, [edit the otel/otel-config.yaml configuration file](../configuration/configure-otel.md) to add `prometheus/internal` in the list of receivers: +You can choose to integrate these internal metrics in the pipeline of the *OpenTelemetry Collector* to push them to the platform of your choice. To do so, [edit the otel/otel-config.yaml configuration file](../configuration/send-telemetry.md) to add `prometheus/internal` in the list of receivers: ```yaml # [...] @@ -101,4 +101,4 @@ service: exporters: [...] # List here the platform of your choice ``` -> Additional troubleshooting information is available in the [OpenTelemetry Collector's Troubleshooting Guide](https://github.com/open-telemetry/opentelemetry-collector/blob/main/docs/troubleshooting.md). \ No newline at end of file +> Additional troubleshooting information is available in the [OpenTelemetry Collector's Troubleshooting Guide](https://opentelemetry.io/docs/collector/troubleshooting/). \ No newline at end of file diff --git a/metricshub-doc/src/site/markdown/index.md b/metricshub-doc/src/site/markdown/index.md index b1816a42c..25919516f 100644 --- a/metricshub-doc/src/site/markdown/index.md +++ b/metricshub-doc/src/site/markdown/index.md @@ -13,7 +13,7 @@ description: MetricsHub is a universal metrics collection agent for OpenTelemetr ![](./images/otel-metricshub.png) -**MetricsHub** includes a library of YAML files - called **connectors** - which describe how to collect metrics about [operating systems and a variety of platforms.]((https://metricshub.com/docs/latest/metricshub-connector-reference.html)) +**MetricsHub** includes a library of YAML files - called **connectors** - which describe how to collect metrics about [operating systems and a variety of platforms.](metricshub-connectors-directory.html) **MetricsHub** uses the OTLP protocol to send metrics to observability platforms that support OpenTelemetry natively like Datadog, New Relic, Prometheus, and Splunk. diff --git a/metricshub-doc/src/site/markdown/install/debian-linux.md b/metricshub-doc/src/site/markdown/install/debian-linux.md index 624524ffc..e9939116d 100644 --- a/metricshub-doc/src/site/markdown/install/debian-linux.md +++ b/metricshub-doc/src/site/markdown/install/debian-linux.md @@ -25,7 +25,7 @@ When complete, the **MetricsHub**'s files are deployed in `/opt/metricshub` and ### Configure * In the **./lib/config/metricshub.yaml** file, located under the `/opt/metricshub` installation directory, configure the [resources to be monitored.](../configuration/configure-monitoring.html#configure-resources) -* In the **./lib/otel/otel-config.yaml** file, located under the `/opt/metricshub` installation directory, specify where the _OpenTelemetry Collector_ should [send the collected data.](../configuration/send-data.html#configure-the-otel-collector-28enterprise-edition-29) +* In the **./lib/otel/otel-config.yaml** file, located under the `/opt/metricshub` installation directory, specify where the _OpenTelemetry Collector_ should [send the collected data](../configuration/send-telemetry.html#configure-the-otel-collector-28enterprise-edition-29). To assist with the setup process, two configuration examples are provided for guidance in the installation directory (`./metricshub`): @@ -81,7 +81,7 @@ sudo tar xzf /tmp/metricshub-linux-${communityVersion}.tar.gz In the `./lib/config/metricshub.yaml` file, located under the `./metricshub` installation directory, configure: * the [resources to be monitored.](../configuration/configure-monitoring.html#configure-resources) -* the [OpenTelemetry Protocol endpoint](../configuration/send-data.html#configure-the-otlp-receiver-28community-edition-29) that will receive the MetricsHub signals. +* the [OpenTelemetry Protocol endpoint](../configuration/send-telemetry.html#configure-the-otlp-exporter-28community-edition-29) that will receive the MetricsHub signals. To assist with the setup process, the configuration example `./lib/config/metricshub-example.yaml` is provided for guidance in the installation directory (`./metricshub`). diff --git a/metricshub-doc/src/site/markdown/install/docker.md b/metricshub-doc/src/site/markdown/install/docker.md index 4a537d9a8..77194c94d 100644 --- a/metricshub-doc/src/site/markdown/install/docker.md +++ b/metricshub-doc/src/site/markdown/install/docker.md @@ -29,7 +29,7 @@ sudo docker build -t metricshub:latest . ### Configure * In the **./lib/config/metricshub.yaml** file, located under the `/docker/metricshub` installation directory, configure the [resources to be monitored](../configuration/configure-monitoring.html#configure-resources). -* In the **./lib/otel/otel-config.yaml** file, located under the `/docker/metricshub` installation directory, specify where the _OpenTelemetry Collector_ should [send the collected data](../configuration/send-data.html#configure-the-otel-collector-28enterprise-edition-29). +* In the **./lib/otel/otel-config.yaml** file, located under the `/docker/metricshub` installation directory, specify where the _OpenTelemetry Collector_ should [send the collected data](../configuration/send-telemetry.html#configure-the-otel-collector-28enterprise-edition-29). To assist with the setup process, two configuration examples are provided for guidance in the installation directory (`./metricshub`): @@ -99,7 +99,7 @@ sudo tar xzf /tmp/metricshub-linux-${communityVersion}-docker.tar.gz -C /docker In the `./lib/config/metricshub.yaml` file, locally under the `./metricshub` installation directory, configure: * the [resources to be monitored.](../configuration/configure-monitoring.md#configure-resources) -* the [OpenTelemetry Protocol endpoint](../configuration/send-data.html#configure-the-otlp-receiver-28community-edition-29) that will receive the MetricsHub signals. +* the [OpenTelemetry Protocol endpoint](../configuration/send-telemetry.html#configure-the-otlp-exporter-28community-edition-29) that will receive the MetricsHub signals. To assist with the setup process, the configuration example `./lib/config/metricshub-example.yaml` is provided for guidance in the installation directory (`./metricshub`). diff --git a/metricshub-doc/src/site/markdown/install/redhat-linux.md b/metricshub-doc/src/site/markdown/install/redhat-linux.md index 7dd8a5cb2..065e4e2ca 100644 --- a/metricshub-doc/src/site/markdown/install/redhat-linux.md +++ b/metricshub-doc/src/site/markdown/install/redhat-linux.md @@ -24,7 +24,7 @@ When complete, the **MetricsHub**'s files are deployed in `/opt/metricshub` and ### Configure * In the **./lib/config/metricshub.yaml** file, located under the `/opt/metricshub` installation directory, configure the [resources to be monitored.](../configuration/configure-monitoring.html#configure-resources) -* In the **./lib/otel/otel-config.yaml** file, located under the `/opt/metricshub` installation directory, specify where the _OpenTelemetry Collector_ should [send the collected data.](../configuration/send-data.html#configure-the-otel-collector-28enterprise-edition-29) +* In the **./lib/otel/otel-config.yaml** file, located under the `/opt/metricshub` installation directory, specify where the _OpenTelemetry Collector_ should [send the collected data.](../configuration/send-telemetry.html#configure-the-otel-collector-28enterprise-edition-29) To assist with the setup process, two configuration examples are provided for guidance in the installation directory (`./metricshub`): @@ -93,7 +93,7 @@ sudo tar xzf /tmp/metricshub-linux-${communityVersion}.tar.gz In the `./lib/config/metricshub.yaml` file, located under the `./metricshub` installation directory, configure: * the [resources to be monitored.](../configuration/configure-monitoring.html#configure-resources) -* the [OpenTelemetry Protocol endpoint](../configuration/send-data.html#configure-the-otlp-receiver-28community-edition-29) that will receive the MetricsHub signals. +* the [OpenTelemetry Protocol endpoint](../configuration/send-telemetry.html#configure-the-otlp-exporter-28community-edition-29) that will receive the MetricsHub signals. To assist with the setup process, the configuration example `./lib/config/metricshub-example.yaml` is provided for guidance in the installation directory (`./metricshub`). diff --git a/metricshub-doc/src/site/markdown/install/windows.md b/metricshub-doc/src/site/markdown/install/windows.md index 904f12f76..ec52da7a1 100644 --- a/metricshub-doc/src/site/markdown/install/windows.md +++ b/metricshub-doc/src/site/markdown/install/windows.md @@ -21,7 +21,7 @@ MetricsHub operates using the configuration located in the `ProgramData\MetricsH ### Configure * In the **C:\ProgramData\MetricsHub\config\metricshub.yaml** file, configure the [resources to be monitored.](../configuration/configure-monitoring.html#configure-resources) -* In the **C:\ProgramData\MetricsHub\otel\otel-config.yaml** file, specify where the _OpenTelemetry Collector_ should [send the collected data.](../configuration/send-data.html#configure-the-otel-collector-28enterprise-edition-29) +* In the **C:\ProgramData\MetricsHub\otel\otel-config.yaml** file, specify where the _OpenTelemetry Collector_ should [send the collected data.](../configuration/send-telemetry.html#configure-the-otel-collector-28enterprise-edition-29) To assist with the setup process, two configuration examples are provided for guidance in the installation directory (`C:\Program Files\MetricsHub`): @@ -53,7 +53,7 @@ Unzip the content of `metricshub-windows-${communityVersion}.zip` into a program In the `C:\ProgramData\MetricsHub\config\metricshub.yaml` file, configure: * the [resources to be monitored.](../configuration/configure-monitoring.html#configure-resources) -* the [OpenTelemetry Protocol endpoint](../configuration/send-data.html#configure-the-otlp-receiver-28community-edition-29) that will receive the MetricsHub signals. +* the [OpenTelemetry Protocol endpoint](../configuration/send-telemetry.html#configure-the-otlp-exporter-28community-edition-29) that will receive the MetricsHub signals. To assist with the setup process, the configuration example `.\config\metricshub-example.yaml` is provided for guidance in the installation directory (typically, `C:\Program Files\MetricsHub`). diff --git a/metricshub-doc/src/site/site.xml b/metricshub-doc/src/site/site.xml index 588bc2936..98ae2b274 100644 --- a/metricshub-doc/src/site/site.xml +++ b/metricshub-doc/src/site/site.xml @@ -91,25 +91,19 @@ - - - - - - - - - - - - - + + + + + + +