Snowplow Tracking CLI 0.1.0 released


We are pleased to announce the first release of the Snowplow Tracking CLI! This is a command-line application (written in Golang) to make it fast and easy to send an event to Snowplow directly from the command line. You can use the app to embed Snowplow tracking directly into your shell scripts.
In the rest of this post we will cover:
- How to install the app
- How to use the app
- Examples
- Under the hood
- Roadmap
- Documentation and getting help
1. How to install the app
You can download the binary for Linux and Windows directly from Bintray:
Unzip the file and the app is called snowplowtrk
.
The binary for macOS is scheduled for version 0.2.0 – (see issue #2).
2. How to use the app
The command line interface is as follows:
snowplowtrk --collector=[[COLLECTOR_DOMAIN]] --appid=[[APP_ID]] --method=[[POST|GET]] --sdjson=[[SELF_DESC_JSON]]
or:
snowplowtrk --collector=[[COLLECTOR_DOMAIN]] --appid=[[APP_ID]] --method=[[POST|GET]] --schema=[[SCHEMA_URI]] --json=[[JSON]]
Where:
--collector
is the domain for your Snowplow collector, e.g.snowplow-collector.acme.com
--appid
is optional (not sent if not set)--method
is optional. It defaults toGET
--sdjson
is a self-describing JSON of the standard form{ "schema": "iglu:...", "data": { ... } }
--schema
is a schema URI, most likely of the formiglu:...
--json
is a (non-self-describing) JSON, of the form{ ... }
--dbpath
is optional, it allows you to set the full path to where the event database is created. It defaults toevents.db
in the same directory as the application
You can either send in a self-describing JSON, or pass in the constituent parts (i.e. a regular JSON plus a schema URI) and the Snowplow Tracking CLI will construct the final self-describing JSON for you.
3. Examples
Here are some examples:
$ snowplowtrk --collector snowplow-collector.acme.com --appid myappid --method POST --schema iglu:com.snowplowanalytics.snowplow/event/jsonschema/1-0-0 --json "{"hello":"world"}"
$ snowplowtrk --collector snowplow-collector.acme.com --appid myappid --method POST --sdjson "{"schema":"iglu:com.snowplowanalytics.snowplow/event/jsonschema/1-0-0", "data":{"hello":"world"}}"
4. Under the hood
There is no buffering in the Snowplow Tracking CLI – each event is sent as an individual payload whether GET
or POST
.
Under the hood, the app uses the Snowplow Golang Tracker.
The Snowplow Tracking CLI will exit once the Snowplow collector has responded. The return codes from snowplowtrk
are as follows:
- 0 if the Snowplow collector responded with an OK status (2xx or 3xx)
- 4 if the Snowplow collector responded with a 4xx status
- 5 if the Snowplow collector responded with a 5xx status
- 1 for any other error
5. Roadmap
In the future, we plan to support generating events from local files of newline-delimited (ND) JSON. There is potential for the Snowplow Tracking CLI to evolve into a sophisticated logfile-to-Snowplow emitter, along similar lines to Logstash or Fluentd.
6. Documentation and getting help
This is the first release of the Snowplow Tracking CLI.
For more information, check out the project README</a>; you can read more about self-describing JSONs here.
If you have any questions or run into any problems, please raise an issue or get in touch with us through the usual channels.