/** otelcol-contrib release the config is validated against (collector/config.yaml). */
export declare const COLLECTOR_VERSION = "0.160.0";
/** Upstream contrib image used by `respan collector start --docker`. */
export declare const COLLECTOR_IMAGE = "otel/opentelemetry-collector-contrib:0.160.0";
/** OTLP/HTTP receiver port — what the SDK's RESPAN_BASE_URL points at. */
export declare const DEFAULT_COLLECTOR_PORT = 4318;
/** health_check extension port (fixed in the config unless overridden by env). */
export declare const DEFAULT_HEALTH_PORT = 13133;
/** Prometheus metrics port (hard-coded in the config). */
export declare const DEFAULT_METRICS_PORT = 8888;
/** file_storage max_size default: 512 MiB. */
export declare const DEFAULT_MAX_SIZE_BYTES = 536870912;
/** sending_queue.queue_size default (batches). */
export declare const DEFAULT_QUEUE_SIZE = 10000;
export declare const CONTAINER_NAME = "respan-collector";
export declare const VOLUME_NAME = "respan-collector-queue";
/** Queue directory inside the container (matches collector/Dockerfile). */
export declare const CONTAINER_DATA_DIR = "/var/lib/otelcol/respan";
/** Config mount point inside the container (the upstream image's default path). */
export declare const CONTAINER_CONFIG_PATH = "/etc/otelcol-contrib/config.yaml";
/** Uid the upstream contrib image runs as; the queue volume must be writable by it. */
export declare const CONTAINER_UID = "10001";
/** Helper image used once to chown a fresh queue volume (the contrib image has no shell). */
export declare const VOLUME_INIT_IMAGE = "alpine:3.20";
/**
 * The collector configuration — an exact copy of collector/config.yaml (the
 * single source of truth; tests/collector.test.mjs asserts they never drift).
 * Every tunable is a `${env:NAME:-default}` placeholder; the API key is only
 * ever read from the RESPAN_API_KEY environment variable.
 */
export declare const COLLECTOR_CONFIG_TEMPLATE = "# Respan Collector \u2014 an OpenTelemetry Collector configuration.\n#\n# Receives OTLP/HTTP from the Respan SDKs on localhost and forwards it to the\n# Respan ingest endpoint through a bounded, persistent (write-ahead-log) queue,\n# so spans survive Respan outages and collector restarts without unbounded\n# local growth. Every value can be overridden with an environment variable.\n#\n# Validated against otelcol-contrib 0.160.0.\n\nextensions:\n  file_storage:\n    # Persistent queue. Entries are deleted as soon as Respan acknowledges them;\n    # in steady state the directory is nearly empty.\n    directory: ${env:RESPAN_COLLECTOR_DATA_DIR:-/var/lib/otelcol/respan}\n    create_directory: true\n    # Hard cap on disk (bytes). When reached, new batches are dropped and counted\n    # in otelcol_exporter_enqueue_failed_spans instead of filling the disk.\n    max_size: ${env:RESPAN_COLLECTOR_MAX_SIZE_BYTES:-536870912}\n    timeout: 1s\n    compaction:\n      on_start: true\n      on_rebound: true\n      directory: ${env:RESPAN_COLLECTOR_DATA_DIR:-/var/lib/otelcol/respan}\n  health_check:\n    endpoint: ${env:RESPAN_COLLECTOR_HEALTH_ENDPOINT:-127.0.0.1:13133}\n\nreceivers:\n  otlp:\n    protocols:\n      http:\n        endpoint: ${env:RESPAN_COLLECTOR_LISTEN:-127.0.0.1:4318}\n        # The Respan SDKs post to <RESPAN_BASE_URL>/api/v2/traces.\n        traces_url_path: /api/v2/traces\n\nprocessors:\n  memory_limiter:\n    check_interval: 1s\n    limit_mib: ${env:RESPAN_COLLECTOR_MEMORY_LIMIT_MIB:-512}\n    spike_limit_mib: 128\n  batch:\n    send_batch_size: 512\n    send_batch_max_size: 1024\n    timeout: 2s\n\nexporters:\n  otlphttp/respan:\n    traces_endpoint: ${env:RESPAN_COLLECTOR_EXPORT_URL:-https://api.respan.ai/api/v2/traces}\n    encoding: json\n    # Respan's ingest does not decompress request bodies; keep this `none` unless\n    # your endpoint (e.g. a proxy in front of a self-hosted deployment) accepts gzip.\n    compression: ${env:RESPAN_COLLECTOR_COMPRESSION:-none}\n    headers:\n      Authorization: \"Bearer ${env:RESPAN_API_KEY}\"\n    timeout: 30s\n    sending_queue:\n      enabled: true\n      storage: file_storage\n      # Number of batches kept while Respan is unreachable (also bounded by max_size).\n      queue_size: ${env:RESPAN_COLLECTOR_QUEUE_SIZE:-10000}\n      num_consumers: 4\n    retry_on_failure:\n      enabled: true\n      initial_interval: 5s\n      max_interval: 60s\n      # Never give up on a batch; the queue bounds are the only limit.\n      max_elapsed_time: 0\n\nservice:\n  extensions: [file_storage, health_check]\n  telemetry:\n    metrics:\n      level: normal\n      readers:\n        - pull:\n            exporter:\n              prometheus:\n                host: ${env:RESPAN_COLLECTOR_METRICS_HOST:-127.0.0.1}\n                port: 8888\n  pipelines:\n    traces:\n      receivers: [otlp]\n      processors: [memory_limiter, batch]\n      exporters: [otlphttp/respan]\n";
export interface CollectorConfigOptions {
    /** Full ingest URL, e.g. https://api.respan.ai/api/v2/traces (RESPAN_COLLECTOR_EXPORT_URL). */
    exportUrl?: string;
    /** Persistent queue directory (RESPAN_COLLECTOR_DATA_DIR). */
    dataDir?: string;
    /** Disk cap for the queue in bytes (RESPAN_COLLECTOR_MAX_SIZE_BYTES). */
    maxSizeBytes?: number;
    /** Batches kept while Respan is unreachable (RESPAN_COLLECTOR_QUEUE_SIZE). */
    queueSize?: number;
    /** OTLP/HTTP listen address, e.g. 127.0.0.1:4318 (RESPAN_COLLECTOR_LISTEN). */
    listen?: string;
    /** health_check listen address (RESPAN_COLLECTOR_HEALTH_ENDPOINT). */
    healthEndpoint?: string;
    /** Prometheus metrics bind host (RESPAN_COLLECTOR_METRICS_HOST). */
    metricsHost?: string;
    /** memory_limiter limit (RESPAN_COLLECTOR_MEMORY_LIMIT_MIB). */
    memoryLimitMib?: number;
}
/**
 * Render the collector config. Each `${env:NAME:-default}` placeholder whose
 * option is given is replaced by that value; the others keep the placeholder
 * (and therefore stay overridable through the environment). RESPAN_API_KEY is
 * never substituted — the file must not contain the secret.
 */
