API calls for groups

Hi Samuel,

Do you want to generate an accumulated uptime for each group? Please also let me know how you generate the list for sensors.

Thank you!

Kind regards
Andreas Günther, Technical Support

Hi Andreas,

At the moment we are working just with the historicdata api calls on a per sensor basis

/api/historicdata.csv?id=11238&avg=0&sdate=2018-01-01-00-00-00&edate=2018-03-01-00-00-00&username

However out customer has their devices in groups, so for example they have Internet, Access Points, Routers, Factory Line etc etc. They need a simple reportable overview of these groups cumulative uptime which can later be investigated further in historic logs to provide a more detailed downtime reason

Hi sorry to be a nag but do you have any advice on how to work this?

Hi Samuel,

I am afraid it is not possible to gather cumulative uptime statistics on group level.

Kind regards
Andreas Günther, Technical Support

Hi Gunther,

Thats a shame i was hoping there'd be some sort of API trickery to make this possible. Out of curiosity is it possible to pull a single uptime figure from PRTG for every sensor in its inventory ?

I do not fully understand the question, or the scale, also I do not get what is different between "uptime" and "cumulative uptime".

Did you want to report to them once a week saying that the update for device x is 26 days, or do you want to report every week saying that on Monday is was 26 day, on Tuesday is was 27 days...etc.

Does "cumulative" mean you want to add 2+ device uptimes together, eg router A and router B both have uptimes of 26 days, so lets report that "routers" has an uptime of 52 days?

So, if its for a small scale (eg, under 20) can you create a new "Sensor Factory" that contains all devices uptimes you want? You can then use this object in a report, and email from PRTG to the client directly. Or give the client access to a PRTG map that contains this data.

But if its for more than 20, or changes all the time, then you certainly want to look at something like PrtgAPI ( https://github.com/lordmilko/PrtgAPI ). In short it would be enumerating through all the sensors in a group (in the devices in that group) and returning their uptime, then dump it out somewhere. This will work for a single point in time, or if you want to report once a week on historical uptimes also, or if you want to group all the uptimes into one big number.

How are you viewing uptime with historicdata.csv? Historic Data does not include the Downtime column present on the sensor history pages within the PRTG UI, and Coverage merely represents the percentage over the averaging period during which monitoring was being performed. Are you potentially observing points in time that contain blanks, and therefore concluding that that must have been a point of downtime?

PS C:\> Get-Sensor -count 1 |select *time*

Downtime         : 1.7704%
TotalDowntime    : 8.00:32:40
Uptime           : 98.2296%
TotalUptime      : 445.03:30:50
TotalMonitorTime : 453.04:03:30

Potentially the TotalUptime / TotalDowntime could be of assistance? If you want to say "everything in the group was up over this timespan" you could potentially create a custom EXE/Advanced sensor that tracks the combined TotalDowntime of every single sensor in the group (a useless metric in and of itself).

$sensors = Get-Group -Id 1001 | Get-Sensor
$seconds = $sensors | foreach { $_.TotalDowntime.TotalSeconds }
$sum = ($seconds | Measure-Object -Sum).Sum
$timeSpan = [TimeSpan]::FromSeconds($sum)

If the combined value ever increases at a point in time, that means *something* in the group went down (or continued being down) between the last scan and now.

If you gave this custom sensor a channel for each of the groups you wanted to monitor, a historicdata.csv call (or the Get-SensorHistory cmdlet) would then allow you to analyze the periods during which the group's integrity was either intermittently or increasingly being "compromised" by something in it being down

For reference, it appears historicdata.csv appears to exclude the Downtime column when avg=0 is specified and the automatic averaging interval determined by PRTG resolves to the true interval of the sensor.

As such, requesting data from the last hour of a second that scans at 60 second intervals with

• No average specified (defaulting to avg=0) will include Downtime
• avg=0 will exclude Downtime
• avg=60 will include Downtime
• avg=300 (or anything else) will also include Downtime

Requesting data over over the span of 2 days with avg=0 will resolve to 1 hour intervals, resulting in Downtime being included.

Hi LordMilko!

I like the way you're thinking and the output from that prtg-api query is infinitely helpful! Thanks so much. Few questions, the TotalMonitorTime, what is this? Is this limited by our historic data cache and when they are purged ? and does it factor in paused times? Looking at the results for 10 APs that all have the same retention settings and their total monitor time is different. I am guessing the total monitored time works from the DataCollectedSince figure? Is there a way to manipulate the time frame on datacollectedsince in the query rather than just factoring days/hrs into month chunks?

I fear i am wording all these questions terribly but any guidance is gratefully received :)

