Libhoney
Extends:
libhoney aims to make it as easy as possible to create events and send them on into Honeycomb.
See https://honeycomb.io/docs for background on this library.
Constructor Summary
Public Constructor | ||
public |
constructor(opts: Object) Constructs a libhoney context in order to configure default behavior,
though each of its members ( |
Member Summary
Public Members | ||
public set |
The hostname for the Honeycomb API server to which to send events created through this libhoney instance. |
|
public get |
The hostname for the Honeycomb API server to which to send events created through this libhoney instance. |
|
public set |
The name of the Honeycomb dataset to which to send events through this libhoney instance. |
|
public get |
The name of the Honeycomb dataset to which to send these events through this libhoney instance. |
|
public set |
The rate at which to sample events. |
|
public get |
The rate at which to sample events. |
|
public get |
transmission: * The transmission implementation in use for this libhoney instance. |
|
public set |
The Honeycomb authentication token. |
|
public get |
The Honeycomb authentication token. |
Private Members | ||
private |
_builder: * |
|
private |
_options: * |
|
private |
_responseQueue: *[] |
|
private |
|
|
private |
_usable: * |
Method Summary
Public Methods | ||
public |
adds a group of field->values to the global Builder. |
|
public |
addDynamicField(name: string, fn: function(): any): Libhoney adds a single field->dynamic value function to the global Builder. |
|
public |
adds a single field->value mapping to the global Builder. |
|
public |
creates and returns a clone of the global Builder, merged with fields and dyn_fields passed as arguments. |
|
public |
creates and returns a new Event containing all fields/dyn_fields from the global Builder, that can be further fleshed out and sent on its own. |
|
public |
creates and sends an event, including all global builder fields/dyn_fields, as well as anything in the optional data parameter. |
Private Methods | ||
private |
_responseCallback(responses: *) |
|
private |
sendEvent(event: *) sendEvent takes events of the following form: |
|
private |
sendPresampledEvent(event: *) sendPresampledEvent takes events of the following form: |
|
private |
validateEvent(event: *): Object validateEvent takes an event and validates its structure and contents. |
Public Constructors
public constructor(opts: Object) source
Constructs a libhoney context in order to configure default behavior,
though each of its members (apiHost
, writeKey
, dataset
, and
sampleRate
) may in fact be overridden on a specific Builder or Event.
Params:
Name | Type | Attribute | Description |
opts | Object |
|
overrides for the defaults |
opts.apiHost | string |
|
Server host to receive Honeycomb events. |
opts.proxy | string |
|
The proxy to send events through. |
opts.writeKey | string | Write key for your Honeycomb team. (Required) |
|
opts.dataset | string | Name of the dataset that should contain this event. The dataset will be created for your team if it doesn't already exist. |
|
opts.sampleRate | number |
|
Sample rate of data. If set, causes us to send 1/sampleRate of events and drop the rest. |
opts.batchSizeTrigger | number |
|
We send a batch to the API when this many outstanding events exist in our event queue. |
opts.batchTimeTrigger | number |
|
We send a batch to the API after this many milliseconds have passed. |
opts.maxConcurrentBatches | number |
|
We process batches concurrently to increase parallelism while sending. |
opts.pendingWorkCapacity | number |
|
The maximum number of pending events we allow to accumulate in our sending queue before dropping them. |
opts.maxResponseQueueSize | number |
|
The maximum number of responses we enqueue before dropping them. |
opts.disabled | boolean |
|
Disable transmission of events to the specified |
Example:
import Libhoney from 'libhoney';
let honey = new Libhoney({
writeKey: "YOUR_WRITE_KEY",
dataset: "honeycomb-js-example",
// disabled: true // uncomment when testing or in development
});
Public Members
public set apiHost: string source
The hostname for the Honeycomb API server to which to send events created through this libhoney instance. default: https://api.honeycomb.io/
public get apiHost: string source
The hostname for the Honeycomb API server to which to send events created through this libhoney instance. default: https://api.honeycomb.io/
public set dataset: string source
The name of the Honeycomb dataset to which to send events through this libhoney instance. If it is specified during libhoney initialization, it will be used as the default dataset for all events. If absent, dataset must be explicitly set on a builder or event.
public get dataset: string source
The name of the Honeycomb dataset to which to send these events through this libhoney instance. If it is specified during libhoney initialization, it will be used as the default dataset for all events. If absent, dataset must be explicitly set on a builder or event.
public set sampleRate: number source
The rate at which to sample events. Default is 1, meaning no sampling. If you want to send one event out of every 250 times send() is called, you would specify 250 here.
public get sampleRate: number source
The rate at which to sample events. Default is 1, meaning no sampling. If you want to send one event out of every 250 times send() is called, you would specify 250 here.
public get transmission: * source
The transmission implementation in use for this libhoney instance. Useful when mocking libhoney (specify "mock" for options.transmission, and use this field to get at the list of events sent through libhoney.)
public set writeKey: string source
The Honeycomb authentication token. If it is set on a libhoney instance it will be used as the default write key for all events. If absent, it must be explicitly set on a Builder or Event. Find your team write key at https://ui.honeycomb.io/account
public get writeKey: string source
The Honeycomb authentication token. If it is set on a libhoney instance it will be used as the default write key for all events. If absent, it must be explicitly set on a Builder or Event. Find your team write key at https://ui.honeycomb.io/account
Private Members
private _builder: * source
private _options: * source
private _responseQueue: *[] source
private _transmission: * source
private _usable: * source
Public Methods
public add(data: Object | Map<string, any>): Libhoney source
adds a group of field->values to the global Builder.
Example:
honey.add ({
buildID: "a6cc38a1",
env: "staging"
});
let map = new Map();
map.set("build_id", "a6cc38a1");
map.set("env", "staging");
honey.add (map);
public addDynamicField(name: string, fn: function(): any): Libhoney source
adds a single field->dynamic value function to the global Builder.
Example:
honey.addDynamicField("process_heapUsed", () => process.memoryUsage().heapUsed);
public addField(name: string, val: any): Libhoney source
adds a single field->value mapping to the global Builder.
Params:
Name | Type | Attribute | Description |
name | string | name of field to add. |
|
val | any | value of field to add. |
Example:
honey.addField("build_id", "a6cc38a1");
public newBuilder(fields: Object | Map<string, any>, dyn_fields: Object | Map<string, any>): Builder source
creates and returns a clone of the global Builder, merged with fields and dyn_fields passed as arguments.
Example:
let builder = honey.newBuilder();
let builder = honey.newBuilder({ requestId },
{
process_heapUsed: () => process.memoryUsage().heapUsed
});
public newEvent(): Event source
creates and returns a new Event containing all fields/dyn_fields from the global Builder, that can be further fleshed out and sent on its own.
Example:
let ev = honey.newEvent();
ev.addField("additionalField", value);
ev.send();
public sendNow(data: Object | Map<string, any>): * source
creates and sends an event, including all global builder fields/dyn_fields, as well as anything in the optional data parameter.
Return:
* |
Example:
honey.sendNow ({
responseTime_ms: 100,
httpStatusCode: 200
});
let map = new Map();
map.set("responseTime_ms", 100);
map.set("httpStatusCode", 200);
honey.sendNow (map);
Private Methods
private _responseCallback(responses: *) source
Params:
Name | Type | Attribute | Description |
responses | * |
private sendEvent(event: *) source
sendEvent takes events of the following form:
{ data: a JSON-serializable object, keys become colums in Honeycomb timestamp [optional]: time for this event, defaults to now() writeKey [optional]: your team's write key. overrides the libhoney instance's value. dataset [optional]: the data set name. overrides the libhoney instance's value. sampleRate [optional]: cause us to send 1 out of sampleRate events. overrides the libhoney instance's value. }
Sampling is done based on the supplied sampleRate, so events passed to this method might not actually be sent to Honeycomb.
Params:
Name | Type | Attribute | Description |
event | * |
private sendPresampledEvent(event: *) source
sendPresampledEvent takes events of the following form:
{ data: a JSON-serializable object, keys become colums in Honeycomb timestamp [optional]: time for this event, defaults to now() writeKey [optional]: your team's write key. overrides the libhoney instance's value. dataset [optional]: the data set name. overrides the libhoney instance's value. sampleRate: the rate this event has already been sampled. }
Sampling is presumed to have already been done (at the supplied sampledRate), so all events passed to this method are sent to Honeycomb.
Params:
Name | Type | Attribute | Description |
event | * |