@fluent-org/logger/build/src/client.d.ts

A node fluent protocol compatible logger

import EventTime from "./event_time";
import * as protocol from "./protocol";
import { FluentAuthOptions } from "./auth";
import { FluentSocketOptions, FluentSocketEvent } from "./socket";
import { EventRetryOptions } from "./event_retrier";
/**
 * The set of accepted event modes. See [Forward protocol spec](https://github.com/fluent/fluentd/wiki/Forward-Protocol-Specification-v1#event-modes)
 *
 * `Message` will send each event to FluentD individually.
 *
 * `Forward` will collect the events together by tag, and send them together to FluentD in a single packet.
 * This is more efficient with a `flushInterval` to batch these together.
 *
 * `PackedForward` will behave the same as `Forward`, but will pack the events as part of entering the queue. This saves memory and bandwidth.
 *
 * `CompressedPackedForward` will behave the same as `PackedForward`, but additionally compress the items before emission, saving more bandwidth.
 */
export declare type EventModes = "Message" | "Forward" | "PackedForward" | "CompressedPackedForward";
/**
 * The set of accepted Timestamp values
 */
export declare type Timestamp = number | Date | EventTime;
/**
 * Acknowledgement settings
 */
export declare type AckOptions = {
    /**
     * How long to wait for an acknowledgement from the server
     */
    ackTimeout: number;
};
export declare type SendQueueLimit = {
    /**
     * The queue size limit (memory)
     *
     * This checks the memory size of the queue, which is only useful with `PackedForward` and `PackedForwardCompressed`.
     *
     * Defaults to +Infinity
     */
    size: number;
    /**
     * The queue length limit (# of entries)
     *
     * This checks the number of events in the queue, which is useful with all event modes.
     *
     * Defaults to +Infinity
     */
    length: number;
};
export declare type DisconnectOptions = {
    /**
     * If to wait for all pending events to finish sending to the fluent server before disconnecting
     *
     * Defaults to false (does not wait)
     */
    waitForPending: boolean;
    /**
     * The maximum amount of time to wait for pending events to finish sending to the fluent server before disconnecting
     *
     * Defaults to 0 (no maximum time)
     */
    waitForPendingDelay: number;
    /**
     * The amount of time to wait before disconnecting the socket on disconnection
     *
     * Useful to wait for acknowledgements on final flush
     *
     * Defaults to 0
     */
    socketDisconnectDelay: number;
};
/**
 * The constructor options passed to the client
 */
