[−][src]Crate libhoney
Rust library for sending data to Honeycomb.
IMPORTANT NOTE: please do NOT use this in production (yet).
But I'd be forever greatful if you can try it out and provide feedback. There are a few reasons why I think this is not yet for prime time (aka: production):
-
I'm not happy with the interfaces for the library - althought they are closer to idiomatic rust than the instructions (Honeycomb SDK spec - singleton pattern) I don't think they're quite there yet. That means I'll probably make breaking changes to this, which will cause you pain if you use it straight away. I didn't use the singleton pattern, meaning you have to init and then use the client for the operations (you control the client, not the library).
-
I'm not convinced of the threading code, and how I return responses. Although "it works" it probably isn't what you'd want from a mature library.
-
I have mostly copied the docs from Honeycomb, so there will be a few places where they don't quite match the content, which also means that you'll have a hard time following the docs (sorry!).
-
I tried to get to a workable state quickly and so I (ab)used .unwrap() a lot - that's bad in a library as it will panic your client.
-
I've set Metadata as a "serialisable json value" (serde_json::Value) - this isn't quite right but allows for a nicer use of the library. Check the nlopes/metadata-user-set branch for a user defined Metadata instead.
-
I don't allow a custom logger yet
For these reasons, you're probably better waiting for a 1.0.0 relase (I'll follow semantic versioning). Having said that, if you still want to use this, thank you for being brave, and make sure to open bugs against it!
libhoney
Rust library for sending events to Honeycomb, a service for debugging your software in production.
Usage and Examples
Initialization
Initialize the library by passing in your Team API key and the default dataset name to which it should send events. When you call the library’s initialization routine, it spins up background threads to handle sending all the events. Calling .close() on the client will terminate all background threads.
let client = libhoney::init(libhoney::Config{ options: libhoney::ClientOptions { api_key: "YOUR_API_KEY".to_string(), dataset: "honeycomb-rust-example".to_string(), ..Default::default() }, transmission_options: Default::default(), }); client.close();
Further configuration options can be found in the API reference.
Building and Sending Events
Once initialized, the libhoney client is ready to send events. Events go through three phases:
- Creation
event := builder.new_event()
- Adding fields
event.add_field("key", Value::String("val".to_string()))
,event.add(data)
- Transmission
event.send(&mut client)
Upon calling .send(), the event is dispatched to be sent to Honeycomb. All libraries set defaults that will allow your application to function as smoothly as possible during error conditions.
In its simplest form, you can add a single attribute to an event with the .add_field(k, v) method. If you add the same key multiple times, only the last value added will be kept.
More complex structures (maps and structs—things that can be serialized into a JSON object) can be added to an event with the .add(data) method.
Events can have metadata associated with them that is not sent to Honeycomb. This metadata is used to identify the event when processing the response. More detail about metadata is below in the Response section.
Handling responses
Sending an event is an asynchronous action and will avoid blocking by default. .send() will enqueue the event to be sent as soon as possible (thus, the return value doesn’t indicate that the event was successfully sent). Use the Vec returned by .responses() to check whether events were successfully received by Honeycomb’s servers.
Before sending an event, you have the option to attach metadata to that event. This metadata is not sent to Honeycomb; instead, it’s used to help you match up individual responses with sent events. When sending an event, libhoney will take the metadata from the event and attach it to the response object for you to consume. Add metadata by populating the .metadata attribute directly on an event.
Responses have a number of fields describing the result of an attempted event send:
-
metadata: the metadata you attached to the event to which this response corresponds
-
status_code: the HTTP status code returned by Honeycomb when trying to send the event. 2xx indicates success.
-
duration: the time.Duration it took to send the event.
-
body: the body of the HTTP response from Honeycomb. On failures, this body contains some more information about the failure.
-
error: when the event doesn’t even get to create a HTTP attempt, the reason will be in this field. (e.g. when sampled or dropped because of a queue overflow).
You don’t have to process responses if you’re not interested in them—simply ignoring them is perfectly safe. Unread responses will be dropped.
Examples
Honeycomb can calculate all sorts of statistics, so send the data you care about and let us crunch the averages, percentiles, lower/upper bounds, cardinality—whatever you want—for you.
Simple: send an event
use libhoney::FieldHolder; // Add trait to allow for adding fields // Call init to get a client let mut client = init(libhoney::Config { options: options, transmission_options: Default::default(), }); let mut data: HashMap<String, Value> = HashMap::new(); data.insert("duration_ms".to_string(), json!(153.12)); data.insert("method".to_string(), Value::String("get".to_string())); data.insert("hostname".to_string(), Value::String("appserver15".to_string())); data.insert("payload_length".to_string(), json!(27)); let mut ev = client.new_event(); ev.add(data); ev.send(&mut client);
Macros
json | Construct a |
Structs
Builder | Builder is used to create templates for new events, specifying default fields and override settings. |
Client | Client represents an object that can create new builders and events and send them somewhere. |
ClientOptions | ClientOptions is a subset of the global libhoney config that focuses on the configuration of the client itself. |
Config | Config allows the user to customise the initialisation of the library (effectively the Client) |
Event | Event is used to hold data that can be sent to Honeycomb. It can also specify overrides of the config settings (ClientOptions). |
TransmissionOptions | TransmissionOptions includes various options to tweak the behavious of the sender. |
Enums
Value | Represents any valid JSON value. |
Traits
FieldHolder | FieldHolder implements common functions that operate on the |
Functions
init | init is called on app initialisation and passed a Config. A Config has two sets of options (ClientOptions and TransmissionOptions). |
Type Definitions
DynamicFieldFunc | Shorthand type for the function to be passed to the add_dynamic_field calls |