import type { Plugin } from './app';
/** A set of label values keyed by label name. */
export type Labels = Record<string, string>;
/** Default histogram buckets (seconds), matching common HTTP-latency defaults. */
export declare const DEFAULT_BUCKETS: readonly number[];
interface Metric {
    readonly name: string;
    render(): string;
}
/** A monotonically increasing counter. */
export declare class Counter implements Metric {
    /** Metric name as exposed in the Prometheus output. */
    readonly name: string;
    /** Help text emitted on the `# HELP` line. */
    readonly help: string;
    /**
     * Label names whose values identify each series; only these are recorded
     * (extras dropped, any omitted at increment become `""`). Keep cardinality
     * low — every distinct value combination is a separate retained series.
     */
    readonly labelNames: readonly string[];
    private readonly series;
    /**
     * Prefer {@link MetricsRegistry.counter}, which registers idempotently by name;
     * construct directly only for a standalone counter not shared via a registry.
     */
    constructor(
    /** Metric name as exposed in the Prometheus output. */
    name: string, 
    /** Help text emitted on the `# HELP` line. */
    help: string, 
    /**
     * Label names whose values identify each series; only these are recorded
     * (extras dropped, any omitted at increment become `""`). Keep cardinality
     * low — every distinct value combination is a separate retained series.
     */
    labelNames?: readonly string[]);
    /**
     * Add `value` (default 1, must be ≥ 0) to the series for `labels`. Counters
     * never decrease; pass a positive delta, not the running total.
     *
     * @param labels - Values for the declared {@link labelNames}; picks/creates the series.
     * @param value - Non-negative amount to add (default 1); a negative value throws.
     */
    inc(labels?: Labels, value?: number): void;
    /**
     * Render this counter in Prometheus exposition format.
     *
     * @returns The `# HELP`/`# TYPE` header and one line per series.
     */
    render(): string;
}
/** A value that can go up or down. */
export declare class Gauge implements Metric {
    /** Metric name as exposed in the Prometheus output. */
    readonly name: string;
    /** Help text emitted on the `# HELP` line. */
    readonly help: string;
    /**
     * Label names whose values identify each series; only these are recorded
     * (extras dropped, any omitted become `""`). Keep cardinality low — every
     * distinct value combination is a separate retained series.
     */
    readonly labelNames: readonly string[];
    private readonly series;
    /**
     * Prefer {@link MetricsRegistry.gauge}, which registers idempotently by name;
     * construct directly only for a standalone gauge not shared via a registry.
     */
    constructor(
    /** Metric name as exposed in the Prometheus output. */
    name: string, 
    /** Help text emitted on the `# HELP` line. */
    help: string, 
    /**
     * Label names whose values identify each series; only these are recorded
     * (extras dropped, any omitted become `""`). Keep cardinality low — every
     * distinct value combination is a separate retained series.
     */
    labelNames?: readonly string[]);
    private at;
    /**
     * Set the series for `labels` to `value`.
     *
     * @param labels - Values for the declared {@link labelNames}; picks/creates the series.
     * @param value - The new absolute value; a gauge holds any number, including negatives and fractions (unlike a counter).
     */
    set(labels: Labels, value: number): void;
    /**
     * Add `value` (default 1) to the series for `labels`.
     *
     * @param labels - Values for the declared {@link labelNames}; picks/creates the series.
     * @param value - Amount to add (default 1); pass a negative number to subtract.
     */
    inc(labels?: Labels, value?: number): void;
    /**
     * Subtract `value` (default 1) from the series for `labels`.
     *
     * @param labels - Values for the declared {@link labelNames}; picks/creates the series.
     * @param value - Amount to subtract (default 1); the series may go negative.
     */
    dec(labels?: Labels, value?: number): void;
    /**
     * Render this gauge in Prometheus exposition format.
     *
     * @returns The `# HELP`/`# TYPE` header and one line per series.
     */
    render(): string;
}
/** A cumulative histogram of observed values. */
export declare class Histogram implements Metric {
    /** Metric name as exposed in the Prometheus output. */
    readonly name: string;
    /** Help text emitted on the `# HELP` line. */
    readonly help: string;
    /**
     * Label names whose values identify each series; only these are recorded
     * (extras dropped, any omitted become `""`). Keep cardinality low — every
     * distinct value combination is a separate retained series.
     */
    readonly labelNames: readonly string[];
    /**
     * Bucket upper bounds, sorted ascending at construction; an observation counts
     * in a bucket when it is `<=` the bound. An implicit `+Inf` bucket is always
     * emitted, so these need not span the full range.
     */
    readonly buckets: number[];
    private readonly series;
    /**
     * Prefer {@link MetricsRegistry.histogram}, which registers idempotently by
     * name; construct directly only for a standalone histogram not shared via a
     * registry. The `buckets` argument is copied and sorted, so ordering is free.
     */
    constructor(
    /** Metric name as exposed in the Prometheus output. */
    name: string, 
    /** Help text emitted on the `# HELP` line. */
    help: string, 
    /**
     * Label names whose values identify each series; only these are recorded
     * (extras dropped, any omitted become `""`). Keep cardinality low — every
     * distinct value combination is a separate retained series.
     */
    labelNames?: readonly string[], buckets?: readonly number[]);
    /**
     * Record one observation into the series for `labels`.
     *
     * @param labels - Values for the declared {@link labelNames}; picks/creates the series.
     * @param value - The sample, in the metric's unit (e.g. seconds); added to `_sum`, bumps `_count`, and increments every bucket whose bound it is `<=`.
     */
    observe(labels: Labels, value: number): void;
    /**
     * Render this histogram (bucket, sum, and count series) in Prometheus exposition format.
     *
     * @returns The `# HELP`/`# TYPE` header, then per series: one `_bucket` line per bound carrying an `le` label, the `le="+Inf"` total, a `_sum`, and a `_count`.
     */
    render(): string;
}
/**
 * A registry of metrics that renders the Prometheus text exposition format.
 * Register your app's custom metrics here and bind the same instance as a
 * provider (`{ provide: MetricsRegistry, useValue: registry }`) so controllers
 * can `inject(MetricsRegistry)` the one the {@link metrics} plugin records into.
 */
