New-OoklaSpeedTest.ps1

In my post “Get-WeatherLinkData.ps1” I mentioned we use the free version of Paessler’s PRTG Network Monitor to monitor all we have here. It’s a great little monitoring platform, and we use it to not only keep an eye on the servers and various web-pages we run, but also track and trend our weather.

After suffering poor service from a previous ISP a few years ago, we started running a script utilising H.Merijn Brand’s Perl Speedtest CLI on our PRTG server to keep a track of speeds. It did the job but meant that Perl needed to be installed on the server.

It thus caught our eye when we saw recently that the world standard “speedtest.net” by Ookla has spawned an API.

And thus, New-OoklaSpeedTest.ps1 was born.

This script runs on a schedule under PRTG, captures the results of the speed test and feeds all the useful metrics into PRTG. Now we have a reliable, trustworthy report of upload and download speeds, jitter, latency and packet loss.

The API will let you specify the server to query, or you can let it decide. The server that you tested against is output by Ookla, but as PTRG won’t capture text fields, we can’t surface it in the reports.

Run with no switches, the script will display the output on screen. Add a “-filename” value and it will save the output to that file/location, overwriting any previous file of the same name.

If you have an unreliable connection, “-retries” (a value from 0 to 4) lets you make multiple attempts before reporting a failed test to PRTG.

Adding “-precision” and a number from 0-8 will report the results to that number of decimal places. (At the time of writing, the Speedtest API *also* accepts a precision value, but it doesn’t work well, reporting some badly rounded numbers like latency of 8.2870000000000008 when 3-digit precision was requested – so I’ve done the rounding in the script.)

The optional ‘-debug’ switch will save a lot more information into a monthly log file, in the format “New-OoklaSpeedTest-yyyyMMM.log”, with each entry prefaced by a timestamp:

Jul11-2230 Launched
Jul11-2230 Output file is     "W:\SCRIPTS\New-OoklaSpeedTest.ps1\test.xml"
Jul11-2230 Speedtest found at "W:\SCRIPTS\New-OoklaSpeedTest.ps1\Speedtest.exe"
Jul11-2230 Params   = "--format=json --accept-license 2>&1)"
Jul11-2231 Response = {"type":"result","timestamp":"2020-07-11T12:31:21Z","ping":{"jitter":0.53700000000000003,"latency":9.0299999999999994},"download":{"bandwidth":5980994,"bytes":38826919,"elapsed":6504},"upload":{"bandwidth":2386128,"bytes":21848868,"elapsed":9304},"packetLoss":0,"isp":"Telstra Internet","interface":{"internalIp":"10.10.17.77","name":"","macAddr":"B4:2E:99:44:35:61","isVpn":false,"externalIp":"xxx.yyy.zzz.aaa"},"server":{"id":5744,"name":"Digital Pacific","location":"Sydney","country":"Australia","host":"speedtest.mirror.digitalpacific.com.au","port":8080,"ip":"101.0.120.90"},"result":{"id":"4d9ba3fc-6f1c-4f89-bd7a-1b4644fbdd80","url":"https://www.speedtest.net/result/c/4d9ba3fc-6f1c-4f89-bd7a-1b4644fbdd80"}}
Jul11-2231 InternalIp   : 10.10.17.77
Jul11-2231 IsVpn        : False
Jul11-2231 ExternalIp   : xxx.yyy.zzz.aaa
Jul11-2231 ISP          : Telstra Internet
Jul11-2231 ID           : 5744
Jul11-2231 Name         : Digital Pacific
Jul11-2231 Location     : Sydney
Jul11-2231 Country      : Australia
Jul11-2231 Host         : speedtest.mirror.digitalpacific.com.au
Jul11-2231 IP           : 101.0.120.90
Jul11-2231 Download b/w : 5980994
Jul11-2231 Upload b/w   : 2386128
Jul11-2231 Jitter       : 0.53700000000000003
Jul11-2231 Latency      : 9.0299999999999994
Jul11-2231 Packet loss  : 0
Jul11-2231 Exited cleanly.

 

Add it to PRTG

Download Speedtest from Ookla and the script from Github and place them in the Custom Sensors directory on your PRTG Server (C:\Program Files (x86)\PRTG Network Monitor\Custom Sensors\EXEXML). Links are at the bottom of this page.

