/**
 * Configures SDK logging and creates named loggers with structured fields.
 *
 * Start with {@link resolveLogger} for a logger from a level, handler, or
 * existing logger. Use {@link defaultHandler} when an application must control
 * output format, filters, or environment integration. Implement
 * {@link Handler} only for custom logging backends.
 *
 * This module does not automatically redact ordinary objects. Use
 * {@link customJson} or sanitize sensitive fields before logging them.
 *
 * @packageDocumentation
 */
/**
 * Identifies an optional method that returns a JSON-safe logging value.
 *
 * Add this symbol method to a class when its normal properties contain
 * secrets, circular references, or internal state that must not enter JSON
 * logs. JSON handlers use this method before {@link custom}. If this method is
 * absent, they use {@link custom} as a fallback.
 *
 * @example
 * ```ts
 * import { customJson } from '@nebius/js-sdk/runtime/util/logging';
 *
 * class Session {
 *   constructor(private token: string) {}
 *
 *   [customJson]() {
 *     return { type: 'Session', token: '[redacted]' };
 *   }
 * }
 * ```
 */
export declare const customJson: unique symbol;
/**
 * Re-exports Node.js
 * {@link https://nodejs.org/api/util.html#utilinspectcustom | util.inspect.custom}
 * for readable text logging.
 */
export declare const custom: symbol;
/** Defines the minimum console method that built-in log handlers need. */
export interface ConsoleLike {
    /** Writes one formatted record and any optional values. */
    error(message?: unknown, ...optionalParams: unknown[]): void;
}
/** Contains structured fields attached to a log record. */
export type Argument = {
    [key: string]: unknown;
};
/**
 * Lists log severities from most detailed to disabled.
 *
 * A handler emits a record when its numeric level is at least the handler's
 * configured level.
 */
export declare enum Level {
    /** Represents the trace log level. */
    TRACE = 10,
    /** Represents the debug log level. */
    DEBUG = 20,
    /** Represents the info log level. */
    INFO = 30,
    /** Represents the warn log level. */
    WARN = 40,
    /** Represents the error log level. */
    ERROR = 50,
    /** Represents the none log level. */
    NONE = 100
}
/**
 * Converts a value to a JSON-safe form for structured logging.
 *
 * The function uses {@link customJson} first and {@link custom} second.
 * It handles dates, errors, functions, symbols, and circular references. When
 * conversion fails, it returns an inspected string instead of throwing.
 * A {@link customJson} implementation can call this function to convert nested
 * values.
 *
 * This function does not redact ordinary object properties. Objects that can
 * contain credentials must provide a safe {@link customJson} method or be
 * sanitized before logging.
 */
export declare function inspectJson(val: unknown): unknown;
/**
 * Receives records from a {@link Logger}.
 *
 * Custom handlers should avoid throwing. {@link Logger} catches handler errors
 * so a logging failure does not stop an SDK request.
 */
export interface Handler {
    /**
     * Writes one record.
     *
     * A negative `traceLevel` disables the call-site trace. A non-negative value
     * controls how many logging frames the handler skips. A built-in handler
     * with `alwaysAddTrace` enabled can override a negative value.
     */
    log(level: Level, message: string, args: Argument, name: string, traceLevel: number): void;
}
/**
 * Selects log records by logger name and level.
 *
 * A string matches when the name contains it. A regular expression tests the
 * name. A function can inspect both values. Do not use a stateful regular
 * expression with the `g` or `y` flag. The handler retains its `lastIndex`
 * value between records.
 */
export type Filter = string | RegExp | ((name: string, level: Level) => boolean);
/** Defines one filter or a list in which any matching filter accepts a record. */
export type Filters = Filter[] | Filter;
/** Formats the complete data for one text log record. */
export type FormatFunction = (opts: {
    name: string;
    level: Level;
    time: Date;
    message: string;
    args?: string;
    trace?: string;
}) => string;
/** Formats one structured field after the handler converts its value to text. */
export type ArgFormatFunction = (key: string, value: string) => string;
/** Receives one or more formatted text chunks from a handler. */
export type Writer = (s: string) => void;
/**
 * Appends text log records to a file.
 *
 * A leading `~/` is expanded. The stream stays open for the lifetime of the
 * wrapper, and this class does not provide a close operation.
 */
