import type { Attributes, Tracer } from "@opentelemetry/api";
import type { FilesOperation, FilesPlugin } from "../index.js";
export interface TracingOptions {
    /**
     * The tracer spans are created on. Defaults to
     * `trace.getTracer("files-sdk")` — the global tracer from `@opentelemetry/api`
     * — so with an OpenTelemetry SDK registered it just works. Pass your own to
     * scope the instrumentation name/version or to inject a tracer in tests.
     */
    tracer?: Tracer;
    /**
     * Prefix for span names. Each operation becomes `${spanPrefix}${op.kind}` —
     * the default `"files."` yields `files.upload`, `files.download`, etc. Names
     * stay deliberately low-cardinality (the key lives in an attribute, not the
     * name) so traces group cleanly.
     */
    spanPrefix?: string;
    /**
     * Add or override attributes per operation. Receives the full
     * {@link FilesOperation} and is merged **over** the built-ins, so it can
     * attach context (a tenant id, a request id) or redact a default by returning
     * it as `undefined` — e.g. `{ "files.key": undefined }` to keep keys out of
     * your traces. Return nothing to add none.
     */
    attributes?: (op: FilesOperation) => Attributes | undefined;
}
/**
 * Open an OpenTelemetry span around every operation on a {@link Files}
 * instance. Each call becomes one span named `files.<verb>` carrying the
 * caller-facing key (or `from` / `to` for `copy` / `move`), a `files.bulk` flag
 * for batch items, and a cheap result attribute on success (`files.size`,
 * `files.exists`, `files.count`). A throw is recorded on the span with
 * `recordException` and an `ERROR` status, then re-thrown untouched.
 *
 * Spans are opened with `startActiveSpan`, so they nest correctly: each op span
 * is a child of whatever span is active when you call, and any sub-operation an
 * inner plugin issues — or an `extend` method calling back into the instance —
 * becomes a child of the op span in turn.
 *
 * Body-transparent: it never buffers, transforms, or reads the body (result
 * attributes come from declared metadata, not bytes), so streaming, range
 * downloads, `url()`, and `signedUploadUrl()` all keep working on any adapter.
 *
 * `@opentelemetry/api` is an **optional peer dependency**. The tracer defaults
 * to the global `trace.getTracer("files-sdk")`, which is a no-op until you
 * register an OpenTelemetry SDK — so installing the plugin costs nothing until
 * you wire up an exporter.
 *
 * Plugins run **outside** retries, so a span covers the whole logical call
 * including every retry attempt, not one span per attempt. Place `tracing()`
 * **first** (outermost) so the span wraps the caller-facing operation and the
 * work of inner plugins shows up nested beneath it; place it last to time only
 * the provider call.
 *
 * @param options optional `{ tracer, spanPrefix, attributes }`.
 * @example
 * ```ts
 * import { createFiles } from "files-sdk";
 * import { s3 } from "files-sdk/s3";
 * import { tracing } from "files-sdk/tracing";
 *
 * const files = createFiles({
 *   adapter: s3({ bucket: "uploads" }),
 *   plugins: [tracing()], // uses the global tracer
 * });
 *
 * await files.upload("a.txt", "hello"); // → span "files.upload" { files.key, files.size }
 * ```
 */
export declare const tracing: (options?: TracingOptions) => FilesPlugin;
//# sourceMappingURL=index.d.ts.map