Stop Writing YAML by Hand: Automate MetricsHub Configuration with Velocity

In this article, I will explain how I used the programmable configuration feature in MetricsHub Enterprise to automatically configure all Linux and Windows systems discovered by BMC Helix Discovery, without touching the YAML configuration file.

What is Velocity?

Before diving into the implementation, I would like to first explain what Apache Velocity is. Apache Velocity is a Java-based templating engine commonly used to dynamically generate configuration files, scripts, or API requests from discovered data.

A Velocity script typically combines:

• Directives (such as #if, #foreach, etc.)
• Variables (prefixed with $)
• Method calls on objects.

MetricsHub leverages Velocity to programmatically configure resource monitoring during startup.

Prerequisites

To connect to BMC Helix Discovery, I first need to create an API Token:

1. In the BMC Helix Console, navigate to Administration > Users
2. Create a user with an API access role
3. Click Actions > Generate API Token

This token will be used by the Velocity script to authenticate REST calls to BMC Helix Discovery.

Note: In our scenario, we stored the token in a system environment variable named HELIX_DISCO_TOKEN.

Writing the Velocity Script

The script below retrieves all discovered Linux and Windows hosts from BMC Helix Discovery and automatically generates the corresponding MetricsHub resource definitions.

1. Specify the API Token

   ## 1. API token for Helix Discovery
   #set($apiToken = $env.get("HELIX_DISCO_TOKEN"))
   

2. Build the Discovery request

   ## 2. Properly encoded query string
   #set($query = $url.encode("SEARCH Host"))
   #set($discoveryUrl = "<DiscoveryURL>")
   
   ## 3. Header string (must be a single string with newline-separated values)
   #set($hdrs = "Authorization: Bearer $apiToken\nContent-Type: application/json\nAccept: application/json")
   
   ## 4. Perform the HTTP GET
   #set($raw = $http.execute({
   "url": $discoveryUrl,
   "method": "GET",
   "headers": $hdrs
   }))
   

3. Parse the JSON response

   ## 6. Parse the JSON body
   #set($jsonDoc = $json.parse($raw.body).root())
   #set($payload = $jsonDoc.get(0))
   #set($devices = $payload.get("results"))
   

4. Create a Resource Group named HelixDiscovery:

   loggerLevel: debug
   outputDirectory: C:\metricshub\logs2025
   
   resourceGroups:
   HelixDisco:
       attributes:
       site: helix-disco-sentry2
       metrics:
       hw.site.carbon_intensity: 230   # g/kWh
       hw.site.electricity_cost: 0.12  # $/kWh
       hw.site.pue: 1.8
   

5. Create Linux and Windows resources dynamically:

   #foreach($d in $devices)
   #set($suf = "_helixdisco")
   #set($hostname = $d.get(0))
   #set($os = $d.get(1))
   
   #if($hostname && $hostname.trim().length() > 0)
       #set($hostname = $hostname.trim())
   
       #if($os.contains("Linux"))
   $hostname$suf:
   attributes:
       host.name: $hostname
       host.type: linux
   connectors: [ +Linux ]
   protocols:
       ssh:
       username: admin
       password: EncryptedPassword
       #end
   
       #if($os.contains("Windows"))
   $hostname$suf:
   attributes:
       host.name: $hostname
       host.type: win
   connectors: [ +Windows ]
   protocols:
       winrm:
       username: admin
       password: EncryptedPassword
       #end
   
   #end
   #end
   

   Note: In this example, the same credentials for all Linux and Windows systems. Passwords were encrypted using the metricshub-encrypt utility.

6. Save the script in the MetricsHub configuration directory:

   • ./metricshub/lib/config for Linux
   • C:\ProgramData\metricshub\config for Windows

7. Restart MetricsHub.

A log file is created in the MetricsHub log directory for each monitored host, confirming that the velocity script successfully generated the required configuration:

Pushing metrics to BMC Helix Operations Management

The metrics collected by MetricsHub are produced in OpenTelemetry format, allowing you to forward them to any observability platform that supports OpenTelemetry. In our scenario, we forward the collected metrics to BMC Helix Operations Management for performance monitoring and event management, without deploying any additional agent, like the BMC PATROL Agent.

Pushing metrics to BMC Helix Operations Management is straightforward and only requires updating the OpenTelemetry configuration file (otel-config.yaml), located at:

• C:\ProgramData\metricshub\otel (Windows)
• /opt/metricshub/otel (Linux)

For detailed instructions, refer to the BMC Helix integration documentation.

Once otel-config.yaml is configured, restart MetricsHub to start visualizing your metrics in BMC Helix Operations Management:

Conclusion

Programmable configuration is a major step toward consistent, reliable monitoring that scales effortlessly with your infrastructure. Why don’t you give it a try?

Automate Your Monitoring Now!

Share this post