-
-
Notifications
You must be signed in to change notification settings - Fork 38
Historical Information
Historical information about events that have occurred on objects (sensors going up, down, notification triggers being sent, probes disconnecting, etc) can be retrieved with the GetLogs method. By default, PRTG only stores the last 30 days worth of logs.
// Retrieve logs from the last 7 days
var logs = client.GetLogs();By default, GetLogs will attempt to retrieve the last 500 logs from the root node for the past seven days. A custom number of items can be retrieved using the count parameter. If count is null, all logs within the specified time period for the specified object will be retrieved.
// Retrieve the last 30,000 logs from the root node within the last 7 days
var logs = client.GetLogs(count: 30000);Depending on the size of your installation this can not only take a while, but can cause the request to time out, causing your program to throw an exception.
If you wish to retrieve a large number of of items (i.e. likely more than 20,000) it is recommended to use the StreamLogs method.
// Retrieve all logs from the last 7 days
var logs = client.StreamLogs();
foreach (var log in logs)
{
Console.WriteLine($"{log.Name}: {log.Message}");
}StreamLogs returns an IEnumerable<Log>. As the enumeration is iterated, logs are retrieved as required 500 items at a time. This allows you to easily retrieve hundreds of thousands of items without killing your server.
Queries can also be specified via LINQ style query expressions, allowing high performance queries to be executed via dynamically generated request parameters.
var names = client.QueryLogs(l => l.DateTime > DateTime.Now.AddDays(-2) && l.DateTime < DateTime.Now)
.Select(s => s.Name)
.Take(200)
.Distinct();For more information on using LINQ style queries, see Queries.
GetLogs supports several parameters for filtering the number of results returned, including
- ID of the object to retrieve logs from
- Start and end dates to retrieve logs between
- Number of items to retrieve
- Status (event type) of the object
// Retrieve the last 400 logs from the object with ID 2034 between now and three days ago
var logs = client.GetLogs(2034, endDate: DateTime.AddDays(-3), count: 400);// Retrieve logs about disconnected probes from the last month from the object with ID 3015
// (making the assumption there haven't been more than 500)
var logs = client.GetLogs(3015, RecordAge.LastMonth, status: LogStatus.Disconnected);If you wish to continuously display new logs as they are created, this can be achieved via the WatchLogs method.
var logs = client.WatchLogs(status: new[]{LogStatus.Connected, LogStatus.Disconnected});
foreach (var log in logs)
{
Console.WriteLine($"Probe {log.Name} {log.Status} at {log.DateTime}"
}Unlike other GetLogs methods, logs returned from WatchLogs are always ordered oldest to newest.
By default, WatchLogs will poll for new logs once every second. WatchLogs will continue to request new logs from PRTG until one of the following conditions is met
- You stop enumerating the collection (while
WatchLogsisn't waiting for a new log) - The optional
progressCallbackparameter returnsfalse - The optional
CancellationTokenis cancelled via itsCancellationTokenSource
PrtgAPI always ensures the meaning of startDate and endDate mirror the direction with which results are displayed. This contrasts with the underlying PRTG API where the items you ask to "end" with end up being displayed "first". Please keep this in mind in the event you are debugging with PrtgClient.LogVerbose.
| GetLogs | WatchLogs | PRTG API | |
|---|---|---|---|
| Output | Newest -> Oldest | Oldest -> Newest | Newest -> Oldest |
| StartDate | Closest to now | Furthest from now | Furthest from now |
| EndDate | Furthest from now | N/A | Closest to now |
Note that when streaming in parallel (with StreamLogs), logs will be ordered according to the speed at which they are returned. If you wish to stream logs that are already in the proper order, you must stream serially by specifying serial: true.
Historic channel values of a sensor can be retrieved using the GetSensorHistory method. The GetSensorHistory method allows you to specify a custom date range and averaging interval for the historic records to be retrieved.
// Get historic channel data for the sensor with ID 1041
var history = client.GetSensorHistory(1041);By default, GetSensorHistory will average using 300 seconds (5 minutes), and retrieve records for the past 60 minutes. If an average of 0 is specified, PRTG will return historic channel data using the normal interval defined on the sensor.
// Get historic channel data for the sensor with ID 1041 according to the sensor's actual interval,
// for the time period of 1 hour, between 2 and 3 hours ago
var history = client.GetSensorHistory(1041, 0, DateTime.Now.AddHours(-2), DateTime.Now.AddHours(-3));Due to limitations of the PRTG API, channels that contain value lookups will only display their lookup names when an average of 0 is specified. However, PRTG will also only include Downtime information when an average is specified that is not 0. As such, care should be taken when considering the average to use based on the desired use case. To manually specify the true interval of a sensor, specify the Interval.TotalSeconds
var sensor = client.GetSensor(1041);
var history = client.GetSensorHistory(sensor, (int)sensor.Interval.TotalSeconds);Records returned by GetSensorHistory are ordered newest to oldest. As such, startDate represents the closest time to now, while endDate represents the furthest point to retrieve to. If only an endDate is specified, logs will be retrieved between now and then
var history = client.GetSensorHistory(1041, endDate: DateTime.Now.AddDays(-1));GetSensorHistory returns a List<SensorHistoryData>. Each SensorHistoryData record contains a ChannelRecords property, listing all the values each channel of the sensor had at the specified time period.
// Display all values the "Total" channel had over the past 24 hours
var history = client.GetSensorHistory(1041, 0);
var totalChannelRecords = history.SelectMany(r => r.ChannelRecords.Where(c => c.Name == "Total"));
Console.WriteLine("Values for channel 'Total' over the past 24 hours:");
foreach(var record in totalChannelRecords)
{
Console.WriteLine($"{record.DateTime}: {record.Value}";
}GetSensorHistory optionally allows a count to be specified. If a count is specified, GetSensorHistory will limit the number of results within the specified time period to the specified number. Note that if a count is specified that is higher than the number of results retrieved in the period, all results will simply be returned.
When retrieving historical records over a large time period with a low averaging interval (such as 60 seconds) it may be advantageous to stream records from the PRTG Server, instead of asking for them all at once. This can be achieved via the StreamSensorHistory method
var records = client.StreamSensorHistory(1001, endDate: DateTime.Now.AddDays(-10));StreamSensorHistory returns an IEnumerable<SensorHistoryData>. As such, results will only be retrieved as the IEnumerable is iterated.
//Retrieve the first 600 records between now and 10 days ago, executing
//the minimum number of requests to retrieve the desired number of items
var records = client.StreamSensorHistory(1001, endDate: DateTime.Now.AddDays(-10)).Take(600).ToList();Note: while GetSensorHistory treats the startDate as closest to now and the endDate as the furthest from now, the PRTG API actually inverts this, with the "start date" of logs as the point in time furthest away from now, and the "end date" as the point in time closest to now. PrtgAPI flips the meaning of these values for consistency with other methods within PrtgAPI (such as GetLogs). Keep this in mind in the event you ever wish to interface with the underlying API.
When you generate a historic data report in PRTG, at the bottom of these reports is a nifty table that shows the precise dates and times a given sensor alternated between various sensor states. These dates and times are absolute, and provide the same values regardless of the averaging value that is specified for the rest of the report. The information that is provided in this table is absolutely perfect for generating downtime reports, and PrtgAPI provides a means to retrieve this information via the GetSensorHistoryReport method
//Generate a sensor history report for the sensor with ID 1001 between now and this time yesterday
var results = client.GetSensorHistoryReport(1001);Like GetSensorHistory, by default if no startDate and endDate are specified, GetSensorHistoryReport will retrieve data from between now and 24 hours ago. GetSensorHistoryReport returns a collection of SensorHistoryReportItem objects, each of which describes a particular incidence of a sensor changing from one state to another.
//Calculate the total downtime of the sensor with ID 1001 over the past 6 months
var duration = TimeSpan.FromSeconds(client.GetSensorHistoryReport(1001, endDate: DateTime.Now.AddMonths(-6))
.Where(r => r.Status == Status.Down)
.Sum(r => r.Duration.TotalSeconds));When analyzing sensor history report results, it is important to note that the StartDate and EndDate values that are provided on each individual SensorHistoryReportItem are limited to being within the startDate and endDate that were originally specified to GetSensorHistoryReport. As such, the first and last items of any report will likely extend their start and end dates outside the originally requested range. This is important to consider when analyzing downtime: if you only request a report for the last 30 days, and you can see a sensor was down for the first 15 of those 30 days, that doesn't mean that sensor wasn't also down during the 6 months prior to that! In order to confirm, you would need to expand your search radius to the point where the sensor was previously in another status.
Details of every setting modification done to an object (as listed on the History tab within the PRTG UI) can be retrieved using the GetModificationHistory method.
// Retrieve a list of all modifications ever performed on the object with ID 1050
var modifications = client.GetModificationHistory(1050);Each ModificationEvent object details the Object ID that was modified, the date the modification occurred, who did it, and what they did.
Historical information about events that have occurred on objects (sensors going up, down, notification triggers being sent, probes disconnecting, etc) can be retrieved with the Get-ObjectLog cmdlet. By default, PRTG only stores the last 30 days worth of logs
# Retrieve all logs from the root node
Get-ObjectLogWhen invoked without specifying an object, Get-ObjectLog will retrieve all logs from the root node. PRTG will always report that 1,000,000 logs are available, regardless of the true number. As such, when displaying progress Get-ObjectLog cannot accurately predict how long the command will take.
Get-ObjectLog attempts to be intelligent about the number of items to retrieve based on the specified parameters. When no date range or count is specified:
- When retrieving objects from a probe or the root node (group ID: 0)
Get-ObjectLogwill only retrieve logs from the start of today. - For all other object types (devices and sensors)
Get-ObjectLogwill default to retrieving results for the last 7 days.
# Retrieve logs for the sensor with ID 3024 for the past 7 days
C:\> Get-ObjectLog -Id 3024
DateTime Id Name Device Status Message
-------- -- ---- ------ ------ -------
4/11/2017 2:00:00 AM 1004 Memory dc-1 NotificationItem State Trigger activated (Sensor/Source/ID: 1004/0/1)
4/11/2017 1:58:31 AM 1004 Memory dc-1 Down 5 % (Percent Available Memory) is below the error limit of...
4/11/2017 1:48:27 AM 1004 Memory dc-1 Up 15 %
4/11/2017 1:46:44 AM 1004 Memory dc-1 PausedBySchedule Paused by schedule
...# Retrieve the last 5000 logs from the device named "dc-1"
Get-Device dc-1 | Get-ObjectLog -count 5000Get-ObjectLog allows specifying date ranges to retrieve logs from via the -StartDate and -EndDate parameters as well as the -Period parameter.
By specifying a -EndDate it is possible to limit results between now and a specified time.
# Get all logs from the last 3 days
Get-ObjectLog -EndDate (get-date).AddDays(-3)By specifying a -StartDate it is possible to limit results to from before a particular time. If an -EndDate is not used in conjunction with -StartDate and a -Count has not been specified, Get-ObjectLog will only retrieve logs between -StartDate and 7 days prior.
# Get all logs from yesterday and yesterday week
Get-ObjectLog -StartDate (get-date).AddDays(-1)The -Period parameter allows you to retrieve all logs between now and a predefined time period.
# Retrieve all logs from all probes whose name contains "contoso" for the last 30 days
Get-Probe *contoso* | Get-ObjectLog -Period LastMonthIf you wish to retrieve all logs ever, you can specify -Period All
# Retrieve all logs ever on all probes whose name contains "contoso"
Get-Probe *contoso* | Get-ObjectLog -Period AllLogs can be filtered to those containing certain status types using the -Status parameter.
# How long did that internet outage on the Contoso Head Office last for yesterday?
C:\> Get-Probe "Contoso (Head Office)" | Get-ObjectLog -Status Connected,Disconnected -Period Yesterday
DateTime Id Name Device Status Message
-------- -- ---- ------ ------ -------
4/11/2017 2:01:15 AM 2001 Contoso (Head Office) Connected Probe "Contoso (Head Office)" at...
4/11/2017 1:50:23 AM 2001 Contoso (Head Office) Disconnected Probe "Contoso (Head Office)" at...Logs can also be filtered by name, however note filtering by name is not supported server side. When you filter by name Get-ObjectLog will retrieve logs including those that do not match the specified name and then filter these for you before sending to the pipeline. As such, keep in mind that when filtering by name the -Count parameter will not work exactly as you intended. To attempt to meet your request, when an end date is not specified Get-ObjectLog will continuously attempt to retrieve additional records for you until it goes through all logs that exist in PRTG. To select a certain number of items within a smaller timeframe, you may want to consider using the Select-Object cmdlet instead.
# Try and retrieve 3 logs named "probe health" amongst all logs that exist in PRTG
Get-ObjectLog "probe health" -Count 3
# Retrieve the first 3 logs named "probe health" amongst only the logs that
# are returned in the default search period
Get-ObjectLog "probe health" | select -first 3Logs can be continuously monitored on an object by specifying the -Wait parameter. When -Wait is specified, Get-ObjectLog will continuously poll PRTG for new logs according to a specified -Interval (default: 1 second), returning logs in order from oldest to newest. A -StartDate can optionally be specified to show logs before the current date and time before Get-ObjectLog begins to wait for new records. Note that as -Wait causes logs to ordered from oldest to newest, the meaning of -StartDate is flipped to mean the point in time furthest away from now.
PrtgAPI always ensures the meaning of -StartDate and -EndDate mirror the direction with which results are displayed. This contrasts with the underlying PRTG API where the items you ask to "end" with end up being displayed "first". Please keep this in mind in the event you are debugging with the -Verbose parameter.
| Normal | Wait | PRTG API | |
|---|---|---|---|
| Output | Newest -> Oldest | Oldest -> Newest | Newest -> Oldest |
| StartDate | Closest to now | Furthest from now | Furthest from now |
| EndDate | Furthest from now | N/A | Closest to now |
While Get-ObjectLog does support the -Filter parameter, PRTG ignores most filter properties that are specified on log objects. For filtering on properties without native parameters (i.e. parameters that are explicitly defined on the cmdlet, such as -Status, -Name, etc) it is recommended to filter client side with Where-Object instead.
Historic channel values for a sensor can be retrieved using the Get-SensorHistory cmdlet
C:\> Get-Sensor -Tags wmicpu* -count 1 | Get-SensorHistory
DateTime SensorId Total(%) Processor1(%) Processor2(%) Coverage(%)
-------- -------- -------- ------------- ------------- -----------
17/10/2017 10:02:03 PM 2001 30 20 10 100
17/10/2017 10:01:03 PM 2001 40 26 14 100
17/10/2017 10:00:03 PM 2001 42 27 15 100
...By default, Get-SensorHistory will return records for the past 60 minutes averaged according to the normal scanning interval defined on the sensor. It is possible to average values together however (for example, viewing what the values were every 5 minutes) using the -Average parameter.
# Retrieve all historic channel records for the past hour, displaying the average
# value every 5 minutes
Get-Sensor -Tags wmicpu* -count 1 | Get-SensorHistory -Average 300Due to limitations of the PRTG API, channels that contain value lookups will only display their lookup names when an average of 0 is specified. However, PRTG will also only include Downtime information when an average is specified that is not 0. Get-SensorHistory handles this by providing an optional -Downtime parameter that can be specified. If -Downtime is specified Get-SensorHistory will use the Interval.TotalSeconds of the sensor. If -Downtime is omitted and an -Average is not specified, Get-SensorHistory will automatically use an average of 0
C:\> Get-Sensor -Tags wmicpu* -count 1 | Get-SensorHistory -Downtime
DateTime SensorId Total(%) Processor1(%) Processor2(%) Downtime(%) Coverage(%)
-------- -------- -------- ------------- ------------- ----------- -----------
17/10/2017 10:02:03 PM 2001 30 20 10 0 100
17/10/2017 10:01:03 PM 2001 40 26 14 0 100
17/10/2017 10:00:03 PM 2001 42 27 15 0 100
...The start and end times for the period to retrieve data for can be additionally modified using the -StartDate and -EndDate parameters respectively.
# Retrieve the sensor history of the sensor with ID 1001 from between now and 3am
# earlier this morning
# (PowerShell will coerce the string to a DateTime)
Get-Sensor -Id 1001 | Get-SensorHistory -End "3am"Records returned by GetSensorHistory are ordered newest to oldest. As such, -StartDate represents the closest time to now, while -EndDate represents the furthest point to retrieve to. If only an -EndDate is specified, logs will be retrieved between now and then.
PrtgAPI dynamically generates a table and list view for each sensor requested, for ease of display. Attempting to retrieve multiple historic records of different sensor types at once is not recommended, as PrtgAPI will be unable to display these records in a table together.
All channels displayed in Get-SensorHistory results contain their units displayed in brackets next to their column names. This is for display purposes only, and as such should be omitted if you wish to filter the results based on a channel
# Show all times over the past 3 hours when the Total CPU of a sensor was greater than 30
Get-Sensor -Tags wmicpu* -count 1 | Get-SensorHistory -EndDate (Get-Date).AddHours(-3) | where Total -gt 30Results returned by Get-SensorHistory can optionally be limited to a specified -Count. If a -Count is specified and an -EndDate is not specified, PrtgAPI will dynamically calculate the required end date needed to satisfy the channel's Interval or the specified -Average.
# Retrieve the last 3 results of the sensor with ID 2004
Get-Sensor -Id 2004 | Get-SensorHistory -Count 3Note: while Get-SensorHistory treats the -StartDate as closest to now and the -EndDate as the furthest from now, the PRTG API actually inverts this, with the "start date" of logs as the point in time furthest away from now, and the "end date" as the point in time closest to now. PrtgAPI flips the meaning of these values for consistency with other cmdlets within PrtgAPI (such as Get-ObjectLog). Keep this in mind in the event you specify -Verbose to Get-SensorHistory, as your start and end date values will actually be the other way around.
When you generate a historic data report in PRTG, at the bottom of these reports is a nifty table that shows the precise dates and times a given sensor alternated between various sensor states. These dates and times are absolute, and provide the same values regardless of the averaging value that is specified for the rest of the report. The information that is provided in this table is absolutely perfect for generating downtime reports, and PrtgAPI provides a means to retrieve this information via the -Report parameter to Get-SensorHistory
# Generate a sensor history report for the sensor with ID 1001 between now and this time yesterday
C:\> Get-SensorHistory -Id 1001 -Report
SensorId Status StartDate EndDate Duration
-------- ------ --------- ------- --------
2060 Unknown 8/05/2020 12:38:46 AM 8/05/2020 12:39:08 AM 00:00:22
2060 Down 8/05/2020 12:39:08 AM 9/05/2020 12:38:23 AM 23:59:15Like when using Get-SensorHistory normally, by default if no -StartDate and -EndDate are specified, Get-SensorHistory -Report will retrieve data from between now and 24 hours ago. Get-SensorHistory -Report returns a collection of SensorHistoryReportItem objects, each of which describes a particular incidence of a sensor changing from one state to another.
# Calculate the total downtime of the sensor with ID 1001 over the past 6 months
[TimeSpan]::FromSeconds(((Get-Sensor -Id 1001 | Get-SensorHistory -Report -EndDate (Get-Date).AddMonths(-6) | where Status -eq Down).Duration | Measure-Object -Sum TotalSeconds).Sum)When analyzing sensor history report results, it is important to note that the StartDate and EndDate values that are provided on each individual SensorHistoryReportItem are limited to being within the -StartDate and -EndDate that were originally specified to Get-SensorHistory -Report. As such, the first and last items of any report will likely extend their start and end dates outside the originally requested range. This is important to consider when analyzing downtime: if you only request a report for the last 30 days, and you can see a sensor was down for the first 15 of those 30 days, that doesn't mean that sensor wasn't also down during the 6 months prior to that! In order to confirm, you would need to expand your search radius to the point where the sensor was previously in another status.
Details of every setting modification done to an object (as listed on the History tab within the PRTG UI) can be retrieved using the Get-ModificationHistory cmdlet.
ObjectId DateTime UserName Message
-------- -------- -------- -------
2001 26/03/2017 3:40:20 PM PRTG System Administrator Created. 17.3.33.2830
2001 26/03/2017 3:55:33 PM PRTG System Administrator Edited.
2001 26/03/2017 3:55:33 PM PRTG System Administrator Subnode Edited. Channel ID: 0 limitmaxerror:90 limitmode:1