Crate bosun_emitter

bosun_emitter - A library to emit metric data to Bosun from your command line.

"Bosun is an open-source, MIT licensed, monitoring and alerting system by Stack Exchange. It has an expressive domain specific language for evaluating alerts and creating detailed notifications. It also lets you test your alerts against history for a faster development experience." ^[1]

Bosun receives metric data mostly via scollector which is Boson's agent running on each monitored host. scollector runs build-in as well as external collectors periodically to collect and transmit metrics on its hosts.

While it is easy to create external collectors suitable for most needs, there are cases in which sending a single, individual metric datum may be helpful. Such cases may comprise any individually run program such as a Cron job for backups or in general any other shell script. Further, it might be helpful to send metric data from your own application.

bosun_emitter is a library that makes it easy to send metric data and corresponding meta data describing the metric. Further, this crate contains a CLI standalone binary called emit_bosun that may be used on the command line or from any shell script to send a single metric datum.

Example

Library

use bosun_emitter::{BosunClient, Datum, EmitterError, Metadata, now_in_ms, Tags};

let client = BosunClient::new("localhost:8070");
let metric = "lukas.tests.count";

let metadata = Metadata::new(&metric, "counter", "Test", "Amount of Lukas Tests");
let _ = client.emit_metadata(&metadata);

let tags: Tags = Tags::new();
let datum = Datum::new(&metric, now_in_ms(), "42", &tags);

match client.emit_datum(&datum) {
    Ok(_) => {}
    Err(EmitterError::JsonParseError(_)) => panic!("Failed to create JSON document."),
    Err(EmitterError::EmitError(_)) => panic!("Failed to send."),
    Err(EmitterError::ReceiveError(_)) => panic!("Failed to create resource."),
}

CLI Tool -- Shell Script

#!/bin/bash

local start=$(date +%s)
# Complex, time consuming backup ...
local now=$(date +%s)
local runtime=$((${now}-${start}))

emit_bosun --host localhost:8070 --hostname backup-server --tags 'type=mongodb,database=production' --metric backup.runtime --value $runtime --rate gauge --unit sec -d "Backup runtime"

emit_bosun parses scollector config files for settings like Bosun server Host, --host, local hostname Hostname, --hostname, and tags Tags, --tags. In case scollector is configured on your host, you can omit these CLI parameters and just pass the configuration file.

CLI Tool -- Parsing scollector Configuration File

> emit_bosun -c /etc/bosun/scollector.conf --metric backup.runtime --value $runtime --rate gauge --unit sec -d "Backup Runtime in sec"

The above example scollector configuration file is the default path where emit_bosun looks for a configuration file. So you can even omit that parameter. In addition, tags passed on the command line will be merged with tags read from scollector's configuration file.

> emit_bosun --metric backup.runtime --value $runtime --rate gauge --unit sec -d "Backup Runtime in sec"

Structs

BosunClient	Encapsulates Bosun server connection.
BosunConfig	Represents connection parameters to reach Bosun as well as default tags to append to each metric datum.
Datum	Represents a metric datum.
Metadata	Represents metric meta data.

Enums

EmitterError

Errors which may occur while sending either meta data or metric data.

Functions

now_in_ms

Returns Unix timestamp in ms.

Type Definitions

EmitterResult	Result of an attempt to send meta data or a metric datum
Tags	Metric tags equivalent to Rust's HashMap<String, String>