@fabbahiense/pulsar-pino-transport 0.3.0 → 0.4.0

package/dist/index.d.cts

@@ -1,5 +1,269 @@
 import * as pino_abstract_transport from 'pino-abstract-transport';
 import * as node_stream from 'node:stream';
+import { PinoLikeLogger } from './middleware.cjs';
+
+/**
+ * Distributed trace context shared by the Node.js SDKs (bundled into each
+ * SDK's dist; not public API by itself: each SDK re-exports what it offers).
+ *
+ * - The context of the operation in progress (`traceId`, `spanId`,
+ *   `parentSpanId`, the W3C `sampled` flag and `tracestate`) lives in an
+ *   `AsyncLocalStorage`. That store is shared through a process-wide registry,
+ *   so every SDK copy loaded in the process (pulsar-node, pulsar-next, the
+ *   pino helpers) sees the same context.
+ * - Inbound: W3C `traceparent` (with `tracestate`) and the legacy
+ *   `x-trace-id` header. An `x-trace-id` value always names the trace, as it
+ *   did before; a `traceparent` of the same trace supplies the parent span.
+ * - Outbound: `traceparent` plus `x-trace-id`, so services on older SDKs keep
+ *   following the same trace id.
+ * - Spans: `runSpan()` runs a function in a child span and reports it to a
+ *   sink when it settles; each SDK turns that into a span-end log entry.
+ *
+ * Every helper here is total where it touches the host's traffic: header
+ * parsing never throws, and instrumentation failures never break a request.
+ */
+
+/** The trace context of the operation in progress. */
+interface TraceContext {
+    /**
+     * Groups the entries of one distributed operation. Traces Pulsar starts use
+     * a W3C trace id (32 lowercase hex characters); an inbound `x-trace-id`
+     * value is kept exactly as it was sent.
+     */
+    traceId: string;
+    /** The current span: 16 lowercase hex characters. */
+    spanId: string;
+    /** The span this one is a child of, when it has one. */
+    parentSpanId?: string;
+    /** The W3C sampled flag, propagated as received. Pulsar sends every log regardless of it. */
+    sampled: boolean;
+    /** The inbound W3C `tracestate`, passed through unchanged to outgoing calls. */
+    traceState?: string;
+    /** HTTP method of the request, attached to entries that do not set their own. */
+    method?: string;
+    /** URL of the request, attached to entries that do not set their own. */
+    url?: string;
+}
+/** A context to run with: missing ids are generated (a new trace, a new span). */
+interface TraceContextInit {
+    traceId?: string;
+    spanId?: string;
+    parentSpanId?: string;
+    sampled?: boolean;
+    traceState?: string;
+    method?: string;
+    url?: string;
+}
+/**
+ * A trace context read from a carrier (headers, job data). `spanId` is the
+ * span that injected it; it is absent when the carrier only had an
+ * `x-trace-id`, so spans started under it have no parent.
+ */
+interface ExtractedTrace {
+    traceId: string;
+    spanId?: string;
+    sampled: boolean;
+    traceState?: string;
+}
+/** A parsed W3C `traceparent` header. */
+interface Traceparent {
+    /** Two lowercase hex characters; `00` today, later versions are accepted. */
+    version: string;
+    traceId: string;
+    /** The caller's span id (`parent-id` in the specification). */
+    parentId: string;
+    /** The trace-flags byte. */
+    flags: number;
+    /** Bit 0 of the flags. */
+    sampled: boolean;
+}
+type SpanKind = 'server' | 'client' | 'internal' | 'producer' | 'consumer';
+/** A span that ended, as handed to a {@link SpanSink}. */
+interface FinishedSpan {
+    /** The span's name; it becomes the entry's `msg`. */
+    name: string;
+    kind: SpanKind;
+    context: TraceContext;
+    /** Start and end, in epoch milliseconds (fractional). */
+    start: number;
+    end: number;
+    /** `end - start`, in milliseconds, rounded to 3 decimals. */
+    duration: number;
+    /** What the function threw or rejected with, if it failed. */
+    error?: unknown;
+    attributes?: Record<string, unknown>;
+    method?: string;
+    url?: string;
+    statusCode?: number;
+    serviceName?: string;
+}
+/** Receives finished spans; each SDK logs them as span-end entries. */
+type SpanSink = (span: FinishedSpan) => void;
+interface SpanOptions {
+    /**
+     * The span to start under. Defaults to the current context; pass the result
+     * of `extractTrace()` to continue a trace received through a queue, or
+     * `null` to start a new trace.
+     */
+    parent?: TraceContextInit | ExtractedTrace | null;
+    /** Stored as the entry's metadata. */
+    attributes?: Record<string, unknown>;
+    /** Default `internal`. */
+    kind?: SpanKind;
+    /** Service name of the span-end entry; defaults to the SDK's. */
+    serviceName?: string;
+}
+interface OutboundOptions {
+    /**
+     * Log one `client` span-end entry per call (method, URL without its query
+     * string, status, duration) and propagate that span, so the called service
+     * nests under it. Default true. With `false`, or when nothing can log it,
+     * the current span is propagated as it is.
+     */
+    spans?: boolean;
+    /** Service name of the client span entries; defaults to the SDK's. */
+    serviceName?: string;
+}
+/**
+ * Parses a W3C `traceparent` header. Returns null for anything the
+ * specification says to ignore: a malformed value, uppercase hex, version
+ * `ff`, a version-00 value with trailing data, or an all-zero trace or
+ * parent id. Later versions are accepted when their first four fields
+ * parse and anything after them starts with `-`.
+ */
+declare function parseTraceparent(value: unknown): Traceparent | null;
+/** Formats a version-00 `traceparent` for a context (ids converted to their W3C form). */
+declare function formatTraceparent(ctx: {
+    traceId: string;
+    spanId: string;
+    sampled?: boolean;
+}): string;
+/** The context of the current asynchronous flow, or null outside one. */
+declare function getTraceContext(): TraceContext | null;
+/**
+ * Runs `fn` with `ctx` as the current trace context (missing ids generated:
+ * pass null for a new trace). Every entry logged inside, including in async
+ * work started there, carries its ids.
+ */
+declare function runWithTrace<T>(ctx: TraceContextInit | ExtractedTrace | null | undefined, fn: () => T): T;
+/**
+ * Reads a trace context from headers or job data:
+ * - an `x-trace-id` names the trace, as it always has; a `traceparent` of the
+ *   same trace (compared through {@link toW3CTraceId}) supplies the span and
+ *   the sampled flag, and `tracestate` comes along;
+ * - otherwise a valid `traceparent` does;
+ * - otherwise null.
+ * The result is the span that sent it: start a child of it (the request
+ * middlewares, `startSpan(name, fn, { parent })`) or run in it (`runWithTrace`).
+ */
+declare function extractTrace(carrier: unknown): ExtractedTrace | null;
+/**
+ * The propagation headers for a context (default: the current one):
+ * `traceparent`, `x-trace-id`, and `tracestate` when the trace has one. Empty
+ * outside a trace. Spread them into any HTTP client's headers, for example
+ * Node's `http.request(url, { headers: { ...traceHeaders() } })`.
+ */
+declare function traceHeaders(ctx?: TraceContext | null): Record<string, string>;
+/**
+ * Writes the propagation fields of a context (default: the current one) into
+ * `carrier`, a plain object such as a job's data or anything with
+ * `set(name, value)` (fetch `Headers`, a `Map`). Returns the carrier. Outside
+ * a trace it is returned unchanged. The current span is injected as it is:
+ * the consumer's span becomes its child (see {@link extractTrace}).
+ */
+declare function injectTrace<T extends object>(carrier: T, ctx?: TraceContext | null): T;
+/** The parts of an axios instance the interceptor uses (axios is not a dependency). */
+interface AxiosLike {
+    interceptors: {
+        request: {
+            use(onFulfilled: (config: any) => any, onRejected?: (error: any) => any): unknown;
+        };
+        response: {
+            use(onFulfilled: (response: any) => any, onRejected?: (error: any) => any): unknown;
+        };
+    };
+}
+
+/**
+ * Distributed tracing for pino. pino runs this transport in a worker thread,
+ * where the application's AsyncLocalStorage is out of reach, so the trace ids
+ * have to be written into each record in the main thread: `pulsarMixin()`
+ * does that through pino's `mixin` option.
+ *
+ * @example
+ * ```ts
+ * import pino from 'pino'
+ * import { pulsarMixin } from '@fabbahiense/pulsar-pino-transport'
+ *
+ * const logger = pino({
+ *   mixin: pulsarMixin(),
+ *   transport: { target: '@fabbahiense/pulsar-pino-transport', options: { url, apiKey } },
+ * })
+ * ```
+ */
+
+/** The trace fields `pulsarMixin()` adds to a record. */
+interface PulsarMixinFields {
+    traceId?: string;
+    spanId?: string;
+    parentSpanId?: string;
+}
+/**
+ * A pino `mixin` that adds the current trace context to every record:
+ * `traceId`, `spanId` and `parentSpanId` (nothing outside a trace). It runs
+ * in the application's thread, so the ids travel with the record to the
+ * transport worker. Fields set on the log call itself win, as pino merges
+ * the mixin first.
+ *
+ * To combine it with a mixin of your own: `mixin: () => ({ ...pulsarMixin()(), ...mine() })`.
+ */
+declare function pulsarMixin(): () => PulsarMixinFields;
+/**
+ * Logs finished spans through a pino logger, as records the transport maps to
+ * span-end entries: `msg` the name, `responseTime` the duration, the span ids
+ * and `spanKind` top level, `req`/`res` for HTTP client spans, `err` when it
+ * failed, and the attributes as `metadata`.
+ */
+declare function pinoSpanSink(logger: PinoLikeLogger): SpanSink;
+/** Options of the pino `startSpan()`: the logger that writes the span-end entry. */
+interface PinoSpanOptions extends SpanOptions {
+    /** Your pino logger (with the Pulsar transport configured). */
+    logger: PinoLikeLogger;
+}
+/**
+ * Runs `fn` in a new child span of the current one (or of `options.parent`,
+ * or in a new trace) and logs its span-end entry through `options.logger`
+ * when it returns or settles. Records logged inside (with `pulsarMixin()`)
+ * carry the new span's ids. The result or error is passed through unchanged.
+ *
+ * @example
+ * ```ts
+ * await startSpan('payments.charge', () => charge(order), { logger })
+ * ```
+ */
+declare function startSpan<T>(name: string, fn: (span: TraceContext) => T, options: PinoSpanOptions): T;
+/** Options of the pino outbound helpers. */
+interface PinoOutboundOptions extends OutboundOptions {
+    /**
+     * Logs a `client` span-end entry per call through this logger. Without one,
+     * the current span is propagated as it is and nothing is logged.
+     */
+    logger?: PinoLikeLogger;
+}
+/**
+ * Returns a fetch that propagates the trace: calls made inside a trace send
+ * `traceparent`, `tracestate` and `x-trace-id` (and, with `logger`, log a
+ * `client` span). Calls outside a trace are untouched. Nothing is patched;
+ * the fetch to wrap defaults to the global fetch as it is when this is called.
+ */
+declare function instrumentFetch(options?: PinoOutboundOptions): typeof fetch;
+declare function instrumentFetch(fetchImpl: typeof fetch, options?: PinoOutboundOptions): typeof fetch;
+/**
+ * Adds interceptors to an axios instance (duck-typed: axios is not a
+ * dependency) that propagate the trace like {@link instrumentFetch}.
+ * Returns the instance.
+ */
+declare function instrumentAxios<T extends AxiosLike>(instance: T, options?: PinoOutboundOptions): T;
 
 interface PulsarTransportOptions {
     /** Pulsar server URL (e.g., 'https://pulsar.example.com') */
@@ -10,10 +274,20 @@ interface PulsarTransportOptions {
     source?: string;
     /** Alias for source */
     serviceName?: string;
-    /** Number of logs to buffer before flushing (default: 50) */
+    /** Buffered logs that trigger an immediate send (default: 50, max: 1000) */
     batchSize?: number;
-    /** Flush interval in milliseconds (default: 2000) */
+    /** Longest a log waits before it is sent, in milliseconds (default: 2000) */
     flushInterval?: number;
+    /** Most logs held in memory while the server is slow or down (default: 5000). When full, the oldest are dropped and counted. */
+    maxBufferSize?: number;
+    /** Retries of a failing batch (429, 408, 5xx, network, timeout) before it is dropped; a batch is sent at most `maxRetries + 1` times (default: 10) */
+    maxRetries?: number;
+    /** Timeout per HTTP request, in milliseconds (default: 10000) */
+    requestTimeout?: number;
+    /** Longest the final flush waits when the logger is closed, in milliseconds (default: 3000) */
+    shutdownTimeout?: number;
+    /** Write a line to stderr (at most once a minute) when logs are dropped (default: true) */
+    warnOnDrop?: boolean;
 }
 /**
  * Creates a Pino transport that sends logs to a Pulsar server.
@@ -21,7 +295,7 @@ interface PulsarTransportOptions {
  * @example
  * ```ts
  * import pino from 'pino'
- * import { createPulsarTransport } from '@pulsar/pino-transport'
+ * import { createPulsarTransport } from '@fabbahiense/pulsar-pino-transport'
  *
  * const logger = pino(
  *   createPulsarTransport({
@@ -47,4 +321,4 @@ declare function createPulsarTransport(options: PulsarTransportOptions): {
 };
 declare function export_default(options: PulsarTransportOptions): Promise<node_stream.Transform & pino_abstract_transport.OnUnknown>;
 
-export { type PulsarTransportOptions, createPulsarTransport, export_default as default };
+export { type AxiosLike, type ExtractedTrace, type OutboundOptions, PinoLikeLogger, type PinoOutboundOptions, type PinoSpanOptions, type PulsarMixinFields, type PulsarTransportOptions, type SpanKind, type SpanOptions, type TraceContext, type TraceContextInit, type Traceparent, createPulsarTransport, export_default as default, extractTrace, formatTraceparent, getTraceContext, injectTrace, instrumentAxios, instrumentFetch, parseTraceparent, pinoSpanSink, pulsarMixin, runWithTrace, startSpan, traceHeaders };

package/dist/index.d.ts

@@ -1,5 +1,269 @@
 import * as pino_abstract_transport from 'pino-abstract-transport';
 import * as node_stream from 'node:stream';
+import { PinoLikeLogger } from './middleware.js';
+
+/**
+ * Distributed trace context shared by the Node.js SDKs (bundled into each
+ * SDK's dist; not public API by itself: each SDK re-exports what it offers).
+ *
+ * - The context of the operation in progress (`traceId`, `spanId`,
+ *   `parentSpanId`, the W3C `sampled` flag and `tracestate`) lives in an
+ *   `AsyncLocalStorage`. That store is shared through a process-wide registry,
+ *   so every SDK copy loaded in the process (pulsar-node, pulsar-next, the
+ *   pino helpers) sees the same context.
+ * - Inbound: W3C `traceparent` (with `tracestate`) and the legacy
+ *   `x-trace-id` header. An `x-trace-id` value always names the trace, as it
+ *   did before; a `traceparent` of the same trace supplies the parent span.
+ * - Outbound: `traceparent` plus `x-trace-id`, so services on older SDKs keep
+ *   following the same trace id.
+ * - Spans: `runSpan()` runs a function in a child span and reports it to a
+ *   sink when it settles; each SDK turns that into a span-end log entry.
+ *
+ * Every helper here is total where it touches the host's traffic: header
+ * parsing never throws, and instrumentation failures never break a request.
+ */
+
+/** The trace context of the operation in progress. */
+interface TraceContext {
+    /**
+     * Groups the entries of one distributed operation. Traces Pulsar starts use
+     * a W3C trace id (32 lowercase hex characters); an inbound `x-trace-id`
+     * value is kept exactly as it was sent.
+     */
+    traceId: string;
+    /** The current span: 16 lowercase hex characters. */
+    spanId: string;
+    /** The span this one is a child of, when it has one. */
+    parentSpanId?: string;
+    /** The W3C sampled flag, propagated as received. Pulsar sends every log regardless of it. */
+    sampled: boolean;
+    /** The inbound W3C `tracestate`, passed through unchanged to outgoing calls. */
+    traceState?: string;
+    /** HTTP method of the request, attached to entries that do not set their own. */
+    method?: string;
+    /** URL of the request, attached to entries that do not set their own. */
+    url?: string;
+}
+/** A context to run with: missing ids are generated (a new trace, a new span). */
+interface TraceContextInit {
+    traceId?: string;
+    spanId?: string;
+    parentSpanId?: string;
+    sampled?: boolean;
+    traceState?: string;
+    method?: string;
+    url?: string;
+}
+/**
+ * A trace context read from a carrier (headers, job data). `spanId` is the
+ * span that injected it; it is absent when the carrier only had an
+ * `x-trace-id`, so spans started under it have no parent.
+ */
+interface ExtractedTrace {
+    traceId: string;
+    spanId?: string;
+    sampled: boolean;
+    traceState?: string;
+}
+/** A parsed W3C `traceparent` header. */
+interface Traceparent {
+    /** Two lowercase hex characters; `00` today, later versions are accepted. */
+    version: string;
+    traceId: string;
+    /** The caller's span id (`parent-id` in the specification). */
+    parentId: string;
+    /** The trace-flags byte. */
+    flags: number;
+    /** Bit 0 of the flags. */
+    sampled: boolean;
+}
+type SpanKind = 'server' | 'client' | 'internal' | 'producer' | 'consumer';
+/** A span that ended, as handed to a {@link SpanSink}. */
+interface FinishedSpan {
+    /** The span's name; it becomes the entry's `msg`. */
+    name: string;
+    kind: SpanKind;
+    context: TraceContext;
+    /** Start and end, in epoch milliseconds (fractional). */
+    start: number;
+    end: number;
+    /** `end - start`, in milliseconds, rounded to 3 decimals. */
+    duration: number;
+    /** What the function threw or rejected with, if it failed. */
+    error?: unknown;
+    attributes?: Record<string, unknown>;
+    method?: string;
+    url?: string;
+    statusCode?: number;
+    serviceName?: string;
+}
+/** Receives finished spans; each SDK logs them as span-end entries. */
+type SpanSink = (span: FinishedSpan) => void;
+interface SpanOptions {
+    /**
+     * The span to start under. Defaults to the current context; pass the result
+     * of `extractTrace()` to continue a trace received through a queue, or
+     * `null` to start a new trace.
+     */
+    parent?: TraceContextInit | ExtractedTrace | null;
+    /** Stored as the entry's metadata. */
+    attributes?: Record<string, unknown>;
+    /** Default `internal`. */
+    kind?: SpanKind;
+    /** Service name of the span-end entry; defaults to the SDK's. */
+    serviceName?: string;
+}
+interface OutboundOptions {
+    /**
+     * Log one `client` span-end entry per call (method, URL without its query
+     * string, status, duration) and propagate that span, so the called service
+     * nests under it. Default true. With `false`, or when nothing can log it,
+     * the current span is propagated as it is.
+     */
+    spans?: boolean;
+    /** Service name of the client span entries; defaults to the SDK's. */
+    serviceName?: string;
+}
+/**
+ * Parses a W3C `traceparent` header. Returns null for anything the
+ * specification says to ignore: a malformed value, uppercase hex, version
+ * `ff`, a version-00 value with trailing data, or an all-zero trace or
+ * parent id. Later versions are accepted when their first four fields
+ * parse and anything after them starts with `-`.
+ */
+declare function parseTraceparent(value: unknown): Traceparent | null;
+/** Formats a version-00 `traceparent` for a context (ids converted to their W3C form). */
+declare function formatTraceparent(ctx: {
+    traceId: string;
+    spanId: string;
+    sampled?: boolean;
+}): string;
+/** The context of the current asynchronous flow, or null outside one. */
+declare function getTraceContext(): TraceContext | null;
+/**
+ * Runs `fn` with `ctx` as the current trace context (missing ids generated:
+ * pass null for a new trace). Every entry logged inside, including in async
+ * work started there, carries its ids.
+ */
+declare function runWithTrace<T>(ctx: TraceContextInit | ExtractedTrace | null | undefined, fn: () => T): T;
+/**
+ * Reads a trace context from headers or job data:
+ * - an `x-trace-id` names the trace, as it always has; a `traceparent` of the
+ *   same trace (compared through {@link toW3CTraceId}) supplies the span and
+ *   the sampled flag, and `tracestate` comes along;
+ * - otherwise a valid `traceparent` does;
+ * - otherwise null.
+ * The result is the span that sent it: start a child of it (the request
+ * middlewares, `startSpan(name, fn, { parent })`) or run in it (`runWithTrace`).
+ */
+declare function extractTrace(carrier: unknown): ExtractedTrace | null;
+/**
+ * The propagation headers for a context (default: the current one):
+ * `traceparent`, `x-trace-id`, and `tracestate` when the trace has one. Empty
+ * outside a trace. Spread them into any HTTP client's headers, for example
+ * Node's `http.request(url, { headers: { ...traceHeaders() } })`.
+ */
+declare function traceHeaders(ctx?: TraceContext | null): Record<string, string>;
+/**
+ * Writes the propagation fields of a context (default: the current one) into
+ * `carrier`, a plain object such as a job's data or anything with
+ * `set(name, value)` (fetch `Headers`, a `Map`). Returns the carrier. Outside
+ * a trace it is returned unchanged. The current span is injected as it is:
+ * the consumer's span becomes its child (see {@link extractTrace}).
+ */
+declare function injectTrace<T extends object>(carrier: T, ctx?: TraceContext | null): T;
+/** The parts of an axios instance the interceptor uses (axios is not a dependency). */
+interface AxiosLike {
+    interceptors: {
+        request: {
+            use(onFulfilled: (config: any) => any, onRejected?: (error: any) => any): unknown;
+        };
+        response: {
+            use(onFulfilled: (response: any) => any, onRejected?: (error: any) => any): unknown;
+        };
+    };
+}
+
+/**
+ * Distributed tracing for pino. pino runs this transport in a worker thread,
+ * where the application's AsyncLocalStorage is out of reach, so the trace ids
+ * have to be written into each record in the main thread: `pulsarMixin()`
+ * does that through pino's `mixin` option.
+ *
+ * @example
+ * ```ts
+ * import pino from 'pino'
+ * import { pulsarMixin } from '@fabbahiense/pulsar-pino-transport'
+ *
+ * const logger = pino({
+ *   mixin: pulsarMixin(),
+ *   transport: { target: '@fabbahiense/pulsar-pino-transport', options: { url, apiKey } },
+ * })
+ * ```
+ */
+
+/** The trace fields `pulsarMixin()` adds to a record. */
+interface PulsarMixinFields {
+    traceId?: string;
+    spanId?: string;
+    parentSpanId?: string;
+}
+/**
+ * A pino `mixin` that adds the current trace context to every record:
+ * `traceId`, `spanId` and `parentSpanId` (nothing outside a trace). It runs
+ * in the application's thread, so the ids travel with the record to the
+ * transport worker. Fields set on the log call itself win, as pino merges
+ * the mixin first.
+ *
+ * To combine it with a mixin of your own: `mixin: () => ({ ...pulsarMixin()(), ...mine() })`.
+ */
+declare function pulsarMixin(): () => PulsarMixinFields;
+/**
+ * Logs finished spans through a pino logger, as records the transport maps to
+ * span-end entries: `msg` the name, `responseTime` the duration, the span ids
+ * and `spanKind` top level, `req`/`res` for HTTP client spans, `err` when it
+ * failed, and the attributes as `metadata`.
+ */
+declare function pinoSpanSink(logger: PinoLikeLogger): SpanSink;
+/** Options of the pino `startSpan()`: the logger that writes the span-end entry. */
+interface PinoSpanOptions extends SpanOptions {
+    /** Your pino logger (with the Pulsar transport configured). */
+    logger: PinoLikeLogger;
+}
+/**
+ * Runs `fn` in a new child span of the current one (or of `options.parent`,
+ * or in a new trace) and logs its span-end entry through `options.logger`
+ * when it returns or settles. Records logged inside (with `pulsarMixin()`)
+ * carry the new span's ids. The result or error is passed through unchanged.
+ *
+ * @example
+ * ```ts
+ * await startSpan('payments.charge', () => charge(order), { logger })
+ * ```
+ */
+declare function startSpan<T>(name: string, fn: (span: TraceContext) => T, options: PinoSpanOptions): T;
+/** Options of the pino outbound helpers. */
+interface PinoOutboundOptions extends OutboundOptions {
+    /**
+     * Logs a `client` span-end entry per call through this logger. Without one,
+     * the current span is propagated as it is and nothing is logged.
+     */
+    logger?: PinoLikeLogger;
+}
+/**
+ * Returns a fetch that propagates the trace: calls made inside a trace send
+ * `traceparent`, `tracestate` and `x-trace-id` (and, with `logger`, log a
+ * `client` span). Calls outside a trace are untouched. Nothing is patched;
+ * the fetch to wrap defaults to the global fetch as it is when this is called.
+ */
+declare function instrumentFetch(options?: PinoOutboundOptions): typeof fetch;
+declare function instrumentFetch(fetchImpl: typeof fetch, options?: PinoOutboundOptions): typeof fetch;
+/**
+ * Adds interceptors to an axios instance (duck-typed: axios is not a
+ * dependency) that propagate the trace like {@link instrumentFetch}.
+ * Returns the instance.
+ */
+declare function instrumentAxios<T extends AxiosLike>(instance: T, options?: PinoOutboundOptions): T;
 
 interface PulsarTransportOptions {
     /** Pulsar server URL (e.g., 'https://pulsar.example.com') */
@@ -10,10 +274,20 @@ interface PulsarTransportOptions {
     source?: string;
     /** Alias for source */
     serviceName?: string;
-    /** Number of logs to buffer before flushing (default: 50) */
+    /** Buffered logs that trigger an immediate send (default: 50, max: 1000) */
     batchSize?: number;
-    /** Flush interval in milliseconds (default: 2000) */
+    /** Longest a log waits before it is sent, in milliseconds (default: 2000) */
     flushInterval?: number;
+    /** Most logs held in memory while the server is slow or down (default: 5000). When full, the oldest are dropped and counted. */
+    maxBufferSize?: number;
+    /** Retries of a failing batch (429, 408, 5xx, network, timeout) before it is dropped; a batch is sent at most `maxRetries + 1` times (default: 10) */
+    maxRetries?: number;
+    /** Timeout per HTTP request, in milliseconds (default: 10000) */
+    requestTimeout?: number;
+    /** Longest the final flush waits when the logger is closed, in milliseconds (default: 3000) */
+    shutdownTimeout?: number;
+    /** Write a line to stderr (at most once a minute) when logs are dropped (default: true) */
+    warnOnDrop?: boolean;
 }
 /**
  * Creates a Pino transport that sends logs to a Pulsar server.
@@ -21,7 +295,7 @@ interface PulsarTransportOptions {
  * @example
  * ```ts
  * import pino from 'pino'
- * import { createPulsarTransport } from '@pulsar/pino-transport'
+ * import { createPulsarTransport } from '@fabbahiense/pulsar-pino-transport'
  *
  * const logger = pino(
  *   createPulsarTransport({
@@ -47,4 +321,4 @@ declare function createPulsarTransport(options: PulsarTransportOptions): {
 };
 declare function export_default(options: PulsarTransportOptions): Promise<node_stream.Transform & pino_abstract_transport.OnUnknown>;
 
-export { type PulsarTransportOptions, createPulsarTransport, export_default as default };
+export { type AxiosLike, type ExtractedTrace, type OutboundOptions, PinoLikeLogger, type PinoOutboundOptions, type PinoSpanOptions, type PulsarMixinFields, type PulsarTransportOptions, type SpanKind, type SpanOptions, type TraceContext, type TraceContextInit, type Traceparent, createPulsarTransport, export_default as default, extractTrace, formatTraceparent, getTraceContext, injectTrace, instrumentAxios, instrumentFetch, parseTraceparent, pinoSpanSink, pulsarMixin, runWithTrace, startSpan, traceHeaders };