Custom Metrics - Using the API CLI

As well as interacting directly with the REST API, a Command line interface is available for calling common API Functions. In this tutorial we will create and send custom metrics to your BMC TrueSight Pulse account using this CLI.

1) Install the API CLI. see the API documentation for info on this

2) Confirm the CLI is installed. If you haven't already export the environment metrics for your account email address and API Token:


$export BOUNDARY_API_TOKEN="api.mysecretToken-5536"

Then run "metric-list" and you should see an output of all the metrics in your account

3) Create your new metric. Before we send data to BMC TrueSight Pulse we need to tell it what to expect. Metric names in BMC TrueSight Pulse exist globally and therefore you should create a metric name that is unique to your account, and you'll also let the system know what kind of data we're sending it. For example:

metric-create -n LF851_USERS_ONLINE -d "Online Users" -s "Users Online" -i "Count of Online Users" -g avg -u number -r 1000

 -n Is the unique name of my metric. This must not begin with a number or contain spaces, and should be in all caps. I have used a naming convention of initials and year of birth to ensure this is a unique name.

-d Metric display name

-s Short name - some dashboards and screens need to abbreviate the metric name

-i Metric description

-g Default Aggregate (avg, min, max, etc)

-u Unit (percent, number, countOfBytes etc)

-r Default Resolution (ms)

Provided there are no issues with your input you should receive the below response (success: true)


With the metric created we can use the measurement-create command to send data. This is simply a case of sending the metric name, measurement, source and optionally a timestamp:

measurement-create -n LF851_USERS_ONLINE -m 10 -s ""</code>

Again we should receive a success response. Run this a couple more times, and head over to BMC TrueSight Pulse to check you see data (you'll need to add the metric to your dashboard to see it!)

That's all there is to it! You can use these commands inside scripts that do some data collection and have them running in the background, for example this script sends a random number every second (which isn't the best way to track online users). It's that easy to have your own custom metrics in BMC TrueSight Pulse.

while :
count=$[RANDOM % 10]
measurement-create -n LF851_USERS_ONLINE -m $count -s ""
sleep 1

Have more questions? Submit a request