Custom script SDKs

Custom script checks collect observations with your code and emit metrics using RouteSpear’s SDKs. Choose built-in JavaScript or an enabled host interpreter: Python, Node.js, Bash or PowerShell. Each SDK supplies metric emission, non-secret arguments, run context and named credentials. Their exact APIs differ by language.

The SDK is included and configured automatically

You do not install a RouteSpear SDK on the agent machine. The script plugin already contains the Python, Node.js, Bash and PowerShell helper libraries. Before each run, it writes fresh copies into that run’s private working directory and configures the script’s environment. SDK updates arrive with the script plugin, so its helpers and metric parser stay together.

• Python: write import routespear as rs. The agent sets the import path.
• Node.js: write const rs = require('routespear');. The agent sets the CommonJS module search path.
• Bash: source "$ROUTESPEAR_SCRIPT_SDK/routespear.sh". The agent supplies that variable and file; you do not create the directory or configure a path.
• PowerShell: import "$env:ROUTESPEAR_SCRIPT_SDK/RouteSpear.psm1". The agent supplies that variable and module too.

The editor’s starter script already includes the appropriate import line. Keep that line when writing your check; SDK functions are not injected as implicit globals. There is no separate pip/npm SDK install or machine-wide SDK environment setup.

The interpreter is separate. Built-in JavaScript ships with the agent. Python and Node.js can use optional managed runtimes on supported agents, or interpreters installed by the host operator. Bash/sh and PowerShell remain operator-installed. Automatic discovery finds existing interpreters on the agent service’s PATH; managed runtimes require a separate local opt-in. Verify the deployed agent’s reported capabilities before selecting a managed version.

SDK reference

Each language page lists its public methods, parameters, defaults, return values, error behavior and examples. Shared pages describe the runtime contract.

• Managed runtimes: installation permission, version selection, verified downloads, updates, rollback and system interpreters.

• Parameters and execution: every check parameter, runtime prerequisites, deadlines, resource limits and signed-bundle fields.

• Metrics and output: all six metric kinds, the JSON wire schema, units, counter temporality, distributions, labels and budgets.

• Arguments, context and secrets: input JSON, the full context schema, credential references and helper equivalents across languages.

• Built-in JavaScript: the complete rs module, including synchronous HTTP, DNS and TCP host APIs.

• Python: all Python functions, keyword arguments and the timed context manager.

• Node.js: the CommonJS module and its host-runtime behavior.

• Bash: shell functions, JSON handling and quoting requirements.

• PowerShell: exported commands and their parameters, timing and output streams.

• Examples and troubleshooting: authenticated HTTP checks in JavaScript and Python, local validation and common failures.

Choose a language

Capability	Built-in JavaScript	Python	Node.js	Bash	PowerShell
Language value	js	python	node	bash	powershell
Scalar metrics	Yes	Yes	Yes	Yes	Yes
Distribution helper	Yes	Yes	Yes	No; raw JSON possible	Yes
Timing helper	rs.timer	rs.timed	rs.timer	rs_now_ms clock	Measure-RsDuration
Args, context, target, check ID, timeout, secrets	Yes	Yes	Yes	Yes; JSON text for args/context	Yes
SDK HTTP/DNS/TCP helpers	Yes	No	No	No	No
Needs a host interpreter	No	Yes	Yes	Yes	Yes

Python has the core RouteSpear helpers. It emits the same six metric kinds and reads the same run inputs and declared credentials. Use rs.boolean, rs.test_id, rs.timeout_ms and rs.timed for the Python spellings.

Networking convenience methods currently belong to the built-in JavaScript engine. Host languages use their own standard libraries or installed packages. For example, Python can combine urllib.request with rs.secret, rs.duration and rs.boolean; the HTTP example shows the complete flow. Host networking has the interpreter’s OS permissions; it does not use the engine’s target-policy host API.

Built-in JavaScript is useful when you want a portable check without a host interpreter. It supports only require('routespear'), synchronous networking and the documented SDK. Node globals, npm modules, browser APIs and global fetch are unavailable. Choose a host language when you need its libraries, existing code or host facilities, subject to the operator’s execution grants.

Write your first check

1. Create a Custom script check and choose Write a script.
2. Select a language supported and enabled on the executing agent.
3. Paste code using that language’s SDK import and metric helpers.
4. Put non-secret input in Args (JSON). Put only credential names and store references in Advanced → Credential references.
5. Set a timeout that covers the operation and cleanup. Save deliberately, then inspect a real run’s metrics, stderr and refusal/timeout diagnostics.

For a local SDK smoke check, choose Python and set Args to {"depth":12}:

import routespear as rs

settings = rs.args()
rs.gauge("queue_depth", settings["depth"], unit="count")

This emits the supplied fixture value to demonstrate the input/output contract. A production check should obtain the reading from the system it monitors. The agent supplies the SDK import path; installing the RouteSpear module with pip or npm is unnecessary. Additional third-party packages are not installed automatically.

Use stderr for diagnostics and reserve stdout for metric JSON lines. Keep credentials out of source, args, labels, logs and assistant messages. A failed script or absent reading is not automatically an observed service failure.

Signed bundle mode runs an operator-installed, signed artifact by name. It has separate trust, interpreter and argument requirements; see parameters and execution.

Ask Spear for coding help

Select Ask Spear beside the script or bundle entry. The Custom Script specialist receives the current unsaved language, code, args, credential references and schedule. Large drafts are explicitly marked as excerpts. Ask it to write a check, explain a helper, review metric output, or debug an error.

The specialist can read this reference and the exact SDK/runtime sources bundled with the portal API. Copy suggested code into the editor and review it before saving. Assistance does not execute code, save a check or verify the executing agent’s installed capabilities.

These pages describe the source implementation shipped with this documentation. Deployed agents and portal APIs need matching updates before new behavior or reference content is available there.