librato-ts/dist/index.d.ts

Client for Librato Metrics (https://metrics.librato.com/)

import { EventEmitter } from 'node:events';
import { StrictEventEmitter } from 'strict-event-emitter-types';

interface Annotation {
    /**
     * The description contains extra metadata about a particular annotation.
     * E.g. `Deployed 9b562b2: shipped new feature foo!`
     */
    description?: string;
    /**
     * The unix timestamp indicating the time at which the event referenced by this annotation started.
     * By default, this is set to the current time if not specified.
     */
    startTime?: Date;
    /**
     * The unix timestamp indicating the time at which the event referenced by this annotation ended. For events that
     * have a duration, this is a useful way to annotate the duration of the event.
     */
    endTime?: Date;
    /**
     * Metric stream name used to categorize annotations. If not specified, the title of the annotation is used.
     */
    streamName?: string;
    /**
     * An optional list of references to resources associated with the particular annotation.
     * For example, these links could point to a build page in a CI system or a changeset description of an SCM.
     */
    links?: AnnotationLink[];
    /**
     * A string which describes the originating source of an annotation when that annotation is tracked across
     * multiple members of a population.
     */
    source?: string;
}
interface AnnotationLink {
    href: string;
    label?: string;
    rel?: string;
}

declare function getMillisecondsFromHrTime(hrtime: [number, number]): number;
declare function sanitizeMeasurementName(name: string): string;
declare function sanitizeAnnotationStreamName(name: string): string;
declare function sanitizeTagName(name: string): string;
declare function sanitizeTagValue(name: string): string;
declare function sanitizeTags(tags?: Record<string, string>): Record<string, string> | undefined;

interface SimulateConfig {
    simulate: true;
}
interface ClientConfig {
    simulate?: false;
    email: string;
    token: string;
    /**
     * Metric name prefix to apply to all measurements
     */
    prefix?: string;
    /**
     * Amount of time in milliseconds to wait between flushes. Default is 60s
     */
    period?: number;
    /**
     * Amount of time in milliseconds before the request times out. Default is 30s
     */
    timeout?: number;
    /**
     * Number of times to retry sending metrics to Librato. Default is 3
     */
    retryCount?: number;
    /**
     * Source dimension to apply to all measurements
     */
    source?: string;
}

interface Measurement$1 {
    /**
     * The unique identifying name of the property being tracked. The metric name is used both to create new measurements and query existing measurements. Must be 255 or fewer characters, and may only consist of ‘A-Za-z0-9.:-_’. The metric namespace is case-insensitive.
     */
    name: string;
    /**
     * Unix Time (epoch seconds). This defines the time that a measurement is recorded at. It is useful when sending measurements from multiple hosts to align them on a given time boundary, eg. time=floor(Time.now, 60) to align samples on a 60-second tick.
     */
    time?: number;
    /**
     * Define the period for the metric. This will be persisted for new metrics and used as the metric period for metrics marked for Service-Side Aggregation.
     */
    period?: number;
    /**
     * Source dimension
     * NOTE: This is a legacy approach for adding a dimension to a metric. Accounts created after January 24th, 2017 12:00 PST should use tags instead. See https://www.librato.com/docs/kb/faq/account_questions/tags_or_sources/ for more information.
     */
    source?: string;
    /**
     * A set of key/value pairs that describe the particular data stream. Tags behave as extra dimensions that data streams can be filtered and aggregated along.
     *
     * Tag names must match the regular expression /\A[-.:_\w]{1,64}\z/. Tag names are always converted to lower case.
     *
     * Tag values must match the regular expression /\A[-.:_?\\\/\w ]{1,255}\z/. Tag values are always converted to lower case.
     *
     * Data streams have a default limit of 50 tag names per measurement.
     *
     * Users should be mindful of the maximum cardinality of their full tag set over all measurements.
     * Each unique set of pairs is a new unique stream and is billed as such.
     * The full cardinality of a metric is the permutation of all possible values of tags over the billing period.
     * For example, if you have two tags on your measurements and the first tag has 20 possible values and the second tag has 30 possible values,
     * then your potential tag cardinality could be 20 * 30 => 600 data streams.
     * This would be billed as 600 individual streams over the billing duration of one hour.
     */
    tags?: Record<string, string>;
}

interface SingleMeasurement extends Measurement$1 {
    /**
     * The numeric value of a single measured sample.
     */
    value: number;
}

declare class CounterCollector {
    private cache;
    increment(measurement: Measurement$1 & Partial<SingleMeasurement>): void;
    flush(): SingleMeasurement[];
}

interface GaugeAggregateMeasurement extends Measurement$1 {
    /**
     * Indicates the request corresponds to a multi-sample measurement.
     */
    count: number;
    /**
     * The summation of the individual measurements. The combination of count and sum are used to calculate an average value for the recorded metric measurement.
     */
    sum: number;
    /**
     * Used to report the largest individual measurement amongst the averaged set.
     */
    max: number;
    /**
     * Used to report the smallest individual measurement amongst the averaged set.
     */
    min: number;
    /**
     * Represents the last value seen in the interval. Useful when tracking derivatives over points in time.
     */
    last: number;
    /**
     * Represents the population standard deviation of the sample set.
     */
    stddev?: number;
}

type Measurement = GaugeAggregateMeasurement | SingleMeasurement;
declare class GaugeCollector {
    private cache;
    measure(measurement: SingleMeasurement): void;
    flush(): Measurement[];
}

interface LibratoEvents {
    error: (error: Error) => void;
    sending: (args: SendMetricsParams) => void;
    sent: (args: SentMetricsParams) => void;
}
type LibratoEventEmitter = StrictEventEmitter<EventEmitter, LibratoEvents>;
type MeasurementOptions = Omit<Measurement$1, 'name'>;
interface SendMetricsParams {
    counters: SingleMeasurement[];
    gauges: Measurement$1[];
}
interface SentMetricsParams extends SendMetricsParams {
    /**
     * Duration in milliseconds of the request to Librato
     */
    duration: number;
}
declare const Librato_base: new () => LibratoEventEmitter;
declare class Librato extends Librato_base {
    private client;
    private config;
    private counterCollector;
    private gaugeCollector;
    private isEnding;
    private startTimeout?;
    /**
     * Initializes the Librato client and starts sending measurements to Librato.
     * @param {object} config
     */
    init(config: ClientConfig | SimulateConfig): void;
    /**
     * Flushes any queued measurements to Librato and stops the process of sending measurements to Librato
     */
    end(): Promise<void>;
    /**
     * Increment a value that accumulates over time – you can think of this like an odometer on a car; it only ever goes up.
     * @param {string} name - Name of the metric
     * @param {object} options
     */
    increment(name: string, options?: MeasurementOptions): void;
    /**
     * Increment a value that accumulates over time – you can think of this like an odometer on a car; it only ever goes up.
     * @param {string} name - Name of the metric
     * @param {number} value - Amount to increment by
     * @param {object} options
     */
    increment(name: string, value: number, options?: MeasurementOptions): void;
    /**
     * Measures a current value at the time it is read. An example would be the fuel gauge in a vehicle.
     * @param {string} name - Name of the metric
     * @param {number} value - Value of the gauge metric
     * @param {object} options
     */
    measure(name: string, value: number, options?: MeasurementOptions): void;
    annotate(title: string, options: Annotation): Promise<void>;
    flush(): Promise<void> | void;
    _sendMetrics({ counters, gauges }: SendMetricsParams): Promise<void>;
    private run;
}

export { type Annotation, type AnnotationLink, type ClientConfig, CounterCollector, type GaugeAggregateMeasurement, GaugeCollector, Librato, type Measurement$1 as Measurement, type SendMetricsParams, type SentMetricsParams, type SimulateConfig, type SingleMeasurement, getMillisecondsFromHrTime, sanitizeAnnotationStreamName, sanitizeMeasurementName, sanitizeTagName, sanitizeTagValue, sanitizeTags };