export declare class FileWrapper implements ConsoleLike {
    private fs;
    private stream;
    /** Creates a new file wrapper. */
    constructor(filePath: string);
    /** Appends one formatted record and its optional values. */
    error(message?: unknown, ...optionalParams: unknown[]): void;
}
/**
 * Selects log output.
 *
 * A string is a file path. A function receives formatted text. A
 * {@link ConsoleLike} receives records through {@link ConsoleLike.error}.
 */
export type Output = ConsoleLike | Writer | string;
/**
 * Writes configurable plain-text log records.
 *
 * This handler is suitable for non-interactive output. It supports a custom
 * formatter or a template with `name`, `level`, `time`, `message`, `args`, and
 * `trace` placeholders.
 *
 * @example
 * ```ts
 * import {
 *   ConsoleHandler,
 *   Level,
 *   Logger,
 * } from '@nebius/js-sdk/runtime/util/logging';
 *
 * const handler = new ConsoleHandler({
 *   level: Level.DEBUG,
 *   format: '{time} [{level}] {name}: {message}{ args}',
 * });
 * const logger = new Logger(handler, 'example.worker');
 * logger.debug('Started', { jobId: 'job-1' });
 * ```
 */
export declare class ConsoleHandler implements Handler {
    /** Returns a concise representation for text inspection. */
    [custom]: () => string;
    private consoleLike;
    private level;
    private filters;
    private format;
    private argFormat;
    private argDelimiter;
    private alwaysAddTrace;
    /**
     * Creates a plain-text handler.
     *
     * The default level is {@link Level.INFO}, the default filter matches every
     * name, and the default output is the process console.
     */
    constructor(opts?: {
        output?: Output;
        level?: Level;
        format?: FormatFunction | string;
        argFormat?: ArgFormatFunction;
        argDelimiter?: string;
        filters?: Filters;
        alwaysAddTrace?: boolean;
    });
    /** Returns a JSON-safe value for logs. */
    [customJson](): object;
    private matchFilters;
    /** Converts structured fields to one delimiter-separated text string. */
    argString(args: Argument): string;
    /** Writes a log entry. */
    log(level: Level, message: string, args: Argument, name: string, traceLevel?: number): void;
}
/**
 * Writes human-readable log records with optional ANSI colors.
 *
 * Error values include their message and stack. Use `colors: false` when the
 * output is a file or another destination that does not process ANSI codes.
 */
export declare class PrettyHandler implements Handler {
    /** Returns a concise representation for text inspection. */
    [custom]: () => string;
    private consoleLike;
    private level;
    private filters;
    private argFormat;
    private argDelimiter;
    private useColors;
    private alwaysAddTrace;
    /**
     * Creates a pretty handler.
     *
     * The default level is {@link Level.INFO}, all logger names match, colors are
     * enabled, and output goes to the process console.
     */
    constructor(opts?: {
        output?: Output;
        level?: Level;
        argFormat?: ArgFormatFunction;
        argDelimiter?: string;
        filters?: Filters;
        colors?: boolean;
        alwaysAddTrace?: boolean;
    });
    /** Returns a JSON-safe value for logs. */
    [customJson](): object;
    private matchFilters;
    private colorize;
    private levelColor;
    private formatArgs;
    /** Writes a log entry. */
    log(level: Level, message: string, args: Argument, name: string, traceLevel: number): void;
}
/**
 * Writes one JSON object per log record.
 *
 * Structured fields appear at the top level. Reserved record fields (`time`,
 * `level`, `name`, `message`, and `trace` when generated) replace fields with
 * the same names from `args`. Values pass through {@link inspectJson}.
 */
export declare class JsonHandler implements Handler {
    /** Returns a concise representation for text inspection. */
    [custom]: () => string;
    private consoleLike;
    private level;
    private filters;
    private alwaysAddTrace;
    /**
     * Creates a JSON handler.
     *
     * The default level is {@link Level.INFO}, all logger names match, and output
     * goes to the process console.
     */
    constructor(opts?: {
        output?: Output;
        level?: Level;
        filters?: Filters;
        alwaysAddTrace?: boolean;
    });
    /** Returns a JSON-safe value for logs. */
    [customJson](): object;
    private matchFilters;
    private serializeValue;
    /** Writes a log entry. */
    log(level: Level, message: string, args: Argument, name: string, traceLevel?: number): void;
}
/**
 * Parses a logging level name or exact numeric value.
 *
 * Names are case-insensitive. `WARNING` maps to {@link Level.WARN}, and `OFF`
 * maps to {@link Level.NONE}. Returns `undefined` for unsupported values.
 */
