Bash and sh SDK API reference

Select language Bash (bash). The agent tries its allowlisted bash, then sh; code requiring Bash-specific syntax needs Bash on that agent. Enable host interpreters and source the library the agent supplies:

. "$ROUTESPEAR_SCRIPT_SDK/routespear.sh"

This line is already in the editor’s starter script. The SDK file is bundled with the script plugin and written automatically before each run. The agent sets ROUTESPEAR_SCRIPT_SDK for that process; it is not a path you need to configure or a library you need to install. The shell interpreter itself must already be installed and discoverable by the agent service.

Shell helpers write the same metric JSON as the other SDKs. They use positional arguments and do not have object keyword options. There is no shell distribution helper, raw public rs_emit, timer wrapper or SDK HTTP/DNS/TCP API. Use installed OS commands for collection and keep their normal stdout out of metric output.

Metric helpers

Helper	Positional arguments	Meaning/defaults
rs_gauge	NAME VALUE [UNIT] [LABELS_JSON]	Gauge; default unit empty.
rs_counter	NAME VALUE [UNIT] [LABELS_JSON]	Delta counter; default unit count.
rs_counter_cumulative	NAME VALUE [UNIT] [LABELS_JSON]	Cumulative external running total; default unit count.
rs_duration	NAME MILLISECONDS [LABELS_JSON]	Duration with unit ms.
rs_ratio	NAME VALUE [LABELS_JSON]	Fraction 0–1, unit ratio.
rs_bool	NAME VALUE [LABELS_JSON]	Values 1, true, TRUE, True, yes, YES, Yes emit 1; everything else emits 0.
rs_labels	key=value [key=value ...]	Returns a JSON label object on stdout; capture it instead of emitting it alone.

Metric helpers write one line to stdout. Their shell exit status is not an acknowledgment that ingestion accepted the metric. Supply numeric literals for VALUE (no units, percent suffix or thousands separators). Names, units and labels must satisfy the output contract.

Optional arguments retain their positions. To pass labels with an empty gauge unit, write rs_gauge temperature 21.5 "" "$labels". Use actual booleans or the documented rs_bool values; shell command exit codes use the opposite convention, where zero means success. Convert them explicitly.

JSON quoting

rs_labels is a lightweight builder and does not JSON-escape keys or values. Use it only for controlled values without quotes, backslashes or control characters. For arbitrary strings, use an installed JSON tool:

labels=$(jq -cn --arg site "$site" '{site:$site}')
rs_gauge queue_depth 12 count "$labels"

The emitted metric name and unit are also interpolated directly. Keep them to the valid fixed names/unit strings. The SDK does not sanitize arbitrary command output into valid metric names. Do not enable set -u casually: the lightweight helper internals access optional positional parameters directly.

Run and credential helpers

Helper	Output / behavior
rs_args	Raw stdin JSON, or {}. Does not parse or validate it.
rs_context	Raw runtime context JSON, or {}.
rs_target	Target string, or empty.
rs_test_id	Check ID string, or empty.
rs_timeout_ms	Runtime budget text, default 0; not a live countdown.
rs_secret NAME	Named credential value on stdout; nonzero exit and stderr diagnostic on missing/unreadable data. Requires jq, or Python 3 as fallback.
rs_now_ms	Epoch milliseconds for manual timing; uses Bash’s EPOCHREALTIME when available, otherwise host date. Resolution/portability depend on the shell and OS.

Capture args once into your own variable. Although rs_args has a process-local cache, each $(rs_args) command substitution runs in a subshell; a later substitution can see already-consumed stdin. For example:

args=$(rs_args)
queue=$(printf '%s' "$args" | jq -er '.queue') || exit 1
limit=$(printf '%s' "$args" | jq -er '.warn_depth') || exit 1

Likewise, capture credentials and check the exit status:

token=$(rs_secret api_token) || exit 1
# Pass token only to the intended authenticated operation. Never echo it.

The helper emits a credential value as its return channel; calling it bare would put that secret on metric stdout. See the reference map and context schema. Avoid set -x when secrets are in use. Nonzero errors require deliberate handling; the helper does not terminate its caller automatically.

Complete metric example

This example requires jq and processes supplied fixture input. Args: {"depth":12,"request_count":4}. Replace fixture values with observations in a production check.

. "$ROUTESPEAR_SCRIPT_SDK/routespear.sh"
args=$(rs_args)
depth=$(printf '%s' "$args" | jq -er '.depth | numbers') || exit 1
count=$(printf '%s' "$args" | jq -er '.request_count | numbers') || exit 1
labels=$(rs_labels site=example)
rs_gauge queue_depth "$depth" count "$labels"
rs_counter processed "$count" count "$labels"
if [ "$depth" -lt 100 ]; then
  rs_bool within_limit true "$labels"
else
  rs_bool within_limit false "$labels"
fi
printf '%s\n' 'Processed supplied sample input' >&2

For manual timing, capture start=$(rs_now_ms), perform the operation, then emit rs_duration operation_ms "$(( $(rs_now_ms) - start ))". Since this is wall-clock time, clock adjustments can affect subtraction. Validate your host’s date support, or use a monotonic timer in Python/Node for precise timings.

Source implementation: agent/plugins/script/internal/sdk/files/routespear.sh.