export declare type FluentClientOptions = {
    /**
     * The event mode to use. Defaults to PackedForward
     */
    eventMode?: EventModes;
    /**
     * The connection options. See subtype for defaults.
     */
    socket?: FluentSocketOptions;
    /**
     * The fluentd security options. See subtype for defaults.
     */
    security?: FluentAuthOptions;
    /**
     * Acknowledgement settings.
     */
    ack?: Partial<AckOptions>;
    /**
     * The timestamp resolution of events passed to FluentD.
     *
     * Passing false here means that the timestamps will be emitted as numbers (unless you explicitly provide an EventTime)
     * Passing true means that timestamps will alwyas be emitted as EventTime object instances. This includes timestamps
     *
     * Defaults to false (seconds). If true, the resolution will be in milliseconds.
     */
    milliseconds?: boolean;
    /**
     * How long to wait to flush the queued events
     *
     * If this is 0, we don't wait at all
     *
     * Defaults to 0
     */
    flushInterval?: number;
    /**
     * The limit at which the queue needs to be flushed.
     *
     * Used when flushInterval is > 0 to say "flush after flushInterval ms, or when the queue reaches X size"
     *
     * See the subtype for defaults
     */
    sendQueueIntervalFlushLimit?: Partial<SendQueueLimit>;
    /**
     * The limit at which we flush synchronously. By default, we flush asynchronously,
     * which can be bad if we're sending 30k+ events at a time.
     *
     * This sets a size limit at which we flush synchronously within emit(), which makes
     * sure we're flushing as quickly as possible
     *
     * Defaults to null (no limit)
     *
     * See the subtype for defaults
     */
    sendQueueSyncFlushLimit?: Partial<SendQueueLimit>;
    /**
     * The limit at which we start dropping events
     *
     * Prevents the queue from growing to an unbounded size and exhausting memory.
     *
     * See the subtype for defaults
     */
    sendQueueMaxLimit?: Partial<SendQueueLimit>;
    /**
     * The limit at which we start dropping events when we're not writable
     *
     * Prevents the queue from growing too much when fluentd is down for an extended period
     *
     * Defaults to null (no limit)
     *
     * See the subtype for defaults
     */
    sendQueueNotFlushableLimit?: Partial<SendQueueLimit>;
    /**
     * The delay after which we're not writable to start flushing events.
     * Useful to make sure we don't drop events during short blips
     *
     * Defaults to 0 (no delay)
     */
    sendQueueNotFlushableLimitDelay?: number;
    /**
     * Retry event submission on failure
     *
     * Warning: This effectively keeps the event in memory until it is successfully sent or retries exhausted
     *
     * See subtype for defaults
     */
    eventRetry?: Partial<EventRetryOptions>;
    /**
     * Options to control disconnection behavior
     *
     * How many times to try to flush before disconnecting, wait times, etc
     *
     * See subtype for defaults
     */
    disconnect?: Partial<DisconnectOptions>;
    /**
     * Disable connection on client creation. Expects the client to call .connect to start sending messages.
     *
     * Defaults to false
     */
    disableAutoconnect?: boolean;
};
/**
 * A Fluent Client. Connects to a FluentD server using the [Forward protocol](https://github.com/fluent/fluentd/wiki/Forward-Protocol-Specification-v1).
 */
