Fortinet black logo

User Guide

Custom metrics using the command line

24.1.0
Copy Link
Copy Doc ID af1daa65-c273-11ec-9fd1-fa163e15d75b:106842
Download PDF

Custom metrics using the command line (FortiMonitor Agent)

Custom metrics allow you to report your own metrics straight to the agent with a command-line call. This process is simpler than creating a custom agent plugin and is a great way to add new functionality to our agent.

The way to create a custom metric is is a two-step process. First, you will have to create a custom metric using the registration script below. Your metric key can be any value containing letters, numbers, periods, underscores, or dashes.

Linux

python3 /usr/bin/fm-agent/register.py <metrickey> <description>

If this script is not found in the fm-agent folder, then your version of the Agent is out of date and you should update it to gain access to this feature.

Windows

PS C:\Program Files (x86)\FortiMonitorAgent\bin> .\register.ps1 <metrickey> <description>

If this script is not found in the folder, then your version of the Agent is out of date and you should update it to gain access to this feature.

You will only need to do this once. Then, whenever you would like to report a value, you can use the following command line call:

Linux

python /usr/bin/fm-agent/report.py <metrickey> <value> <timestamp>

Windows

C:\Program Files\FortimonitorAgent\bin> .\report.ps1 <metrickey> <value> <timestamp>

The value must be an integer or a float, and the timestamp is an optional UTC date with ISO format (YYYY-mm-dd HH:mm:SS”). If the timestamp is left off it will default to the current UTC time.

You can make any number of report calls for a given metric key. However, the system will record only the last value submitted in a given minute, and discard any previously submitted metric readings in the same minute.

You can now create you own scripts to reports these metrics automatically or integrate calls to the agent into your own application. Once you have registered your new metric, an agent resource type will be created for this server automatically in the control panel. You can edit this check as you would any other. You can create as many additional custom metrics as you like and they will all show up under the “Custom Metric” category.

If you want to verify that report.py is collecting those metrics, review the generated log entries.

If you have followed the steps above and the new metric and plugin do not show properly, you may need to manually rebuild the agent’s metadata. You can do this by following the guide here.

Custom metrics using the command line (FortiMonitor Agent)

Custom metrics allow you to report your own metrics straight to the agent with a command-line call. This process is simpler than creating a custom agent plugin and is a great way to add new functionality to our agent.

The way to create a custom metric is is a two-step process. First, you will have to create a custom metric using the registration script below. Your metric key can be any value containing letters, numbers, periods, underscores, or dashes.

Linux

python3 /usr/bin/fm-agent/register.py <metrickey> <description>

If this script is not found in the fm-agent folder, then your version of the Agent is out of date and you should update it to gain access to this feature.

Windows

PS C:\Program Files (x86)\FortiMonitorAgent\bin> .\register.ps1 <metrickey> <description>

If this script is not found in the folder, then your version of the Agent is out of date and you should update it to gain access to this feature.

You will only need to do this once. Then, whenever you would like to report a value, you can use the following command line call:

Linux

python /usr/bin/fm-agent/report.py <metrickey> <value> <timestamp>

Windows

C:\Program Files\FortimonitorAgent\bin> .\report.ps1 <metrickey> <value> <timestamp>

The value must be an integer or a float, and the timestamp is an optional UTC date with ISO format (YYYY-mm-dd HH:mm:SS”). If the timestamp is left off it will default to the current UTC time.

You can make any number of report calls for a given metric key. However, the system will record only the last value submitted in a given minute, and discard any previously submitted metric readings in the same minute.

You can now create you own scripts to reports these metrics automatically or integrate calls to the agent into your own application. Once you have registered your new metric, an agent resource type will be created for this server automatically in the control panel. You can edit this check as you would any other. You can create as many additional custom metrics as you like and they will all show up under the “Custom Metric” category.

If you want to verify that report.py is collecting those metrics, review the generated log entries.

If you have followed the steps above and the new metric and plugin do not show properly, you may need to manually rebuild the agent’s metadata. You can do this by following the guide here.