Documentation menu

PowerShell SDK API reference

Every exported cmdlet, parameter default, timing behavior and output-stream requirement.

Select language PowerShell (powershell). Enable host interpreters and allowlist pwsh or powershell. Import the module from the runtime directory:

Import-Module "$env:ROUTESPEAR_SCRIPT_SDK/RouteSpear.psm1"

This line is already in the editor’s starter script. The SDK module is bundled with the script plugin and written automatically before each run. The agent sets ROUTESPEAR_SCRIPT_SDK for that process. You do not install a module from PowerShell Gallery, copy SDK files or configure that path on the machine. PowerShell itself must already be installed and discoverable by the agent service.

The module supplies all six metric kinds, timing, args, context and credentials. It does not supply the built-in JavaScript engine’s HTTP/DNS/TCP methods. Use PowerShell/.NET networking and finite timeouts, respecting the host’s installed version and permissions.

Exported metric commands

-Name is a required metric name. Numeric -Value inputs bind to double, except Send-RsBool, which applies PowerShell truthiness. Labels are a mapping whose keys/values become strings. Emitters write directly to [Console]::Out and flush each JSON line; they return no measurement object on the pipeline.

Command	Required parameters	Optional parameters/defaults
`Send-RsMetric`	`-Metric <object>`	Raw metric serialized with compressed JSON, depth 4. You supply the full wire schema.
`Send-RsGauge`	`-Name <string> -Value <double>`	`-Unit <string>` defaults `''`; `-Labels <mapping>`.
`Send-RsCounter`	`-Name <string> -Value <double>`	`-Unit` defaults `count`; `-Labels`; `-Cumulative` switch defaults off.
`Send-RsDuration`	`-Name <string> -Value <double>`	`-Labels`; value is milliseconds, unit fixed `ms`.
`Send-RsRatio`	`-Name <string> -Value <double>`	`-Labels`; value is a fraction 0–1, unit `ratio`.
`Send-RsBool`	`-Name <string> -Value <object>`	`-Labels`; truthy emits 1, falsey emits 0. Use `$true`/`$false`, not strings such as `'false'`.
`Send-RsDistribution`	`-Name <string> -Values <double[]>`	`-Unit` defaults `''`; `-Bounds <double[]>`; `-Labels`.
`Measure-RsDuration`	`-Name <string> -Block <scriptblock>`	`-Labels`; runs the block and emits elapsed milliseconds in a `finally` clause.

Send-RsDistribution computes per-bucket counts, count/sum/min/max. Omitted or empty bounds use the shared default buckets. Use finite values and strictly ascending bounds; see metric output. Parameter binding and serialization do not establish that a wire object will pass runtime validation.

Timing and output streams

Measure-RsDuration -Name parse_ms -Labels @{ operation = 'parse' } -Block {
    $value = [int]::Parse('42')
}

The command uses System.Diagnostics.Stopwatch, discards the block’s normal pipeline output with Out-Null, and emits timing even when the block throws. It does not swallow a terminating exception or convert it to a success metric. For code that must retain a return value, use a stopwatch yourself and pass $watch.Elapsed.TotalMilliseconds to Send-RsDuration.

PowerShell often emits unused expression/command results automatically. Assign or suppress responses from Invoke-WebRequest, collection methods and other commands. A bare object, Write-Output, or formatted table on stdout is not a metric. Use [Console]::Error.WriteLine('safe diagnostic') for logs; never print credential values or authenticated response bodies.

Exported input commands

Command	Return / behavior
`Get-RsArgs`	Reads/caches stdin through `ConvertFrom-Json`; empty input returns an empty hashtable. Invalid JSON reports a decoding error.
`Get-RsContext`	Parses/caches the supplied context object. Missing/malformed context gives an empty object; it does not synthesize all nested sections.
`Get-RsTarget`	Target string, possibly empty.
`Get-RsTestId`	Check ID string, possibly empty.
`Get-RsTimeoutMs`	Runtime budget as integer milliseconds, `0` when absent; malformed nonempty numeric text can fail conversion.
`Get-RsSecret -Name <string>`	Declared credential value; cached file read. Missing names throw, and read/JSON errors remain errors.

These commands return useful values; capture them instead of letting them print on stdout. See args, context and credential maps. In standalone tests, check that optional context properties exist before reading them under strict mode.

Complete metric example

Use Args {"depth":12,"request_count":4,"samples_ms":[12,18,22]} for this fixture example. Production checks should obtain real observations instead.

Import-Module "$env:ROUTESPEAR_SCRIPT_SDK/RouteSpear.psm1"
$settings = Get-RsArgs
$labels = @{ site = 'example' }
Measure-RsDuration -Name process_ms -Labels $labels -Block {
    Send-RsGauge -Name queue_depth -Value $settings.depth -Unit count -Labels $labels
    Send-RsCounter -Name processed -Value $settings.request_count -Labels $labels
    Send-RsDistribution -Name sample_ms -Values $settings.samples_ms -Unit ms -Bounds @(10, 20, 50) -Labels $labels
    Send-RsBool -Name within_limit -Value ($settings.depth -lt 100) -Labels $labels
}
[Console]::Error.WriteLine('Processed supplied sample input')

The SDK sets strict mode internally; helper implementation commands such as Send-RsScalar and ConvertTo-RsLabels are not exported public APIs. Source implementation: agent/plugins/script/internal/sdk/files/RouteSpear.psm1.