The FortiMonitor Agent supports generating custom metrics, which provides a mechanism for your own applications to push custom data to our system and leverage FortiMonitor’s alerting and dashboard functionality. To use the custom metrics, you need to have the latest version of the Agent.

To use the custom metric support, you create a JSON file each time there is a metric result to report and place it in a special agent directory. The next time the agent syncs, it picks up that file and sends it to the FortiMonitor Monitoring Cloud where it is processed and begins alerting.

Metric File Generation

The metric files are JSON files that get placed by default in the following directories:

Linux

/usr/share/fm-agent/incoming

Windows

C:\Program Files (x86)\FortiMonitorAgent\custom_metric

Additional directories can be specified by setting a metric_incoming_directory variable with a comma-separated list of directories in your agent configuration file (Linux Only) located in /etc/fm-agent/panopta_agent.cfg.

On Windows, you can provide a single path in the MetricIncomingDirectory entry in the agent config file, Agent.config, which is located in the Agent directory. Make sure to also restart the FortiMonitor Agent service after saving.

Each file should look like the following:

{"agent_payload_version": 1.0,

"plugin_textkey": "sample_custom_plugin",

"plugin_category_name": "Sample Application Plugin",

"metrics": [

{"textkey": "database_connection",

"label": "Database is accessible",

"value": 1,

"unit": "boolean",

"timestamp": "2017-08-17 10:53:00"

},

{"textkey": "generated_lines",

"label": "Number of lines in batch file",

"value": 800,

"unit": "lines",

"timestamp": "2017-08-17 10:53:00"

}

]

}

The top-level keys in the document set the agent version, which should be left as 1.0, and the plugin textkey and category name. The textkey is used to reference this application internally, and can be any string of letters, numbers, periods, and underscores. The plugin category name is used for display in the control panel’s metric catalog and for alert descriptions.

The metric list contains a separate entry for each metric result that you wish to report. The keys in each entry are:

• textkey: an internal reference for the resource the metric applies to. Follows the same character convention as the plugin textkey.

• label: a human readable label for the metric, which is shown in the control panel and alerts.

• value: the actual numeric metric values associated with the metric.

• unit: the unit of measurement for this metric. boolean and percentage are recognized unit types which will cause special behavior in the app

• timestamp: The time associated with the metric result. The timestamps are in YYYY-MM-DD HH:MM:SS format, and need to be in the UTC timezone.

You can bundle together multiple metric results into one file, or create each one as a separate file. The agent will pick up and process each file found in the import directory. We recommend naming files based on the application name and current timestamp to avoid running into conflicts with previous files that are waiting to be picked up.