Create a new custom command scheduled test

Navigate to the Tests tab.
Click the "Custom Command" sub-menu link.
Click the "+ Add Scheduled Custom Command Test" button.
Follow the configuration wizard:
1. In the "Select Source Agents" section, pick the individual agent(s) or agent groups that will run the command.
2. In the "Configure Test" section paste the custom command to execute, then in the "Output Schema" section add one or more "Metric:Unit" pairs based on the desired output (must match what's in the script); use the + button to add more than one of "Metric:Unit" pairs.
3. In the "Timeout (seconds)" section update, if needed, the default timeout that will rule the maximum execution time for the command; by default the timer is set to 30 seconds.
In the "Schedule" section specify the frequency of execution of the command.
In the "Run Options" select the execution mode amongst the following options:
1. Parallel (default): Selected agents in 4.a will run the command at the same time.
2. Serialized: Selected agents in 4.a will run the command one after another.
3. Randomized: Selected agents in 4.a will randomly run the command within the time window as specified in the "Time window (minutes)" input box.
In the "Alerts" section select the alert profiles, if any, to apply to the test results.
1. Note: Custom commands only support "Scheduled Test Error" alert types which applies when the executed script triggers an error (e.g. command not found).
Click the "Create Custom Command Test" button to save and push the custom command to the agents.

Custom Command Script Requirements

The first line of your custom command script must define the interpreter in the following way:
- Bash: #!/usr/bin/env bash
- Python: #!/usr/bin/env python
The last lines of the custom command script must print the output, such as:
- Bash: echo "load_time=$load_time"
- Python: print(f"disk_io={random.randint(100, 1000)}")
The output must be in the format key=value, one per line.
Values must be numeric (integer or float).
Keys must be alphanumeric and unique.
Output should go to stdout (not stderr).
Scripts must not be interactive.
Scripts can't be longer than 20,000 characters otherwise the UI will trigger an error.

Configuring the Metric:Unit pair

After adding your script in the "Configure Test" section of step 4.b, make sure that the "Output Schema" section is configured the following way:

For each Metric your script prints, create a Metric in the UI using the same key name.
For the Unit, use a descriptive unit like seconds, bytes, %, etc. this will be displayed in the chart's legend

Example
If your script outputs load_time=1.23, then in the dashboard:

Metric = load_time
Unit = seconds

Note: If a key is not defined in the dashboard, its value will be ignored.

You can provide your own Bash or Python script to generate custom metrics. These scripts run on the agent and must output values in the format:

metric_name=value

Error Messages

If there are specific error messages you want to be caught you have to prefix them with "ERROR:".

In the following example, if the directory /data is missing the script prints the appropriate error message and exits:

The messages is caught and displayed on the UI:

Configuration Example

Dashboard configuration at step 4.b

Dashboard results

Example Scripts

Bash – Measure HTTP Response Time

#!/bin/bash
URL="https://example.com"
load_time=$(curl -o /dev/null -s -w "%{time_total}\n" "$URL")
echo "load_time=$load_time"

Python – Generate Random Metrics

#!/usr/bin/env python3
import random
print(f"cpu_usage={random.uniform(10, 90):.2f}")
print(f"disk_io={random.randint(100, 1000)}")

Bash – Ping and Packet Loss

#!/usr/bin/env bash
loss=$(ping -c 4 8.8.8.8 | grep -oP '\d+(?=% packet loss)')
echo "packet_loss=$loss"

Invalid Output Examples (Will Be Ignored)

latency:123 (use latency=123)
value=abc (non-numeric)
=42 (missing key)
Time was 1.2 seconds (not in key=value format)

Best Practices

Use lowercase, descriptive key names (e.g. response_time, cpu_usage)
Be consistent with units (e.g. always use seconds or ms)
Keep scripts efficient and fast to run

Let us know if you'd like help writing or troubleshooting your script, post your requests to the NetBeez community.

Install NetBeez Agents

Agent Configuration - Interface Management

Path Analysis

DNS

Traceroute