Wavefront CLI

This is a complete command-line interface to Wavefront's API. It also provides easy ways to get data into Wavefront.

The gem is hosted on Rubygems and can be installed with

$ gem install wavefront-cli

It is built on our Wavefront Ruby SDK and requires Ruby >= 3.0. It has no "native extension" dependencies.

For a far more comprehensive overview/tutorial, please read this article.

$ wf --help
Wavefront CLI

Usage:
  wf [options] command [options]
  wf --version
  wf --help

Commands:
  account            view and manage Wavefront accounts
  alert              view and manage alerts
  apitoken           view and your own API tokens
  cloudintegration   view and manage cloud integrations
  config             create and manage local configuration
  dashboard          view and manage dashboards
  derivedmetric      view and manage derived metrics
  event              open, close, view, and manage events
  ingestionpolicy    view and manage ingestion policies
  integration        view and manage Wavefront integrations
  link               view and manage external links
  message            read and mark user messages
  metric             get metric details
  notificant         view and manage Wavefront alert targets
  proxy              view and manage proxies
  query              run Wavefront queries
  role               view and manage roles
  savedsearch        view and manage saved searches
  serviceaccount     view and manage service accounts
  settings           view and manage system preferences
  source             view and manage source tags and descriptions
  spy                monitor traffic going into Wavefront
  usage              view and manage usage reports
  usergroup          view and manage Wavefront user groups
  webhook            view and manage webhooks
  window             view and manage maintenance windows
  write              send data to Wavefront

Use 'wf <command> --help' for further information.

General Rules

Credentials and the Config File

You can pass in your Wavefront API and token with command-line options -E and -t; with the environment variables WAVEFRONT_ENDPOINT and WAVEFRONT_TOKEN, or by putting them in a configuration file at ${HOME}/.wavefront. This is an ini-style file, with a section for each Wavefront account you wish to use. (None of the tokens shown here are real, of course!)

[default]
token = 106ba476-e3bd-c14c-4a3d-391cd4c11def
endpoint = metrics.wavefront.com
proxy = wavefront.localnet
format = human

[company]
token = 9ac40b15-f47f-a168-a5d3-271ab5bad617
endpoint = company.wavefront.com
format = yaml

You can override the config file location with -c, and select a profile with -P. If you don't supply -P, the default profile is used.

Listing Things

Most commands have a list subcommand, which will produce brief "one thing per line" output. The unique ID of the "thing" is in the first column.

$ wf proxy list
457d6cf3-5171-45e0-8d31-5c980be889ea  test agent
917102d1-a10e-997b-ba63-95058f98d4fb  Agent on wavefront-2017-03-13-02
926dfb4c-23c6-4fb9-8c8d-833625ab8f6f  Agent on shark-wavefront

You can get more verbose listings with the -l flag. Results may be paginated. You can progress through pages with the -L and -o options, or use --all to get everything in one go.

Describing Things

Most commands have a describe subcommand which will tell you more about the object.

$ wf proxy describe 917102d1-a10e-497b-ba63-95058f98d4fb
name                     Agent on wavefront-2017-03-13-02
id                       917102d1-a10e-497b-ba63-95058f98d4fb
version                  4.7
customerId               sysdef
inTrash                  false
lastCheckInTime          2017-06-06 14:47:20
hostname                 wavefront-2017-03-13-02
timeDrift                -751
bytesLeftForBuffer       1536094720
bytesPerMinuteForBuffer  280109
localQueueSize           0
sshAgent                 false
ephemeral                false
deleted                  false

Most timestamps come back from the API as epoch seconds or epoch milliseconds. The CLI, in its human-readable descriptions, will convert those to YYYY-MM-DD HH:mm:ss when it describes something.

Formats, Importing, and Exporting

All commands support the -f option. This takes one of json, yaml, human and raw, and tells the CLI to present the information it fetches from the Wavefront API in that format. (raw is the raw Ruby representation, which, for instance, you could paste into irb.) Some object types can be exported in other formats. Alerts, notificants and dashboards can be exported as HCL, for easy integration with Space Ape's Wavefront Terraform provider. Query results can be presented as CSV files, or in the native Wavefront data format.

Human output can be selective. As well as the time formatting mentioned above, human-readable listings and desctiptions may omit data which is not likely to be useful, or which is extremely hard to present in a readable way.

If you describe an object like a dashboard, account, webhook etc as json or yaml, and send the output to a file, you can re-import that data. The format of the file to be imported is automatically detected.

