This article applies to PRTG 24.

Script v2 sensor

The Script v2 sensor is custom sensor in PRTG that monitors a system using a Python script. It enables users to create script sensors, which are then used as a Command-Line Interface (CLI) program in PRTG. This streamlines the process of writing a script sensor and maintaining the environment that the sensor needs to run.

Content

1. Improvements and technical differences in the Script v2 sensor
2. Python installation
3. Script differences

1. Improvements and technical differences in the Script v2 sensor

The following are the improvements of the Script v2 sensor compared to the Python Script Advanced sensor:

• We can add new features without breaking backwards compatibility. We guarantee that updates to the Script v2 sensor will not break custom scripts written for a previous version.
• The expected script result is validated against a JSON schema. For more information see script-v2-json-schema.
• You can check script outputs for validity, using a JSON schema validator, without the need to actually run the sensor in PRTG.
• When a sensor result is invalid, the sensor debug log provides detailed information on why.
• Parameters and results to and from the script are passed via pipe, increasing security by not exposing them to process lists (as opposed to passing by arguments).
• An external python distribution is installed on the system (instead of the one delivered with PRTG).
  • Users can install their own packages easily, allowing for higher number of applications.
  • Users can patch security issues in python and python packages quickly and independently from PRTG.
• You can use standard argument parsing from python. A Script v2 sensor can now be written as a CLI program that can make use of the standard argparse library.
• The Script v2 sensor is fully supported on the multi-platform probe.

2. Python installation

The Script v2 sensor requires python3 to be installed on the remote probe system. This gives the user control of the python installation and any installed python packages.

This setup has two benefits. First, we keep the input and output format of user scripts compatible with newer versions of the Script v2 sensor. Second, the user ensures that there is a working python environment which fulfills the requirements of their sensor scripts.

2.1. Shortcomings of the Python Script Advanced sensor

PRTG included a python interpreter, which was an easy way to install python for the Python Script Advanced sensor. However, this came several maintenance issues such as:

• Updates to the bundled python installation broke python script advanced sensors due to changes in the language.

• Difficult maintenance of third-party packages.

• Hard to push targeted security fixes in a timely manner as it was synced with the PRTG release cycle.

3. Script differences

PRTG handles Python Script Advanced and Script v2 scripts differently.

Input parameter handling

With the Python Script Advanced sensor, the following code was used to extract a JSON object sent by PRTG:

  data = json.loads(sys.argv[1])
  # get the hostname that was passed from PRTG.
  print(data["host"])

Arguments with the Script v2 sensor are sent via pipe to stdin. To parse the input from a Script v2 sensor, we recommend that you use argparse to handle the input parameters:

argparser = argparse.ArgumentParser()
argparser.add_argument("--your_parameter")
args = argparser.parse_args()
# now we can access your_parameter from args to get the value passed on the cli
print(args.your_parameter)

This setup makes it possible to configure parameters in PRTG via Script Settings | Parameters | --your_parameter 9001:

Click to enlarge

Output format

The Python Script Advanced sensor used the following output format:

{
  "prtg": {
        "text": "The sensor message",
        "result": [
            {
                "Channel": "FIRST CHANNEL",
                "Value": 9001,
                "Unit": "",
            },
        ],
    }
}

The Script v2 sensor introduces a new output format based on a versioned JSON schema. We can use the versioned schema to introduce new fields in the result without breaking existing scripts that use an older version of the output format.

{
  "version": 2,
  "status": "ok",
  "message": "The sensor message",
  "channels": [
      {
          "id": 10,
          "name": "FIRST CHANNEL",
          "type": "integer",
          "value": 9001,
      }
  ]
}

More

Knowledge Base

• Where can I find the JSON schema against which the Script v2 sensor validates my script output?
• How can I make my Python scripts work with the Script v2 sensor?