Home Reference Source
import Libhoney from 'libhoney/src/libhoney.js'
public class | source

Libhoney

Extends:

events~EventEmitter → Libhoney

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

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.

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

The transmission implementation in use for this libhoney instance.

public set

The Honeycomb authentication token.

public get

The Honeycomb authentication token.

Private Members
private
private
private
private
private

_usable: *

Method Summary

Public Methods
public

add(data: Object | Map<string, any>): Libhoney

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

addField(name: string, val: any): Libhoney

adds a single field->value mapping to the global Builder.

public

newBuilder(fields: Object | Map<string, any>, dyn_fields: Object | Map<string, any>): Builder

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

sendNow(data: Object | Map<string, any>): *

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 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:

NameTypeAttributeDescription
opts Object
  • optional

overrides for the defaults

opts.apiHost string
  • optional
  • default: https://api.honeycomb.io

Server host to receive Honeycomb events.

opts.proxy string
  • optional

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
  • optional
  • default: 1

Sample rate of data. If set, causes us to send 1/sampleRate of events and drop the rest.

opts.batchSizeTrigger number
  • optional
  • default: 50

We send a batch to the API when this many outstanding events exist in our event queue.

opts.batchTimeTrigger number
  • optional
  • default: 100

We send a batch to the API after this many milliseconds have passed.

opts.maxConcurrentBatches number
  • optional
  • default: 10

We process batches concurrently to increase parallelism while sending.

opts.pendingWorkCapacity number
  • optional
  • default: 10000

The maximum number of pending events we allow to accumulate in our sending queue before dropping them.

opts.maxResponseQueueSize number
  • optional
  • default: 1000

The maximum number of responses we enqueue before dropping them.

opts.disabled boolean
  • optional
  • default: false

Disable transmission of events to the specified apiHost, particularly useful for testing or development.

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.

Params:

NameTypeAttributeDescription
data Object | Map<string, any>

field->value mapping.

Return:

Libhoney

this libhoney instance.

Example:

using an object
  honey.add ({
    buildID: "a6cc38a1",
    env: "staging"
  });
using an ES2015 map
  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.

Params:

NameTypeAttributeDescription
name string

name of field to add.

fn function(): any

function that will be called to generate the value whenever an event is created.

Return:

Libhoney

this libhoney instance.

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:

NameTypeAttributeDescription
name string

name of field to add.

val any

value of field to add.

Return:

Libhoney

this libhoney instance.

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.

Params:

NameTypeAttributeDescription
fields Object | Map<string, any>

a field->value mapping to merge into the new builder.

dyn_fields Object | Map<string, any>

a field->dynamic function mapping to merge into the new builder.

Return:

Builder

a Builder instance

Example:

no additional fields/dyn_field
  let builder = honey.newBuilder();
additional fields/dyn_field
  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.

Return:

Event

an Event instance

Example:

adding data at send-time
  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.

Params:

NameTypeAttributeDescription
data Object | Map<string, any>

field->value mapping.

Return:

*

Example:

using an object
  honey.sendNow ({
    responseTime_ms: 100,
    httpStatusCode: 200
  });
using an ES2015 map
  let map = new Map();
  map.set("responseTime_ms", 100);
  map.set("httpStatusCode", 200);
  honey.sendNow (map);

Private Methods

private _responseCallback(responses: *) source

Params:

NameTypeAttributeDescription
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:

NameTypeAttributeDescription
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:

NameTypeAttributeDescription
event *

private validateEvent(event: *): Object source

validateEvent takes an event and validates its structure and contents.

Params:

NameTypeAttributeDescription
event *

Return:

Object

the validated libhoney Event. May return undefined if the event was invalid in some way or unable to be sent.