$ wf user list
slackboy@gmail.com
sysdef.limited@gmail.com
$ wf user describe -f json sysdef.limited@gmail.com > user.json
$ cat user.json
{"identifier":"sysdef.limited@gmail.com","customer":"sysdef","groups":["agent_management"]}
$ wf user delete sysdef.limited@gmail.com
Deleted user 'sysdef.limited@gmail.com'.
$ wf user list
slackboy@gmail.com
$ wf user import user.json
Imported user.
identifier  sysdef.limited@gmail.com
customer    sysdef
groups      agent_management
$ wf user list
slackboy@gmail.com
sysdef.limited@gmail.com

You could, of course, modify certain aspects of the exported data before re-importing. You can import an object over the top of an existing one with import --update.

Time Windows

Commands which operate on a time window, such as query or event will expect that window to be defined with -s and -e (or --start and --end). Times can be in seconds since the epoch, or any format which Ruby's strptime method method can parse unaided. For instance:

$ wf command --start 12:15 --end 12:20 ...

will define a window between 12:15 and 12:20pm today. If you ran that in the morning, the time would be invalid, and you would get a 400 error from Wavefront, so something of the form 2016-04-17T12:25:00 would remove all ambiguity.

There is no need to include a timezone in your time: the wf CLI will automatically use your local timezone when it parses the string. You can also specify relative times: for instance '-10m' for the last ten minutes.

Querying Data

Use the query subcommand with any timeseries expression.

$ wf query "ts(cpu.*.pc.user, source=cube)" | more
name          ts(cpu.*.pc.user, source=cube)
query         ts(cpu.*.pc.user, source=cube)
timeseries
  label       cpu.0.pc.user
  sparkline   > ▇▅     █<
  host        cube
  tags
    env       lab
  data                     13:39:00    26.081756828668336
                           13:40:00    20.37380923087
                           13:41:00    4.086552186471667
                           13:42:00    2.5642049289966664
                           13:43:00    2.542284133615
                           13:44:00    2.6524157880366666
                           13:45:00    2.1158611431600005
                           13:46:00    27.911804005566665
              2019-03-07   13:38:00    3.8412758439216668
              ------------------------------------------------------------------
  label       cpu.1.pc.user
  sparkline   > █▅     ▇<
  host        cube
  tags
    env       lab
  data                     13:39:00    27.45281202666833
                           13:40:00    19.441659754188333
                           13:41:00    3.96397654233
                           13:42:00    2.49657063456
                           13:43:00    2.4946187951783334
                           13:44:00    2.8966526517783335
                           13:45:00    2.636301021795
                           13:46:00    25.407542657531668
              2019-03-07   13:38:00    4.655340261835
...
events        <none>
warnings      <none>

By default you get the last ten minutes of data, but the time windowing rules can be used to specify any range.

Writing Points

Writing a single point is simple:

$ wf write point cli.example 10

and you can add point tags, if you like.

$ wf write point cli.example 9.4 -E wavefront -T proxy=wavefront -T from=README

or force a timestamp:

$ wf write point -t 16:53:14 cli.example 8

More usefully, you can write from a file. Your file must contain multiple columns: metric name (m), metric value (v), timestamp(t), and point tags (T). v is mandatory, m can be filled in with the -m flag, t can be filled in with the current timestamp, and T is optional, but if used, must be last. You then tell the CLI what order your fields are in.

$ cat datafile
1496767813 dev.cli.test 12.1
1496767813 dev.cli.test 10.0
1496767813 dev.cli.test 14.5
$ wf write file -F tmv datafile

If you set the file to -, you can read from standard in:

$ while true; do echo $RANDOM; sleep 1; done | wf write file -m cli.demo -Fv -

If you wish to write points directly via the API, and you have the "direct ingestion" privilege, just add -u api to your write command. To send points to a proxy over HTTP, use -u http, and to write to a Unix socket use -u socket.

You can write delta metrics with -i (for increment).

$ wf write point -i counter.example 4

To sent negative values, you must use -- to tell wf that you have finished declaring options, or get creative with your quoting.

$ wf write point cli.example -- -10
$ wf write point cli.example "\-10"

You can even write distibutions. Either list every number individually, or use x to specify multiples of any value. You can mix and match within the same line.

$ wf write distribution dist.example 3 1 4 1 1 2 3 6 4 1 3 2
$ wf write distribution dist.example 3x3 4x1 2x4 2x2 1x6
$ wf write distribution dist.example 3x3 4x1 4 4 2x2 6

wavefront-cli

Runtime