export declare function parseLevel(v?: string | number): Level | undefined;
/**
 * Writes a best-effort warning for deprecated generated API elements.
 *
 * Before {@link setDeprecatedWarningLogger} runs, output goes to
 * `console.warn`. Logging errors are ignored.
 */
export declare function deprecatedWarn(message: string, type?: string, fullName?: string, date?: string): void;
/**
 * Sets the base logger for future deprecation warnings.
 *
 * Warnings use a detached logger named `nebius.deprecated`.
 */
export declare function setDeprecatedWarningLogger(logger: Logger): void;
/** Configures {@link defaultHandler} and fallback handling in {@link resolveLogger}. */
export type HandlerOpts = {
    /** Selects a console-like object, writer function, or append-only file path. */
    output?: Output;
    /** Sets the minimum emitted level. The default is {@link Level.INFO}. */
    level?: Level;
    /** Selects logger names. Any matching filter accepts the record. */
    filters?: Filters;
    /** Selects the pretty colored handler when JSON output is disabled. */
    colored?: boolean;
    /** Adds a call-site trace even when the logger does not request one. */
    alwaysAddTrace?: boolean;
    /** Selects newline-delimited JSON output. */
    useJson?: boolean;
};
/**
 * Creates a log handler from options and Nebius logging environment variables.
 *
 * Explicit scalar options override their matching environment settings.
 * Important settings include `NEBIUS_LOG`, `NEBIUS_LOG_JSON`,
 * `NEBIUS_LOG_ALWAYS_ADD_TRACE`, and `NEBIUS_LOG_OUTPUT`.
 *
 * Per-name variables add environment filters. The suffix is matched with a
 * case-sensitive `loggerName.includes(suffix)` check. For example,
 * `NEBIUS_LOG_auth=DEBUG` matches `nebius.auth`. If `opts.filters` is present,
 * the environment filters are added to it; they are not replaced.
 * A per-name filter cannot lower the handler's global minimum level. To emit
 * debug records, also set `NEBIUS_LOG=DEBUG` or pass
 * `level: Level.DEBUG`.
 *
 * Without explicit output, `NEBIUS_LOG_OUTPUT` accepts `stderr`, `stdout`,
 * `console`, `none`, or a file path. Color selection also follows `NO_COLOR`,
 * `FORCE_COLOR`, and whether stderr is a terminal.
 *
 * @example
 * ```ts
 * import {
 *   defaultHandler,
 *   Level,
 *   Logger,
 * } from '@nebius/js-sdk/runtime/util/logging';
 *
 * const handler = defaultHandler({
 *   level: Level.DEBUG,
 *   useJson: true,
 *   filters: ['nebius.auth', 'nebius.request'],
 * });
 * const logger = new Logger(handler, 'nebius.request');
 * ```
 */
export declare function defaultHandler(opts?: HandlerOpts): Handler;
/**
 * Converts a logger specification to a {@link Logger}.
 *
 * A {@link Handler} is wrapped in a new logger chain. An existing
 * {@link Logger} is returned unchanged, so `defaultName` and `opts` do not
 * affect it.
 *
 * A supported level name or exact {@link Level} value creates a default
 * handler at that level. An unsupported value falls back to `opts`, the
 * environment, or {@link Level.INFO}. An absent value creates a default
 * handler from `opts` and the environment.
 *
 * A dotted `defaultName` creates the same hierarchy as repeated
 * {@link Logger.child} calls.
 */