export declare function buildCollectorConfig(opts?: CollectorConfigOptions): string;
export interface CollectorPaths {
    /** ~/.respan/collector */
    root: string;
    configPath: string;
    dataDir: string;
    binDir: string;
    binaryPath: string;
    pidPath: string;
    logPath: string;
}
/** Where the CLI keeps the collector config, queue, binary, pid and log. */
export declare function collectorPaths(home?: string): CollectorPaths;
/**
 * Ingest URL for a Respan API base URL. Mirrors the SDKs, which accept both
 * `https://api.respan.ai` and `https://api.respan.ai/api` and post to
 * `<origin>/api/v2/traces`.
 */
export declare function exportUrlFromBaseUrl(baseUrl: string): string;
/** Base URL the SDKs / pi extension should use to reach a local collector. */
export declare function collectorBaseUrl(port?: number): string;
export interface DockerRunOptions {
    /** Host path of the rendered config (mounted read-only). */
    configPath: string;
    /** Host port published on 127.0.0.1 for the OTLP/HTTP receiver. */
    port: number;
    exportUrl: string;
    maxSizeBytes: number;
    queueSize: number;
    image?: string;
}
/**
 * Arguments for `docker <args>` that start the collector container. All ports
 * are published on 127.0.0.1 only. RESPAN_API_KEY is passed through from the
 * caller's environment (`-e RESPAN_API_KEY` without a value) so the secret
 * never appears on the command line.
 */
export declare function dockerRunArgs(opts: DockerRunOptions): string[];
/**
 * One-off `docker <args>` that makes a fresh queue volume writable by the
 * collector. Docker creates a new named volume owned by root, and the upstream
 * image runs as uid 10001 without a shell, so a helper image does the chown
 * (the same trick collector/Dockerfile uses at build time).
 */
export declare function dockerVolumeInitArgs(volume?: string): string[];
/** Release tarball for otelcol-contrib (contains `otelcol-contrib` and README.md). */
export declare function binaryDownloadUrl(version?: string, platform?: string, arch?: string): string;
/**
 * SHA-256 of the tarball. The release publishes one `<asset>.sha256` file per
 * asset (there is no aggregate checksums file); its body is the bare hex digest.
 */
export declare function checksumUrl(version?: string, platform?: string, arch?: string): string;
/** Extract the hex digest from a `.sha256` body (`<hex>` or `<hex>  <file>`). */
export declare function parseSha256(text: string): string | undefined;
/**
 * Parse Prometheus text exposition into metric name → value. Labels are
 * stripped; series that share a name are summed.
 */
export declare function parsePrometheusText(text: string): Map<string, number>;
export interface CollectorMetricsSummary {
    /** Batches currently waiting in the persistent queue. */
    queueSize: number;
    /** sending_queue.queue_size as reported by the exporter. */
    queueCapacity: number;
    /** Spans dropped because the queue (or its disk cap) was full. */
    enqueueFailedSpans: number;
    /** Spans given up on after export failures (permanent errors such as 4xx). */
    sendFailedSpans: number;
    /** Spans acknowledged by Respan. */
    sentSpans: number;
}
/**
 * Pick the exporter metrics out of a scrape. otelcol-contrib 0.160.0 exposes
 * them without a `_total` suffix (e.g. `otelcol_exporter_sent_spans`); the
 * suffixed spelling is accepted too in case a build re-enables it. Counters
 * only appear once they have been incremented, so a missing one reads as 0.
 */
export declare function summarizeCollectorMetrics(metrics: Map<string, number>): CollectorMetricsSummary;
/** Human-readable byte count (1024-based). */
export declare function formatBytes(bytes: number): string;