Custom Metrics

Overview

You can configure custom metrics and query them with OpenTelemetry.

This feature is available in:

• R82 and higher

• R81.20 Jumbo Hotfix Accumulator, Take 54 and higher

• R81.10 Jumbo Hotfix Accumulator, Take 135 and higher

• R81 Jumbo Hotfix Accumulator, Take 99 and higher

Procedure

1. Connect to the command line on the Check Point server.

2. Log in to the Expert mode.

3. Create a shell script to configure the required objects for your custom metrics.

   Create this script file in any directory.

   Example: /home/admin/script_with_custom_metrics.sh

   Notes: You can use this script file as a template: /opt/CPotlpAgent/custom_scripts_template.bash To create a script file, run: vi /path/to/your/script_file

   This shell script file must contain the lines described below.

   Part 1 (mandatory) - The call to the shell and to the required Check Point script

   Syntax:

   #!/bin/bash . /opt/CPotlpAgent/cs_data_handler_is.bash

   Part 2 (mandatory) - Configure a custom metric object

   Syntax:

   set_ot_object new value <Metric Value> set_ot_object last label <Metric Label Key 1> <Metric Label Value 1> set_ot_object last label <Metric Label Key 2> <Metric Label Value 2> ... set_ot_object last label <Metric Label Key N> <Metric Label Value N>

   Example:

   set_ot_object new value 3.1 set_ot_object last label Client_IP 192.168.30.1 set_ot_object new value 4.0 set_ot_object last label Client_IP 192.168.30.2 set_ot_object last label Client_Type SecurityGateway

   Result JSON array of custom metrics:

   [ { "value": 3.1, "labels": [ { "Client_IP": "192.168.30.1" } ] }, { "value": 4, "labels": [ { "Client_IP": "192.168.30.2" }, { "Client_Type": "SecurityGateway" } ] } ]

   Part 3 (optional) - Print verbose output

   You can configure a desired log message that your shell script will save in the /var/log/<script_name>.log file.

   Example:

   • If the script file is: /home/admin/script_with_custom_metrics.sh

   • Then the log file is: /var/log/script_with_custom_metrics.log

   The line must start with the function name "verbose_print" and supports two parameters - a text string "%s" and an integer value "%d".

   Possible positional arguments:

   verbose_print "%s %d" "<Desired Text Message>" <Desired Integer Value>

   verbose_print "%d %s" <Desired Integer Value> "<Desired Text Message>"

   Example:

   verbose_print "My verbose message: %s ; My integer value: %d" "Script executed" 10

   verbose_print "My integer value: %d ; My verbose message: %s" 10 "Script executed"

   Part 4 (mandatory) - Show an exit message and generate an exit code

   Syntax:

   script_exit "<Desired Exit Message>" <Integer Exit Code>

   Configure one of these exit codes:

   • 0 for success.

   • 1 for input error or non-critical error.

   • 2 for critical error.

   Example:

   script_exit "Finished running" 0

4. Prepare the required payload in a JSON file for your custom metric.

   Create this JSON file in any directory.

   Example: /home/admin/payload_with_custom_metrics.json

   This JSON file must contain these lines (replace the placeholder strings "<...>" with your actual strings):

   { "state" : "<State>", "command" : "<Command>", "desc" : "<Description>", "name" : "<Name>", "type" : "<Type>", "unit" : "<Unit>", "interval" : <Interval> }

   Where:

   Parameter	Description
   "state"	The state of the collector: "enabled" "disabled"
   "command"	The command that the Skyline Agent needs to run to get the values and labels of the custom metric. The collected data will be in the JSON format - a batch of metric values (real value and label values).
   "desc"	A description of this custom metric.
   "name"	The name of the custom metric. Must be unique. Must contain only lowercase Latin letters (a-z). Use the period character "." as a separator between each name part. Example: system.cpu.util Best Practice - For the metric convention name, refer to https://opentelemetry.io/docs/specs/semconv/general/metrics/.
   "type"	Can be one of these: "Counter" To count something by recording a delta value. If the value is monotonic, use "Counter". Otherwise, use "UpDownCounter". "UpDownCounter" To measure something by recording an absolute value that is additive / summable. "Gauge" To measure something by recording an absolute value that is not additive / summable. Best Practice - For the metric types, refer to https://uptrace.dev/opentelemetry/metrics.html.
   "unit"	The measurement unit for the custom metric. For example, the unit for the metric "hardware.memory.util" is "bytes". If the custom metric uses a non-standard unit, you must enclose it in curly braces { }. For example : "{interval}". Best Practice - For the unit convention, refer to https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/metrics.md#instrument-units.
   "interval"	How frequently (in seconds) the Skyline Agent needs to run the command.

   Example:

   { "state" : "enabled", "command" : "cat /home/admin/HW_sensors_data.json", "desc" : "The current temperature in the appliance", "name" : "hardware.sensors.temperature", "type" : "Gauge", "unit" : "{celcius}", "interval" : 2 }

5. Run the configuration command to apply the JSON payload:

   sklnctl otlp add –name /<Path>/<Shell Script File> --path /<Path>/<JSON File>

   Example:

   sklnctl otlp add –name /home/admin/script_with_custom_metrics.sh --path /home/admin/payload_with_custom_metrics.json

6. Restart the OpenTelemetry Agent:

   /opt/CPotlpAgent/CPotlpagentCli.sh stop

   /opt/CPotlpAgent/CPotlpagentCli.sh start

7. Examine the currently exported metrics:

   sklnctl otelcol metrics --show