Skip to content

Custom sensor method

General

The custom sensor method lets the Rimscout client execute a provided PowerShell script in the user's context. The script can run once or multiple times per minute to measure or retrieve performance metrics.

When to use

A custom sensor test is useful in case metrics can't be measured using standard network protocols (which are covered by the other test methods). Typical use cases include:

  • Using non-implemented network protocols like SMB.
  • Retrieving system metrics, such as the network usage of a specific application.
  • Connecting to a site that requires authentication.

The script is limited to commands that don't require admin rights and must execute within a minute. Read the notes below carefully before creating a custom sensor test!

Important notes

  • By configuring a custom sensor test, you accept full responsibility for the PowerShell script and its effects. Net at Work is not liable for any resulting issues.
  • Scripts are encrypted for secure transfer from portal to client and can't be modified locally.
  • The custom sensor feature is disabled by default for tenants. Contact support@rimscout.com to enable it.
  • Control who can create and edit PowerShell scripts via the Custom sensor role in Access control. Existing tests can be assigned to test sets by anyone with access to Configuration.
  • Don't execute commands requiring admin rights; they will prompt the user every minute and fail anyway.
  • Scripts shouldn't change user configurations unless necessary for measurement.

Parameters

Measurement unit (optional)

The unit name of the value returned by the script, used when results are displayed on the test results chart.

PowerShell script

It can be written, copied, or imported into the text area and edited there. The script must:

  • Not take input parameters.
  • Run within a minute; otherwise, it will be interrupted and result in an error.
  • Return a single integer. A decimal number will result in an error.
  • It may throw exceptions, with messages viewable on the test result chart.
  • Not execute commands needing admin rights. There is no validation to prevent this.

Find examples below.

Number of measurements

The number of script executions within a minute. If a script run takes too long, actual executions may be fewer than specified.

Allowed inputs: 1 - 58

Example: 1

Warning threshold

Defines the value beyond which a measurement gets a warning status.

Allowed input: 1 - 1.000 and has to be less than the critical threshold.

Critical threshold

Defines the value beyond which a measurement gets a critical status.

Allowed input: 1 - 1.000 and has to be greater than the warning threshold.

Percentage

See Percentage.

Allowed input: 1 - 100%.

Limitations and recommondations

  • The custom sensor uses PowerShell version 7.5, but not all libraries are included. Some commands might not work due to missing modules. Contact support@rimscout.com if issues arise.

Example scripts

SMB test

# This is an example script that measures the time to read a directory on a file share.
# The script returns the measured milliseconds by writing it as only value to stdout
# For a more refined version visit: https://www.msxfaq.de/windows/smb_caching.htm
$value = "\\your-server\name-of-your-fileshare" #fill in your values
$result = (Measure-Command {Get-Item $value}).TotalMilliseconds
[Math]::Round($result) #round to get an integer as result

CPU usage of an application

# This script gets the cpu usage of the main Teams processes (not including sub-processes).
# The script returns the calculated usage in %
# For reference: https://stackoverflow.com/a/54023818

$cpu = Get-WmiObject –class Win32_processor -Property NumberOfCores, NumberOfLogicalProcessors
$teamsusage = 0

Get-Process "ms-teams*" | ForEach-Object {
    if ($_.StartTime -gt 0) {
        $ts = (New-TimeSpan -Start $_.StartTime -ErrorAction SilentlyContinue).TotalSeconds
        $cpuusage = [Math]::Round($_.CPU * 100 / $ts / $cpu.NumberOfLogicalProcessors, 2)
    } else {
        $cpuusage = 0
    }
    $teamsusage += $cpuusage
}
$teamsusage

SharePoint health score

# This is an example script that retrieves the health score value from a SharePoint site.
# For details on the SharePoint health score visit: https://www.msxfaq.de/tools/end2end/end2end-sharepoint.htm
$sharepoint = "https://your-site.sharepoint.com/" #fill in your values
$url = $sharepoint + "_layouts/15/SPAndroidAppManifest.aspx"
(Invoke-WebRequest $url).headers."X-SharePointHealthScore"