This article applies to PRTG Network Monitor 16.x.26 or later
Creating a Meta-Scan for Any Sensor Type
PRTG provides the possibility to create your own meta-scan for any sensor type you want. This generic meta-scan functionality allows advanced users to write an individual meta-scan without the need to edit the code of the sensor itself. HTTP sensors, for example, do not have a meta-scan functionality, but if you create a meta-scan for them, you can automatically add various HTTP sensors with different target URLs using the PRTG Auto-Discovery.
Note: We recommend that you use this feature only if you are an advanced PRTG user with knowledge about scripting and device templates.
The generic meta-scan is not officially supported.
To use the generic meta-scan for a specific sensor type, you need to create the following objects.
1) Executable File
You need to write an executable file (for example, an .exe, .ps1, or .bat file) that defines what to monitor. Save this executable into the \Custom Sensors\EXEXML subfolder of your PRTG installation path, for example, as mysensor.exe.
The output of this program has to be valid XML, in this format:
<?xml version="1.0" encoding="UTF-8"?>
<prtg>
<item>
<sub-item-1>x1</sub-item-1>
<sub-item-2>x2</sub-item-2>
[more sub-items]
</item>
<item>
<sub-item-1>y1</sub-item-1>
<sub-item-2>y2</sub-item-2>
[more sub-items]
</item>
[more items]
</prtg>
PRTG will add one sensor for each <item> element within the <prtg> section. The <item> sections define the properties of each sensor, for example, the sensor name. PRTG will copy all these sub-items into fields of the PRTG configuration file, using the same sub-item names.
To find the correct names of the config fields to use them for the sub-items, manually add a sensor of the type you want to use in the meta-scan and export it into a device template:
- Create a device template with the desired sensor and exclude all other sensors from it.
- Open this template with an editor. You can find it in the \devicetemplates subfolder of your PRTG program directory.
- See section <createdata> in the template. Here you can find the names (for example, <httpurl>) of all available parameters that you can use as sub-items in your executable for the meta-scan.
Note: This is not possible for sensors which cannot be saved into device templates (see the manual for a list of exceptions) and sensor types that dynamically scan for available monitoring items when you add the sensor. As an alternative you can use a web developer tool (for example, Firebug) on the settings page of the desired sensor and find the field name this way. Note that the field names are followed by an underscore (_) that you have to leave out in the return code of your executable.
Here is an example for such a sub-item in the XML output:
<httpurl>https://paessler.com</httpurl>
2) Device Template
When you have written your program that returns the XML output in the expected format, you will need to create a device template that attaches the generic meta-scan to your sensor. This template has to execute your meta-scan executable file from above, for example, mysensor.exe.
The device template has to look like this:
<?xml version="1.0" encoding="UTF-8"?>
<devicetemplate id="generic_meta" name="My Generic Meta Scan" priority="1">
<check id="ping" meta="ping"/>
<create id="my_id" kind="http" meta="customexexmlgeneric" requires="ping">
<metadata>
<exefile>mysensor.exe</exefile>
<exeparams/>
</metadata>
</create>
</devicetemplate>
Adjust this template to your needs:
- Replace my_id with a unique ID.
- kind defines the sensor type that the template will add. In this case it is http for HTTP sensors. You can find the kind of any sensor type in a device template that contains this sensor type.
- mysensor.exe is your executable that returns an XML which is used to create your sensors with a meta-scan.
- Save your template into the \devicetemplates subfolder of your PRTG installation.
You can now run an auto-discovery in PRTG using the template which executes your meta-scan program. See below for an example with HTTP sensors.
Example: Generic Meta-Scan for HTTP Sensors
HTTP sensors, for example, do not provide a meta-scan functionality. If you want to monitor specific websites, you would have to add each HTTP sensor with the particular target address manually. Using the generic meta-scan, you can write a program that retrieves target URLs and returns them in the expected XML format to PRTG, telling your device template which websites are to monitor. Then you can run an auto-discovery with this template and PRTG will add all HTTP sensors for each address automatically.
The device template you can use for HTTP sensors and necessary adjustments are described above. Only if you want to implement a generic meta-scan for other sensors, you will have to change the sensor “kind” in the provided template.
Now write your program that retrieves (for example, from a CSV data file) and returns a list of webpages which you want to monitor. For the XML output of the program, you need to define the items for the sensor. You can look up available items in an existing device template, as described above.
The output of your program can look like this, for example:
<?xml version="1.0" encoding="UTF-8"?>
<prtg>
<item>
<name>Http Paessler</name>
<httpurl>https://paessler.com</httpurl>
</item>
<item>
<name>Http Google</name>
<httpurl>http://google.com</httpurl>
</item>
</prtg>
Here is an example (snippet) for a template with an HTTP sensor that queries paessler.com. To find available items look for the content of <createdata>:
<?xml version="1.0" encoding="UTF-8"?>
<devicetemplate id="custom" name="httppaessler" priority="1">
<check id="ping" meta="ping"/>
<create displayname="Paessler" id="{D71DDFE5-3C02-4DCB-ADEB-102662580D64}" kind="http" requires="ping">
<createdata>
<timeout>60</timeout>
<tags>httpsensor</tags>
<priority>3</priority>
<comments/>
<primarychannel>0</primarychannel>
<position>10</position>
<inherittriggers>
<flags>
<inherited/>
</flags>
<cell>1</cell>
</inherittriggers>
<stack>0</stack>
<httpurl>https://paessler.com</httpurl>
<httpmethod>GET</httpmethod>
<httpauthneeded/>
<httpuser/>
<httppassword/>
<httpauthentication/>
<proxy>
<flags>
<inherited/>
</flags>
</proxy>
<proxyport>
<flags>
<inherited/>
</flags>
<cell>8080</cell>
</proxyport>
<proxyuser>
<flags>
<inherited/>
</flags>
</proxyuser>
<proxypassword>
<flags>
<encrypted/>
<inherited/>
<empty/>
</flags>
</proxypassword>
<cookies/>
<postdata/>
<sslmethod/>
<cookies/>
<writeresult/>
<includemusttype/>
<includemaynottype/>
<useuseragent/>
<useragent/>
</createdata>
...
<triggerdata/>
</create>
</devicetemplate>
A PowerShell script that retrieves sensor names and target URLs and returns the according XML output to PRTG can look like this:
#Executable for Auto-Discovery via Generic Meta-Scan Device Template (http)
$path = "c:\temp\myurls.csv"
$csv = Import-csv -path $path
echo '<?xml version="1.0" encoding="UTF-8"?>'
echo '<prtg>'
foreach($line in $csv)
{
[string]$myName = [string]$line.Name.ToString()
[string]$myHttpurl = [string]$line.Httpurl.ToString()
echo '<item>'
echo "<name>$myName</name>"
echo "<httpurl>$myHttpurl</httpurl>"
echo '</item>'
}
echo '</prtg>'
If you run an auto-discovery now with your device template (My Generic Meta Scan in this example) that executes your generic meta-scan executable (mysensor.exe in this example), PRTG will create two new HTTP sensors:
- An HTTP sensor named Http Paessler that monitors the URL http://paessler.com
- An HTTP sensor named Http Google that monitors the URL http://google.com
See Also
Add comment