export declare class FluentClient {
    private tag_prefix;
    private eventMode;
    private ackEnabled;
    private ackOptions;
    private ackQueue;
    private sendQueue;
    private emitQueue;
    private milliseconds;
    private retrier;
    private socket;
    private flushInterval;
    private sendQueueIntervalFlushLimit;
    private sendQueueSyncFlushLimit;
    private sendQueueMaxLimit;
    private sendQueueNotFlushableLimit;
    private sendQueueNotFlushableLimitDelay;
    private notFlushableLimitTimeoutId;
    private nextFlushTimeoutId;
    private flushing;
    private willFlushNextTick;
    private disconnectOptions;
    /**
     * Creates a new FluentClient
     *
     * @param tag_prefix A prefix to prefix to all tags. For example, passing the prefix "foo" will cause `emit("bar", data)` to emit with `foo.bar`.
     * @param options The client options
     */
    constructor(tag_prefix?: string | null, options?: FluentClientOptions);
    /**
     * Attaches an event listener to the underlying socket
     *
     * See FluentSocketEvent for more info
     */
    socketOn(event: FluentSocketEvent, listener: (...args: any[]) => void): void;
    /**
     * Constructs a new socket
     *
     * @param security The security options, if any
     * @param options The socket options, if any
     * @returns A new FluentSocket
     */
    private createSocket;
    /**
     * Emits an event to the Fluent Server
     *
     * @param data The event to emit (required)
     * @returns A Promise, which resolves when the event is successfully sent to the server.
     *  Enabling acknowledgements waits until the server indicates they have received the event.
     */
    emit(data: protocol.EventRecord): Promise<void>;
    /**
     * Emits an event to the Fluent Server
     *
     * @param data The event to emit (required)
     * @param timestamp A millisecond resolution timestamp to associate with the event (optional)
     * @returns A Promise, which resolves when the event is successfully sent to the server.
     *  Enabling acknowledgements waits until the server indicates they have received the event.
     */
    emit(data: protocol.EventRecord, timestamp: Timestamp): Promise<void>;
    /**
     * Emits an event to the Fluent Server
     *
     * @param label The label to emit the data with (optional)
     * @param data The event to emit (required)
     * @returns A Promise, which resolves when the event is successfully sent to the server.
     *  Enabling acknowledgements waits until the server indicates they have received the event.
     */
    emit(label: string, data: protocol.EventRecord): Promise<void>;
    /**
     * Emits an event to the Fluent Server
     *
     * @param label The label to emit the data with (optional)
     * @param data The event to emit (required)
     * @param timestamp A millisecond resolution timestamp to associate with the event (optional)
     * @returns A Promise, which resolves when the event is successfully sent to the server.
     *  Enabling acknowledgements waits until the server indicates they have received the event.
     */
    emit(label: string, data: protocol.EventRecord, timestamp: Timestamp): Promise<void>;
    /**
     * Pushes an event onto the sendQueue
     *
     * Also drops items from the queue if it is too large (size/length)
     *
     * @param tag The event tag
     * @param time The event timestamp
     * @param data The event data
     * @returns The promise from the sendQueue
     */
    private pushEvent;
    /**
     * Called once the underlying socket is writable
     *
     * Should attempt a flush
     */
    private handleWritable;
    /**
     * Connects the client. Can happen automatically during construction, but can be called after a `disconnect()` to resume the client.
     */
    connect(): Promise<void>;
    /**
     * Closes the socket, and clears both the ackQueue and the sendQueue, rejecting all pending events.
     *
     * For use during shutdown events, where we don't plan on reconnecting
     */
    shutdown(): Promise<void>;
    /**
     * Closes the socket and clears the ackQueue. Keeps pending events, which can be sent via a later .connect()
     */
    disconnect(): Promise<void>;
    /**
     * Creates a tag from the passed label and the constructor `tagPrefix`.
     *
     * @param label The label to create a tag from
     * @returns The constructed tag, or `null`.
     */
    private makeTag;
    /**
     * Flushes to the socket synchronously
     *
     * Prefer calling `.flush` which will flush on the next tick, allowing events from this tick to queue up.
     *
     * @returns true if there are more events in the queue to flush, false otherwise
     */
    syncFlush(): boolean;
    /**
     * Flushes the event queue. Queues up the flushes for the next tick, preventing multiple flushes at the same time.
     *
     * @returns A promise, which resolves with a boolean indicating if there are more events to flush.
     */
    flush(): Promise<boolean>;
    /**
     * Potentially triggers a flush
     *
     * If we're flushing on an interval, check if the queue (size/length) limits have been reached, and otherwise schedule a new flush
     *
     * If not, just flush
     * @returns
     */
    private maybeFlush;
    /**
     * Drops events until the send queue is below the specified limits
     *
     * @param limit The limit to enforce
     */
    private dropLimit;
    /**
     * Checks if the sendQueue hits this limit
     * @param limit the limit to check
     */
    private shouldLimit;
    /**
     * Send the front item of the queue to the socket
     * @returns True if there was something to send
     */
    private sendNext;
    /**
     * Creates an event for how long to wait for the ack
     *
     * @param chunkId The chunk ID we're waiting to ack
     * @param deferred The deferred to reject on timeout
     * @param ackTimeout The timeout length
     * @returns
     */
    private setupAckTimeout;
    /**
     * Called on an acknowledgement from the socket
     *
     * @param chunkId The chunk ID the socket has acknowledged
     * @returns
     */
    private handleAck;
    /**
     * Fails all acknowledgements
     * Called on shutdown
     *
     * @returns a Promise which resolves once all the handlers depending on the ack result have resolved
     */
    private clearAcks;
    /**
     * Returns the number of queued events that haven't been sent yet
     *
     * Useful to react if we're queuing up too many events within a single tick
     */
    get sendQueueLength(): number;
    /**
     * Returns whether or not the socket is writable
     *
     * Useful to react if we're disconnected for any reason
     */
    get writable(): boolean;
    /**
     * Returns the number of events that have been queued, but haven't resolved yet
     *
     * This includes acknowledgements and retries if enabled.
     */
    get queueLength(): number;
    /**
     * Waits for all currently pending events to successfully resolve or reject
     *
     * @returns A Promise which resolves once all the pending events have successfully been emitted
     */
    waitForPending(): Promise<void>;
}