TotalMonitorTime is the total amount of time the object has been monitored (not paused) since it was created

DataCollectedSince is the point in time when monitoring started on this object (and TotalMonitorTime started initially increasing). Usually this is a minute or two after the creation time.

HI Lord Milko! Is there any way to change the total monitored time to a range? Even if its just down something like limiting it to 720hrs to get the month ?

Hi LordMilko, do you know how the TotalMonitorTime is formatted? on a query run 21 days apart the same to devices show a TmT of

402:11:02:53 and 404:16:06:01

I had assumed that the 40x number was days but this doesnt seem to be the case

TotalMonitorTime is a TimeSpan object. As such, each of these sensors appear to have a total monitor time of over 402 and 404 days, respectively.

The TotalMonitorTime property represents the raw API field knowntime_raw. API field "knowntime" by contrast is a percentage, indicating this field is related to the Coverage property showed on the sensor in the PRTG UI. PRTG's API documentation states the knowntime field represents "Sum of cumulated uptime and downtime of a sensor"

From my experimentation, I can confirm that the TotalMonitorTime property appears to increase whenever a sensor completes a scanning interval. You can view this yourself by monitoring the TotalMonitorTime of a ping sensor. It will increase by 30 seconds every 30 seconds

Based on this, the implication here is that these two sensors either failed to refresh themselves at their specified intervals, or there is a bug in the script that is executing the query. I recommend manually executing the command

Get-Sensor -Id <id> | select TotalMonitorTime

and then executing it again after the sensor's interval has elapsed and confirm that the amount of time is increasing as expected.

Hi Samuel,

I totally get where you're coming from.

I was asked to create '7 day uptime reports' for different types of devices. The way I achieved this was to do the following:

• Tag my devices by type
• Use the API to get the devices that were tagged
• For each device use the API to get the historic data for the last 7 days
• Use powershell to calculate the 7 day uptime
• Create a custom powershell object and add to my report.

The report could then be exported to csv and distributed to those who needed the info.

Here is some of the code I used:

(Note: I used lordmilko's PRTGAPI PowerShell Module https://github.com/lordmilko/PrtgAPI )

$sensors = @() 
$sensors = Get-Sensor -Tags *router* | sort -Property Group
$report = @()
$edate = Get-Date -Format yyyy-MM-dd
$sdate = (Get-Date).AddDays(-7).ToString("yyyy-MM-dd")
$filteredSensors = @()
$filteredSensors = $sensors | where {$_.Name -eq "PING"}
foreach($s in $filteredSensors)
{
    $ID = $s.Id

    try
    {
        $url = "https://$PRTGHost/api/historicdata.csv?id=$ID&avg=86400&sdate=$sdate-00-00-00&edate=$edate-00-00-00&$auth"
        Write-Host -ForegroundColor Cyan "VERBOSE: $url"
        $request = Invoke-WebRequest -Uri $url -MaximumRedirection 0 -ErrorAction Ignore
        $reportcsv = convertFrom-csv ($request) 
        [decimal]$downtime = 0
        foreach($r in $reportcsv)
        {
            [decimal]$downtime = [decimal]$downtime + [decimal]$r.'Downtime(RAW)'
        }
        $string = $reportcsv | where {$_."Date Time" -match "Averages"} | select "Date Time"
        [int]$count = [int]$string.'Date Time'.Substring(13,1)
        [decimal]$totaluptime = [math]::Round((100 - ([decimal]$downtime / $count)), 2)
    }
    catch
    {
        [string]$totaluptime = "Cannot Retrieve Data"
    }
    $result = [PSCustomObject]@{
        "Site" = $s.Group
        "Device" = $s.Device
        "Uptime" = $totaluptime
    }
    $report += $result
    $result
}
$report | Out-GridView
#$date = Get-Date -Format yyyyMMdd
#$report | Export-Csv -Path "D:\PRTG Data\Reports\SevenDayUptimeReport-$date.csv" -NoTypeInformation

Hi Matthew! This looks hugely promising thank you so much, i have it somewhat working although it is reporting 100% on devices that certainly are not 100% up. I will need to add in a line to also consider unknown state