< Back
Get-SensorHistory
Post
NAME Get-SensorHistory
SYNOPSIS
Retrieves historic data values for a PRTG Sensor.
SYNTAX
Get-SensorHistory -Sensor <Sensor> [-Average <int>] [-Count <int>] [-Downtime <SwitchParameter>] [-EndDate
<DateTime>] [-Raw <SwitchParameter>] [-StartDate <DateTime>] [<CommonParameters>]
Get-SensorHistory -Id <int> [-Average <int>] [-Count <int>] [-EndDate <DateTime>] [-Raw <SwitchParameter>]
[-StartDate <DateTime>] [<CommonParameters>]
DESCRIPTION
The Get-SensorHistory cmdlet retrieves historic data values for all channels of a PRTG Sensor within a specified
time period. By default, values are returned according to the scanning interval defined on the sensor (e.g. values
every 60 seconds). Using the -Average parameter, values can be averaged together to provide a higher level view of
a larger time span. Any number of seconds can be specified as the Average, however note that depending on the
interval of the sensor, certain time spans may result in blank values within the sensor results.
Historic data values can be retrieved over any time period via the -StartDate and -EndDate parameters. If these
values are not specified, records will be returned from between now and 60 minutes ago. If PRTG finds it does not
have enough monitoring data to return for the specified time span, an exception will be thrown. To work around
this, you can request date for a larger time frame and then potentially filter the data with the Where-Object and
Select-Object cmdlets.
When an -EndDate is specified, Get-SensorHistory will split the sensor history query into a series of smaller
requests, emitting results to the pipeline as they arrive. If the -Count parameter is speciifed, and -EndDate is
not specified, Get-SensorHistory will automatically adjust the -EndDate such that the specified number of records
can be retrieved, based on the sensor's Interval or the specified -Average. If an -EndDate has been specified, the
number of records returned may be limited by the number of records available in the specified time period.
Due to limitations of the PRTG API, Get-SensorHistory cannot display both downtime and channel value lookups at
the same time. Value lookups can only be displayed when an -Average of 0 is specified, while downtime can only be
displayed when a specific average has been specified. By default, if no average is specified Get-SensorHistory
will use an average of 0 to enable the display of value lookups. If the -Downtime parameter is specified and no
-Average is specified, Get-SensorHistory will use the Interval property of the sensor to specify the true average.
PrtgAPI will automatically display all numeric channel values as numbers, with the unit of the channel displayed
in brackets next to the channel header (e.g. "Total(%)"). These units are for display purposes only, and so can be
ignored when attempting to extract certain columns from the sensor history result. If the -Raw parameter is
specified Get-SensorHistory will ignore the units of each channel and instead display all values in their raw
format (e.g. Bytes for a unit stored in MegaBytes).
Note that while Get-SensorHistory considers the "start time" as being the point in time closest to now and the
"end time" as the point in time furthest away from now, PRTG's underlying API actually defines these in the
opposite way. Since records are ordered from newest to oldest however, PrtgAPI flips these definitions as to
prevent any confusion. Keep this in mind in the event the -Verbose parameter is specified, as the start and end
times will appear to be switched.
PARAMETERS
-Sensor <Sensor>
Sensor to retrieve historic data for.
Required? true
Position? named
Default value
Accept pipeline input? true (ByValue)
Accept wildcard characters? false
-Id <int>
ID of the sensor to retrieve historic data for.
Required? true
Position? named
Default value 0
Accept pipeline input? false
Accept wildcard characters? false
-StartDate <DateTime>
Start time to retrieve history from. If no value is specified, defaults to 24 hours ago.
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-EndDate <DateTime>
End time to retrieve history to. If no value is specified, defaults to the current date and time.
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-Average <int>
Time span (in seconds) to average results over. For example, a value of 300 will show the average value every
5 minutes. If a value of 0 is used, PRTG will include value lookup labels in historical results. If a value
other than 0 is used, PRTG will include the Downtime channel in results.
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-Downtime <SwitchParameter>
Specifies that the Downtime channel should be included in query results in lieu of value lookup labels. If
this parameter is specified and Average is not specified, the Interval of the sensor will be used to determine
the average.
Required? false
Position? named
Default value False
Accept pipeline input? false
Accept wildcard characters? false
-Raw <SwitchParameter>
Specifies that the raw numeric values for each channel should be displayed using the base unit of the channel.
Required? false
Position? named
Default value False
Accept pipeline input? false
Accept wildcard characters? false
-Count <int>
Limits results to the specified number of items within the specified time period.
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
<CommonParameters>
This cmdlet supports the common parameters: Verbose, Debug,
ErrorAction, ErrorVariable, WarningAction, WarningVariable,
OutBuffer, PipelineVariable, and OutVariable. For more information, see
about_CommonParameters (https:/go.microsoft.com/fwlink/?LinkID=113216).
INPUTS
PrtgAPI.Sensor
Sensor to retrieve historic data for.
OUTPUTS
---------- EXAMPLE 1 ----------
C:\\> Get-Sensor -Id 1001 | Get-SensorHistory
Get historical values for all channels on the sensor with ID 1001 over the past 24 hours, using the sensor's
default interval.
---------- EXAMPLE 2 ----------
C:\\> Get-Sensor -Id 1001 | Get-SensorHistory -Average 300
Get historical values for all channels on the sensor with ID 1001 over the past 24 hours, averaging values in 5
minute intervals.
---------- EXAMPLE 3 ----------
C:\\> Get-Sensor -Id 1001 | Get-SensorHistory -StartDate (Get-Date).AddDays(-1) -EndDate (Get-Date).AddDays(-3)
Get historical values for all channels on the sensor with ID 1001 starting three days ago and ending yesterday.
---------- EXAMPLE 4 ----------
C:\\> Get-Sensor -Tags wmicpu* -count 1 | Get-SensorHistory | select Total
Get historical values for all channels on a single WMI CPU Load sensor, selecting the "Total" channel (visually
displayed as "Total(%)"
---------- EXAMPLE 5 ----------
C:\\> Get-Sensor -Tags wmicpu* -count 1 | where Total -gt 90
Get historical values for all channels on a single WMI CPU Load sensor where the Total channel's value was greater
than 90.
RELATED LINKS
Online version: https://github.com/lordmilko/PrtgAPI/wi ... -history-1
Get-Sensor
Select-Object
Where-Object
SYNOPSIS
Retrieves historic data values for a PRTG Sensor.
SYNTAX
Get-SensorHistory -Sensor <Sensor> [-Average <int>] [-Count <int>] [-Downtime <SwitchParameter>] [-EndDate
<DateTime>] [-Raw <SwitchParameter>] [-StartDate <DateTime>] [<CommonParameters>]
Get-SensorHistory -Id <int> [-Average <int>] [-Count <int>] [-EndDate <DateTime>] [-Raw <SwitchParameter>]
[-StartDate <DateTime>] [<CommonParameters>]
DESCRIPTION
The Get-SensorHistory cmdlet retrieves historic data values for all channels of a PRTG Sensor within a specified
time period. By default, values are returned according to the scanning interval defined on the sensor (e.g. values
every 60 seconds). Using the -Average parameter, values can be averaged together to provide a higher level view of
a larger time span. Any number of seconds can be specified as the Average, however note that depending on the
interval of the sensor, certain time spans may result in blank values within the sensor results.
Historic data values can be retrieved over any time period via the -StartDate and -EndDate parameters. If these
values are not specified, records will be returned from between now and 60 minutes ago. If PRTG finds it does not
have enough monitoring data to return for the specified time span, an exception will be thrown. To work around
this, you can request date for a larger time frame and then potentially filter the data with the Where-Object and
Select-Object cmdlets.
When an -EndDate is specified, Get-SensorHistory will split the sensor history query into a series of smaller
requests, emitting results to the pipeline as they arrive. If the -Count parameter is speciifed, and -EndDate is
not specified, Get-SensorHistory will automatically adjust the -EndDate such that the specified number of records
can be retrieved, based on the sensor's Interval or the specified -Average. If an -EndDate has been specified, the
number of records returned may be limited by the number of records available in the specified time period.
Due to limitations of the PRTG API, Get-SensorHistory cannot display both downtime and channel value lookups at
the same time. Value lookups can only be displayed when an -Average of 0 is specified, while downtime can only be
displayed when a specific average has been specified. By default, if no average is specified Get-SensorHistory
will use an average of 0 to enable the display of value lookups. If the -Downtime parameter is specified and no
-Average is specified, Get-SensorHistory will use the Interval property of the sensor to specify the true average.
PrtgAPI will automatically display all numeric channel values as numbers, with the unit of the channel displayed
in brackets next to the channel header (e.g. "Total(%)"). These units are for display purposes only, and so can be
ignored when attempting to extract certain columns from the sensor history result. If the -Raw parameter is
specified Get-SensorHistory will ignore the units of each channel and instead display all values in their raw
format (e.g. Bytes for a unit stored in MegaBytes).
Note that while Get-SensorHistory considers the "start time" as being the point in time closest to now and the
"end time" as the point in time furthest away from now, PRTG's underlying API actually defines these in the
opposite way. Since records are ordered from newest to oldest however, PrtgAPI flips these definitions as to
prevent any confusion. Keep this in mind in the event the -Verbose parameter is specified, as the start and end
times will appear to be switched.
PARAMETERS
-Sensor <Sensor>
Sensor to retrieve historic data for.
Required? true
Position? named
Default value
Accept pipeline input? true (ByValue)
Accept wildcard characters? false
-Id <int>
ID of the sensor to retrieve historic data for.
Required? true
Position? named
Default value 0
Accept pipeline input? false
Accept wildcard characters? false
-StartDate <DateTime>
Start time to retrieve history from. If no value is specified, defaults to 24 hours ago.
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-EndDate <DateTime>
End time to retrieve history to. If no value is specified, defaults to the current date and time.
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-Average <int>
Time span (in seconds) to average results over. For example, a value of 300 will show the average value every
5 minutes. If a value of 0 is used, PRTG will include value lookup labels in historical results. If a value
other than 0 is used, PRTG will include the Downtime channel in results.
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-Downtime <SwitchParameter>
Specifies that the Downtime channel should be included in query results in lieu of value lookup labels. If
this parameter is specified and Average is not specified, the Interval of the sensor will be used to determine
the average.
Required? false
Position? named
Default value False
Accept pipeline input? false
Accept wildcard characters? false
-Raw <SwitchParameter>
Specifies that the raw numeric values for each channel should be displayed using the base unit of the channel.
Required? false
Position? named
Default value False
Accept pipeline input? false
Accept wildcard characters? false
-Count <int>
Limits results to the specified number of items within the specified time period.
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
<CommonParameters>
This cmdlet supports the common parameters: Verbose, Debug,
ErrorAction, ErrorVariable, WarningAction, WarningVariable,
OutBuffer, PipelineVariable, and OutVariable. For more information, see
about_CommonParameters (https:/go.microsoft.com/fwlink/?LinkID=113216).
INPUTS
PrtgAPI.Sensor
Sensor to retrieve historic data for.
OUTPUTS
---------- EXAMPLE 1 ----------
C:\\> Get-Sensor -Id 1001 | Get-SensorHistory
Get historical values for all channels on the sensor with ID 1001 over the past 24 hours, using the sensor's
default interval.
---------- EXAMPLE 2 ----------
C:\\> Get-Sensor -Id 1001 | Get-SensorHistory -Average 300
Get historical values for all channels on the sensor with ID 1001 over the past 24 hours, averaging values in 5
minute intervals.
---------- EXAMPLE 3 ----------
C:\\> Get-Sensor -Id 1001 | Get-SensorHistory -StartDate (Get-Date).AddDays(-1) -EndDate (Get-Date).AddDays(-3)
Get historical values for all channels on the sensor with ID 1001 starting three days ago and ending yesterday.
---------- EXAMPLE 4 ----------
C:\\> Get-Sensor -Tags wmicpu* -count 1 | Get-SensorHistory | select Total
Get historical values for all channels on a single WMI CPU Load sensor, selecting the "Total" channel (visually
displayed as "Total(%)"
---------- EXAMPLE 5 ----------
C:\\> Get-Sensor -Tags wmicpu* -count 1 | where Total -gt 90
Get historical values for all channels on a single WMI CPU Load sensor where the Total channel's value was greater
than 90.
RELATED LINKS
Online version: https://github.com/lordmilko/PrtgAPI/wi ... -history-1
Get-Sensor
Select-Object
Where-Object