export declare class MetricsRegistry {
    private readonly metrics;
    private register;
    /**
     * Get or create a counter (idempotent by name).
     *
     * @param name - Metric name, also the registry key; a second call with this name returns the first counter and ignores the other arguments.
     * @param help - Help text for the `# HELP` line.
     * @param labelNames - Label names keying the series; keep cardinality low, since each distinct value combination is a retained series.
     * @returns The new or previously registered counter with that name.
     */
    counter(name: string, help: string, labelNames?: readonly string[]): Counter;
    /**
     * Get or create a gauge (idempotent by name).
     *
     * @param name - Metric name, also the registry key; a second call with this name returns the first gauge and ignores the other arguments.
     * @param help - Help text for the `# HELP` line.
     * @param labelNames - Label names keying the series; keep cardinality low, since each distinct value combination is a retained series.
     * @returns The new or previously registered gauge with that name.
     */
    gauge(name: string, help: string, labelNames?: readonly string[]): Gauge;
    /**
     * Get or create a histogram (idempotent by name).
     *
     * @param name - Metric name, also the registry key; a second call with this name returns the first histogram and ignores the other arguments (including `buckets`).
     * @param help - Help text for the `# HELP` line.
     * @param labelNames - Label names keying the series; keep cardinality low, since each distinct value combination is a retained series.
     * @param buckets - Ascending upper bounds for the cumulative buckets, in the observed unit (default {@link DEFAULT_BUCKETS}, seconds).
     * @returns The new or previously registered histogram with that name.
     */
    histogram(name: string, help: string, labelNames?: readonly string[], buckets?: readonly number[]): Histogram;
    /**
     * The full exposition text (one block per metric, trailing newline).
     *
     * @returns The Prometheus exposition text for every registered metric.
     */
    render(): string;
}
/** Options for {@link metrics}. */
export interface MetricsOptions {
    /** Registry to record into (default: a fresh one). Share it to add custom metrics. */
    registry?: MetricsRegistry;
    /** Path the metrics are exposed at (default `"/metrics"`). */
    endpoint?: string;
    /** Latency histogram buckets in seconds (default {@link DEFAULT_BUCKETS}). */
    buckets?: readonly number[];
}
/**
 * Plugin: auto-instrument HTTP traffic and expose Prometheus metrics. Records
 * `http_requests_total` (counter) and `http_request_duration_seconds`
 * (histogram) — both labelled by method, route *pattern* (low cardinality), and
 * status — plus `http_requests_in_flight` (gauge), which is unlabeled (a single
 * series), and serves the exposition format at `endpoint`. The scrape endpoint
 * is served before routing, so it isn't counted.
 *
 * ```ts
 * const app = await createApp({ plugins: [metrics()] }) // GET /metrics
 * ```
 *
 * @param options - Registry to record into, endpoint path, and histogram buckets.
 * @returns A plugin that instruments requests and serves the metrics endpoint.
 */
export declare function metrics(options?: MetricsOptions): Plugin;
export {};
//# sourceMappingURL=metrics.d.ts.map