In the PRTG console we will now create the sensor. It doesn’t really matter what device it’s attached to – you could just put it on the Probe Device. I’m going to put mine on the Internet device, which PRTG creates by default.

Click on Add Sensor and select the “EXE/Script Advanced” sensor type. Give your sensor a name and select the script from the EXE/Script dropdown.

You don’t need to add any extra parameters unless you need to enable debug or want to force a particular Speedtest server, but you will probably want to change the Scanning Interval to something greater than the default 60 seconds. I’ve chosen to run it once an hour.

Click “Create” and you are done.

If you’ve set a long scanning interval it will probably take a few minutes before the script fires and collect its first set of data. Once it has, the grey question mark will turn into a green tick. If you’re the impatient type like me, you can right-click on the sensor and select Scan Now.

It should only take a minute to refresh and show the green tick.

You can now view your data.

GDPR

If you’re in the Euro-zone, you’ll need to consent to GDPR, and for that I’ve added another switch.

You’ll need to edit the sensor to add this, as shown here:

(I’ve captured the relevant terms and conditions from Ookla in the script’s header, if you’re feeling so inclined.)
 

Making it pretty

There’s not a lot really here that needs to change. Click on each of the channels in the Overview page and consider setting upper warning and error limits on latency, jitter and packet loss and lower warning, and error limits on upload and download speed.

Here I have set a warning if the download speed drops below 40Mb/s and an error if it drops below 20Mb/s. The later will trigger an email to prompt me to give our ISP a kick.

Scrolling down the “Edit Channel” screen, you might like to change the number of decimal places from “All” to a more manageable number. While you can set the number of decimal places in the script, if you don’t limit it in here, the averages at the top of the column end up with a lot of useless digits.

I’ll change all mine to 2 except for Packet loss. That can stay at 0.

Much neater.

Finally, scroll right down to the bottom and change the vertical axis scaling from automatic to manual.

Given that we are blessed with a 50Mb/s data service here, 50 seems like the obvious maximum for the bandwidth measurements. Hopefully setting the minimum at 0 turns out to be greatly pessimistic.

For latency and jitter, I set the maximum at 100ms and minimum 0. That should catch most peaks.

It doesn’t matter if you later change your mind on any of these settings – they only affect the rendering of the data. The data is intact so any changes made will be reflected immediately.

The end result is a nice easy to read graph of all the speedtest data. Any anomalies are obvious and if you do need to log a fault with your ISP, you have a complete history of your service.

Troubleshooting

If your speedtest sensor is throwing errors there are two ways you can peek under the hood to see what’s going wrong.

PRTG Logs

To start PRTG logging results, go back into the sensor settings and enable “Write EXE result to disk in case of error”. This will do exactly as it says on the box and create a log file of the output of the script in “C:\ProgramData\Paessler\PRTG Network Monitor\Logs\sensors”.

You might need to make a note of the sensor ID number from the main overview page if you are logging more than one sensor. Note that the log file is overwritten each time it runs.

New-OoklaSpeedTest Logs

We’ve also built logging into the script file itself. Once again, go into the sensor settings and simply add the -debug switch as a Parameter. This will create a logfile in the format “New-OoklaSpeedTest-yyyyMMM.log” in the same folder as the script itself.

This log file is continuous, starting a new log every month. As well as displaying any errors it can be useful for identifying exactly which speedtest server is being used for each test as well as all the raw data from the test.

 

Pre-req’s

You need to have downloaded the SpeedTest API first. It’s a simple download and doesn’t require installation. You can download it from here.

Download

The script lives at GitHub: https://github.com/greiginsydney/New-OoklaSpeedTest.ps1.

Revision History

14th July 2020. Added the GDPR reference.
14th July 2020. Added troubleshooting section.
12th July 2020. This is the initial publication.

– G.

2 Comments

  1. Hi Greig!

    Very useful script! Have it deployed on my Internet probe and it’s working great! I was curious, if it would be possible for this script to work on a client desktop in a LAN probe?

    I would like to have this script run on client machines in my LAN and cross reference their results with what is gathered from the Internet probe. I’m not too familiar with how custom sensors work and was curious if you had any insight here.

    Thank you again for the great script!

Leave a Reply

Your email address will not be published. Required fields are marked *

... and please just confirm for me that you're not a bot first: Time limit is exhausted. Please reload the CAPTCHA.

This site uses Akismet to reduce spam. Learn how your comment data is processed.