< Back
New-SensorFactoryDefinition
Post
NAME New-SensorFactoryDefinition
SYNOPSIS
Creates a channel definition for use in a PRTG Sensor Factory.
SYNTAX
New-SensorFactoryDefinition [-Name] <NameOrScriptBlock> [[-ChannelId] <int>] -Sensor <Sensor> [-Expression
<ScriptBlock>] [-StartId <int>] [<CommonParameters>]
New-SensorFactoryDefinition [-Name] <NameOrScriptBlock> [[-ChannelId] <int>] -Aggregator <EnumOrScriptBlock`1>
-Sensor <Sensor> [-Expression <ScriptBlock>] [-Finalizer <ScriptBlock>] [-StartId <int>] [<CommonParameters>]
New-SensorFactoryDefinition [-Name] <NameOrScriptBlock> [[-ChannelId] <int>] -Sensor <Sensor> -SummaryExpression
<EnumOrScriptBlock`1> -SummaryName <string> [-Expression <ScriptBlock>] [-StartId <int>] [-SummaryFinalizer
<ScriptBlock>] [<CommonParameters>]
New-SensorFactoryDefinition [-Name] <NameOrScriptBlock> -Value <string> [-StartId <int>] [<CommonParameters>]
DESCRIPTION
The New-SensorFactoryDefinition cmdlet automatically defines a series of channel defitions for use in a Sensor
Factory sensor.
New-SensorFactoryDefinition can be used to create both individual channel definitions for a collection of sensors,
as well as aggregation channels, using a complex formula that operates on all of the sensors in a set. As a
shorthand, you can access the New-SensorFactoryDefinition cmdlet via the alias 'fdef'.
When specifying an Expression, the default expression and current sensor can be accessed via the $expr and $_
automatic variables. Unless you wish to modify the sensor ID or channel ID to be used for a specific sensor, it is
generally recommended to avoid recalculating the base channel definition and use the automatic $expr variable,
which is defined as "channel(sensorId, channelID)" where sensorID is the ID of the current sensor, and channelID
is the value passed to -ChannelId. If a -ChannelId is not specified, channel ID 0 will automatically be used.
Aggregation channels, representing values derived from multiple sensor channels, can be created using the
-Aggregator and -SummaryExpression parameters. When -Aggregator is specified, New-SensorFactoryDefinition creates
a single channel based on all of the channels piped in to the -Sensor parameter. By contrast, the
-SummaryExpression parameter creates an aggregated summary channel _in addition to_ channels for each individual
sensor. Both -Aggregator and -SummaryExpression allow specifying well known summarization formulae (including Sum,
Min, Max, Average, etc) as well as a custom ScriptBlock where a custom expression is required.
When specifying an -Aggregator or custom -SummaryExpression, the running accumulator, default expression and
current sensor can be accessed via the $acc, $expr and $_ automatic variables respectively. Based on whether not
the -Expression parameter is specified, $expr will either contain the custom or the default expression.
In the event your aggregation formula requires a "post-processing" step (such as dividing by the total number of
items when calculating an average), this can be performed via the -Finalizer and -SummaryFinalizer parameters
(when creating a regular -Aggregator or -SummaryExpression respectively.
While it is possible to override the expression evaluated in $expr in the -Aggregator or -SummaryExpression by
recalculating the channel definition (via the $_ automatic variable), if the channel ID specified in the new
definition is different from the channel ID specified in the -ChannelId parameter, the first channel definition in
the resulting output will have a different channel ID than all the rest. This is due to the fact when the
Aggregator runs, it initially sets the accumulator ($acc) to the expression of the first sensor. As such, if in
the -Aggregator you change the channel ID, you will also need to replace the channel ID of the initial value in
the accumulator. Due to the complexity involved in managing this, it is recommended to avoid modifying the channel
ID in the aggregator, and either set the channel ID in an -Expression or in the -ChannelId.
All parameters that accept ScriptBlock values including -Expression and -Aggregator and -SummaryExpression support
the use of Sensor Factory formula functions (channel(), min(), max(), avg() and percent()), as well as all boolean
and math operators. For more information, see the Sensor Factory documentation in the PRTG Manual.
Horizontal lines can be generated by specifying the position the line should appear at to the -Value parameter.
When specifying a horizontal line the channel unit the line should apply to should be specified in square brackets
at the end of the channel name. It does not matter what the ID of any horizontal lines are, as long as they do not
conflict with any other channel definitions.
To automatically copy the output of New-SensorFactoryDefinition to the clipboard, you can pipe the cmdlet to
clip.exe.
PARAMETERS
-Sensor <Sensor>
The sensor to create a channel definition for.
Required? true
Position? named
Default value
Accept pipeline input? true (ByValue)
Accept wildcard characters? false
-Name <NameOrScriptBlock>
An string or an expression that resolves the name to use for a channel definition.
Required? true
Position? 0
Default value
Accept pipeline input? false
Accept wildcard characters? false
-ChannelName <NameOrScriptBlock>
An string or an expression that resolves the name to use for a channel definition.
This is an alias of the Name parameter.
Required? true
Position? 0
Default value
Accept pipeline input? false
Accept wildcard characters? false
-ChannelId <int>
The channel ID to use. If a custom expression is provided, this value can be optionally overridden. If this
value is not specified, Channel 0 will automatically be used.
Required? false
Position? 1
Default value 0
Accept pipeline input? false
Accept wildcard characters? false
-Expression <ScriptBlock>
A custom expression to use for defining a channel definition.
Provides the following automatic variables
'$expr' (for the default expression)
'$_' (for the current sensor)
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-StartId <int>
The starting channel ID to use for each channel definition. The default value is 1.
Required? false
Position? named
Default value 1
Accept pipeline input? false
Accept wildcard characters? false
-Aggregator <EnumOrScriptBlock`1>
An aggregator to use for creating a single aggregation channel.
Provides the fllowing automatic variables:
'$acc' (the running accumulator)
'$expr' (for the default expression)
'$_' (the current sensor
Required? true
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-Finalizer <ScriptBlock>
A post-processing action to perform on an aggregated expresion before emititing to the pipeline. If
-Aggregator is not specified this parameter does nothing. If this parameter is specified but -Aggregator is
not a ScriptBlock, an exception will be thrown.
Provides the following automatic variables:
'$acc' (the accumulated result)
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-Value <string>
A static value to use for the channel value in place of an -Expression.
Required? true
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-SummaryName <string>
Name to use for the summary channel.
Required? true
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-sn <string>
Name to use for the summary channel.
This is an alias of the SummaryName parameter.
Required? true
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-SummaryExpression <EnumOrScriptBlock`1>
Expression to use for the summary channel. May be a well known enum value or a custom ScriptBlock expression.
Functions identically to -Aggregator.
Required? true
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-se <EnumOrScriptBlock`1>
Expression to use for the summary channel. May be a well known enum value or a custom ScriptBlock expression.
Functions identically to -Aggregator.
This is an alias of the SummaryExpression parameter.
Required? true
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-sa <EnumOrScriptBlock`1>
Expression to use for the summary channel. May be a well known enum value or a custom ScriptBlock expression.
Functions identically to -Aggregator.
This is an alias of the SummaryExpression parameter.
Required? true
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-SummaryAggregator <EnumOrScriptBlock`1>
Expression to use for the summary channel. May be a well known enum value or a custom ScriptBlock expression.
Functions identically to -Aggregator.
This is an alias of the SummaryExpression parameter.
Required? true
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-SummaryFinalizer <ScriptBlock>
A post-processing action to perform against -SummaryExpression when a custom ScriptBlock is specified. If
-SummaryExpression is not a custom expression, an exception will be thrown. Functions identically to
-Finalizer.
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-sf <ScriptBlock>
A post-processing action to perform against -SummaryExpression when a custom ScriptBlock is specified. If
-SummaryExpression is not a custom expression, an exception will be thrown. Functions identically to
-Finalizer.
This is an alias of the SummaryFinalizer parameter.
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
The sensor to create a channel definition for.
OUTPUTS
---------- EXAMPLE 1 ----------
C:\\> Get-Sensor -Tags wmicpuloadsensor | fdef { $_.Device }
Create a channel definition for the "Total" channel (ID: 0) of each WMI CPU Load sensor in the system
---------- EXAMPLE 2 ----------
C:\\> Get-Sensor -Tags wmicpuloadsensor | fdef { $_.Device } 1
Create a channel definition for the "Processor 1" channel (ID: 1) of each WMI CPU Load sensor in the system
---------- EXAMPLE 3 ----------
C:\\> Get-Sensor -Tags wmimemorysensor | fdef { $_.Device } -Expr { "100 - $expr" } 0
Create a channel definition for the "Percent Available Memory" channel (ID: 0) of each WMI Memory Free sensor,
modifying each channel to show the percent of memory "used" instead of free
---------- EXAMPLE 4 ----------
C:\\> Get-Sensor -Tags wmicpu* | fdef { $_.Device } -sn "Max CPU Load" -se Max
Create a channel definition showing the highest CPU Load of all devices as well as channel definitions for each
individual device in a single command
---------- EXAMPLE 5 ----------
C:\\> $sensors = Get-Sensor -Tags wmicpu*
C:\\> $sensors | fdef { $_.Device } -sn "Average CPU Load" -se { "$acc + $expr" } -sf { "$acc / $($sensors.Count)" }
Create a channel definition showing the average CPU Load of all devices as well as channel definitions for each
individual device using a summary expression and finalizer formula
---------- EXAMPLE 6 ----------
C:\\> $sensors = Get-Sensor -Tags wmicpuloadsensor
C:\\> $sensors | fdef "Max CPU Load" -Aggregator { "max($expr,$acc)" }
C:\\> $sensors | fdef { $_.Device } -StartId 2
Create two separate channel definitions showing the highest CPU Load of all devices as well as channel definitions
for each individual device
---------- EXAMPLE 7 ----------
C:\\> Get-Sensor -Tags wmicpuloadsensor | fdef { "$($_.Device) [bananas]" } 0
Create a channel definition for the "Total" channel (ID: 0) displaying all channels with the custom unit "bananas"
---------- EXAMPLE 8 ----------
C:\\> fdef "Line at 40.2 [msec]" -Value 40.2 -StartId 3
Create a channel definition for a horizontal line against channels that use the "msec" unit using a channel ID of
3.
RELATED LINKS
Online version: https://github.com/lordmilko/PrtgAPI/wi ... efinitions
Get-Sensor
Get-Channel
https://www.paessler.com/manuals/prtg/s ... ory_sensor
SYNOPSIS
Creates a channel definition for use in a PRTG Sensor Factory.
SYNTAX
New-SensorFactoryDefinition [-Name] <NameOrScriptBlock> [[-ChannelId] <int>] -Sensor <Sensor> [-Expression
<ScriptBlock>] [-StartId <int>] [<CommonParameters>]
New-SensorFactoryDefinition [-Name] <NameOrScriptBlock> [[-ChannelId] <int>] -Aggregator <EnumOrScriptBlock`1>
-Sensor <Sensor> [-Expression <ScriptBlock>] [-Finalizer <ScriptBlock>] [-StartId <int>] [<CommonParameters>]
New-SensorFactoryDefinition [-Name] <NameOrScriptBlock> [[-ChannelId] <int>] -Sensor <Sensor> -SummaryExpression
<EnumOrScriptBlock`1> -SummaryName <string> [-Expression <ScriptBlock>] [-StartId <int>] [-SummaryFinalizer
<ScriptBlock>] [<CommonParameters>]
New-SensorFactoryDefinition [-Name] <NameOrScriptBlock> -Value <string> [-StartId <int>] [<CommonParameters>]
DESCRIPTION
The New-SensorFactoryDefinition cmdlet automatically defines a series of channel defitions for use in a Sensor
Factory sensor.
New-SensorFactoryDefinition can be used to create both individual channel definitions for a collection of sensors,
as well as aggregation channels, using a complex formula that operates on all of the sensors in a set. As a
shorthand, you can access the New-SensorFactoryDefinition cmdlet via the alias 'fdef'.
When specifying an Expression, the default expression and current sensor can be accessed via the $expr and $_
automatic variables. Unless you wish to modify the sensor ID or channel ID to be used for a specific sensor, it is
generally recommended to avoid recalculating the base channel definition and use the automatic $expr variable,
which is defined as "channel(sensorId, channelID)" where sensorID is the ID of the current sensor, and channelID
is the value passed to -ChannelId. If a -ChannelId is not specified, channel ID 0 will automatically be used.
Aggregation channels, representing values derived from multiple sensor channels, can be created using the
-Aggregator and -SummaryExpression parameters. When -Aggregator is specified, New-SensorFactoryDefinition creates
a single channel based on all of the channels piped in to the -Sensor parameter. By contrast, the
-SummaryExpression parameter creates an aggregated summary channel _in addition to_ channels for each individual
sensor. Both -Aggregator and -SummaryExpression allow specifying well known summarization formulae (including Sum,
Min, Max, Average, etc) as well as a custom ScriptBlock where a custom expression is required.
When specifying an -Aggregator or custom -SummaryExpression, the running accumulator, default expression and
current sensor can be accessed via the $acc, $expr and $_ automatic variables respectively. Based on whether not
the -Expression parameter is specified, $expr will either contain the custom or the default expression.
In the event your aggregation formula requires a "post-processing" step (such as dividing by the total number of
items when calculating an average), this can be performed via the -Finalizer and -SummaryFinalizer parameters
(when creating a regular -Aggregator or -SummaryExpression respectively.
While it is possible to override the expression evaluated in $expr in the -Aggregator or -SummaryExpression by
recalculating the channel definition (via the $_ automatic variable), if the channel ID specified in the new
definition is different from the channel ID specified in the -ChannelId parameter, the first channel definition in
the resulting output will have a different channel ID than all the rest. This is due to the fact when the
Aggregator runs, it initially sets the accumulator ($acc) to the expression of the first sensor. As such, if in
the -Aggregator you change the channel ID, you will also need to replace the channel ID of the initial value in
the accumulator. Due to the complexity involved in managing this, it is recommended to avoid modifying the channel
ID in the aggregator, and either set the channel ID in an -Expression or in the -ChannelId.
All parameters that accept ScriptBlock values including -Expression and -Aggregator and -SummaryExpression support
the use of Sensor Factory formula functions (channel(), min(), max(), avg() and percent()), as well as all boolean
and math operators. For more information, see the Sensor Factory documentation in the PRTG Manual.
Horizontal lines can be generated by specifying the position the line should appear at to the -Value parameter.
When specifying a horizontal line the channel unit the line should apply to should be specified in square brackets
at the end of the channel name. It does not matter what the ID of any horizontal lines are, as long as they do not
conflict with any other channel definitions.
To automatically copy the output of New-SensorFactoryDefinition to the clipboard, you can pipe the cmdlet to
clip.exe.
PARAMETERS
-Sensor <Sensor>
The sensor to create a channel definition for.
Required? true
Position? named
Default value
Accept pipeline input? true (ByValue)
Accept wildcard characters? false
-Name <NameOrScriptBlock>
An string or an expression that resolves the name to use for a channel definition.
Required? true
Position? 0
Default value
Accept pipeline input? false
Accept wildcard characters? false
-ChannelName <NameOrScriptBlock>
An string or an expression that resolves the name to use for a channel definition.
This is an alias of the Name parameter.
Required? true
Position? 0
Default value
Accept pipeline input? false
Accept wildcard characters? false
-ChannelId <int>
The channel ID to use. If a custom expression is provided, this value can be optionally overridden. If this
value is not specified, Channel 0 will automatically be used.
Required? false
Position? 1
Default value 0
Accept pipeline input? false
Accept wildcard characters? false
-Expression <ScriptBlock>
A custom expression to use for defining a channel definition.
Provides the following automatic variables
'$expr' (for the default expression)
'$_' (for the current sensor)
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-StartId <int>
The starting channel ID to use for each channel definition. The default value is 1.
Required? false
Position? named
Default value 1
Accept pipeline input? false
Accept wildcard characters? false
-Aggregator <EnumOrScriptBlock`1>
An aggregator to use for creating a single aggregation channel.
Provides the fllowing automatic variables:
'$acc' (the running accumulator)
'$expr' (for the default expression)
'$_' (the current sensor
Required? true
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-Finalizer <ScriptBlock>
A post-processing action to perform on an aggregated expresion before emititing to the pipeline. If
-Aggregator is not specified this parameter does nothing. If this parameter is specified but -Aggregator is
not a ScriptBlock, an exception will be thrown.
Provides the following automatic variables:
'$acc' (the accumulated result)
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-Value <string>
A static value to use for the channel value in place of an -Expression.
Required? true
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-SummaryName <string>
Name to use for the summary channel.
Required? true
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-sn <string>
Name to use for the summary channel.
This is an alias of the SummaryName parameter.
Required? true
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-SummaryExpression <EnumOrScriptBlock`1>
Expression to use for the summary channel. May be a well known enum value or a custom ScriptBlock expression.
Functions identically to -Aggregator.
Required? true
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-se <EnumOrScriptBlock`1>
Expression to use for the summary channel. May be a well known enum value or a custom ScriptBlock expression.
Functions identically to -Aggregator.
This is an alias of the SummaryExpression parameter.
Required? true
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-sa <EnumOrScriptBlock`1>
Expression to use for the summary channel. May be a well known enum value or a custom ScriptBlock expression.
Functions identically to -Aggregator.
This is an alias of the SummaryExpression parameter.
Required? true
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-SummaryAggregator <EnumOrScriptBlock`1>
Expression to use for the summary channel. May be a well known enum value or a custom ScriptBlock expression.
Functions identically to -Aggregator.
This is an alias of the SummaryExpression parameter.
Required? true
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-SummaryFinalizer <ScriptBlock>
A post-processing action to perform against -SummaryExpression when a custom ScriptBlock is specified. If
-SummaryExpression is not a custom expression, an exception will be thrown. Functions identically to
-Finalizer.
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-sf <ScriptBlock>
A post-processing action to perform against -SummaryExpression when a custom ScriptBlock is specified. If
-SummaryExpression is not a custom expression, an exception will be thrown. Functions identically to
-Finalizer.
This is an alias of the SummaryFinalizer parameter.
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
The sensor to create a channel definition for.
OUTPUTS
---------- EXAMPLE 1 ----------
C:\\> Get-Sensor -Tags wmicpuloadsensor | fdef { $_.Device }
Create a channel definition for the "Total" channel (ID: 0) of each WMI CPU Load sensor in the system
---------- EXAMPLE 2 ----------
C:\\> Get-Sensor -Tags wmicpuloadsensor | fdef { $_.Device } 1
Create a channel definition for the "Processor 1" channel (ID: 1) of each WMI CPU Load sensor in the system
---------- EXAMPLE 3 ----------
C:\\> Get-Sensor -Tags wmimemorysensor | fdef { $_.Device } -Expr { "100 - $expr" } 0
Create a channel definition for the "Percent Available Memory" channel (ID: 0) of each WMI Memory Free sensor,
modifying each channel to show the percent of memory "used" instead of free
---------- EXAMPLE 4 ----------
C:\\> Get-Sensor -Tags wmicpu* | fdef { $_.Device } -sn "Max CPU Load" -se Max
Create a channel definition showing the highest CPU Load of all devices as well as channel definitions for each
individual device in a single command
---------- EXAMPLE 5 ----------
C:\\> $sensors = Get-Sensor -Tags wmicpu*
C:\\> $sensors | fdef { $_.Device } -sn "Average CPU Load" -se { "$acc + $expr" } -sf { "$acc / $($sensors.Count)" }
Create a channel definition showing the average CPU Load of all devices as well as channel definitions for each
individual device using a summary expression and finalizer formula
---------- EXAMPLE 6 ----------
C:\\> $sensors = Get-Sensor -Tags wmicpuloadsensor
C:\\> $sensors | fdef "Max CPU Load" -Aggregator { "max($expr,$acc)" }
C:\\> $sensors | fdef { $_.Device } -StartId 2
Create two separate channel definitions showing the highest CPU Load of all devices as well as channel definitions
for each individual device
---------- EXAMPLE 7 ----------
C:\\> Get-Sensor -Tags wmicpuloadsensor | fdef { "$($_.Device) [bananas]" } 0
Create a channel definition for the "Total" channel (ID: 0) displaying all channels with the custom unit "bananas"
---------- EXAMPLE 8 ----------
C:\\> fdef "Line at 40.2 [msec]" -Value 40.2 -StartId 3
Create a channel definition for a horizontal line against channels that use the "msec" unit using a channel ID of
3.
RELATED LINKS
Online version: https://github.com/lordmilko/PrtgAPI/wi ... efinitions
Get-Sensor
Get-Channel
https://www.paessler.com/manuals/prtg/s ... ory_sensor