export declare function resolveLogger(spec?: Logger | Handler | string | number, defaultName?: string[] | string, opts?: HandlerOpts): Logger;
/** Discards all log records without side effects. */
export declare const noopHandler: Handler;
/**
 * Writes structured records through a shared {@link Handler}.
 *
 * Logger instances are lightweight. Use {@link child} for a component below
 * the current name, {@link withFields} for fields shared by later records, and
 * {@link detached} for an independent full name.
 *
 * Do not add bearer tokens, private keys, or other secrets as fields. Text
 * handlers inspect ordinary objects, and JSON handlers only redact values that
 * define a safe {@link customJson} method.
 *
 * @example
 * ```ts
 * import { resolveLogger } from '@nebius/js-sdk/runtime/util/logging';
 *
 * const logger = resolveLogger('INFO', 'example.application');
 * const requestLogger = logger.child('request', { requestId: 'req-1' });
 * const error = new Error('connection closed');
 * requestLogger.info('Sending request', { attempt: 1 });
 * requestLogger.error('Request failed', { error }, true);
 * ```
 */
export declare class Logger {
    /** Returns a concise representation for text inspection. */
    [custom]: () => string;
    private handler;
    private name;
    private withFieldsArg;
    private parent?;
    /**
     * Adds a call-site trace to this logger's named-level methods by default.
     *
     * {@link child}, {@link sibling}, and {@link detached} do not inherit this
     * value.
     */
    traceByDefault: boolean;
    /**
     * Creates a logger.
     *
     * Most applications should use {@link resolveLogger}. A logger without a
     * handler uses {@link noopHandler}.
     */
    constructor(handler?: Handler, name?: string, withFieldsArg?: Argument, parent?: Logger | undefined, 
    /**
     * Adds a call-site trace to this logger's named-level methods by default.
     *
     * {@link child}, {@link sibling}, and {@link detached} do not inherit this
     * value.
     */
    traceByDefault?: boolean);
    /** Returns a JSON-safe value for logs. */
    [customJson](): object;
    /** Returns the full logger name. */
    get getName(): string;
    /** Writes an informational record. Set `withTrace` to add a call-site trace. */
    info(message: string, args?: Argument, withTrace?: boolean): void;
    /** Writes a warning record. Set `withTrace` to add a call-site trace. */
    warn(message: string, args?: Argument, withTrace?: boolean): void;
    /** Writes an error record. Set `withTrace` to add a call-site trace. */
    error(message: string, args?: Argument, withTrace?: boolean): void;
    /** Writes a debug record. Set `withTrace` to add a call-site trace. */
    debug(message: string, args?: Argument, withTrace?: boolean): void;
    /** Writes a trace-level record. Set `withTrace` to add a call-site trace. */
    trace(message: string, args?: Argument, withTrace?: boolean): void;
    private _log;
    /**
     * Writes a record at an explicit level.
     *
     * If `withTrace` is absent, this method does not add a call-site trace. It
     * does not use {@link traceByDefault}. The named-level methods use that
     * default when `withTrace` is absent.
     */
    log(level: Level, message: string, args?: Argument, withTrace?: boolean): void;
    /**
     * Returns a logger with additional fields and the same name.
     *
     * New fields replace existing fields with the same keys. The method copies
     * only top-level fields. Later top-level changes to the input object do not
     * change the returned logger, but nested objects and arrays stay shared. The
     * returned logger inherits this logger's `traceByDefault` value unless the
     * `traceByDefault` argument supplies another value.
     */
    withFields(fields: Argument, traceByDefault?: boolean): Logger;
    /**
     * Returns a logger with an independent full name.
     *
     * The new logger uses the same handler but does not inherit this logger's
     * fields. It keeps `additionalArguments` by reference. Later changes to that
     * object change fields written by the detached logger.
     */
    detached(name: string, additionalArguments?: Argument, traceByDefault?: boolean): Logger;
    /**
     * Returns a logger whose name is this name plus `.` and the suffix.
     *
     * The child inherits this logger's fields. Its `traceByDefault` value is
     * independent and defaults to `false`.
     */
    child(suffix: string, additionalArguments?: Argument, traceByDefault?: boolean): Logger;
    /**
     * Returns a logger beside this logger in the name hierarchy.
     *
     * The sibling keeps this logger's fields. If this logger has no parent, the
     * supplied name becomes the complete logger name.
     */
    sibling(siblingName: string, additionalArguments?: Argument, traceByDefault?: boolean): Logger;
    /** Returns the log handler. */
    get getHandler(): Handler;
}
//# sourceMappingURL=logging.d.ts.map