@logtape/sentry/dist/mod.d.cts

LogTape Sentry sink

import { LogLevel, LogRecord, Sink } from "@logtape/logtape";
import { LogSeverityLevel, ParameterizedString, SeverityLevel } from "@sentry/core";

//#region src/mod.d.ts

/**
 * Options for records sent through Sentry's Logs API.
 *
 * @since 2.3.0
 */
interface SentryLogsOptions {
  /**
   * Minimum level for records sent through Sentry's Logs API.
   *
   * @default `"trace"`
   */
  level?: LogLevel;
}
/**
 * Options for records added as Sentry breadcrumbs.
 *
 * @since 2.3.0
 */
interface SentryBreadcrumbOptions {
  /**
   * Minimum level for records added as breadcrumbs.
   *
   * @default `"trace"`
   */
  level?: LogLevel;
  /**
   * Maximum level for records added as breadcrumbs.
   */
  maxLevel?: LogLevel;
}
/**
 * A Sentry client instance type (used for v1.1.x backward compatibility).
 *
 * Client instances only support `captureMessage` and `captureException`.
 * For scope operations (breadcrumbs, user context, traces), the sink always
 * uses global functions from `@sentry/core`.
 *
 * @deprecated This is only used for backward compatibility with v1.1.x.
 * New code should use `getSentrySink()` without parameters, which automatically
 * uses Sentry's global functions.
 *
 * @since 1.3.0
 */
interface SentryInstance {
  captureMessage: (message: string, captureContext?: SeverityLevel | unknown) => string;
  captureException: (exception: unknown, hint?: unknown) => string;
}
/**
 * A Sentry SDK namespace object.
 *
 * Pass the namespace imported by your application when *@logtape/sentry* should
 * use the same Sentry module instance that initialized your app, for example
 * `import * as Sentry from "@sentry/node"`.
 *
 * @since 2.2.0
 */
interface SentryNamespace {
  /**
   * Captures a message event and sends it to Sentry.
   */
  captureMessage(message: ParameterizedString, captureContext?: SeverityLevel | unknown): string;
  /**
   * Captures an exception event and sends it to Sentry.
   */
  captureException(exception: unknown, hint?: unknown): string;
  /**
   * Gets the currently active span, if any.
   */
  getActiveSpan(): {
    spanContext: () => {
      traceId: string;
      spanId: string;
      parentSpanId?: string;
    };
  } | undefined;
  /**
   * Gets the currently active Sentry client, if any.
   */
  getClient(): {
    getOptions: () => {
      enableLogs?: boolean;
      _experiments?: {
        enableLogs?: boolean;
      };
    };
  } | undefined;
  /**
   * Gets the current isolation scope.
   */
  getIsolationScope(): {
    addBreadcrumb: (breadcrumb: {
      category: string;
      level: SeverityLevel;
      message: string;
      timestamp: number;
      data: Record<string, unknown>;
    }) => void;
  } | undefined;
  /**
   * Sentry's structured logging API, available in Sentry SDK 9.41.0+.
   */
  logger?: Partial<Record<LogSeverityLevel, (message: ParameterizedString, attributes: Record<string, unknown>) => void>>;
}
/**
 * Options for configuring the Sentry sink.
 * @since 1.3.0
 */
interface SentrySinkOptions {
  /**
   * Sentry SDK namespace to use for capture, scope, span, and structured log
   * APIs.
   *
   * This is useful when your application initializes Sentry through a framework
   * SDK such as `@sentry/nextjs` or `@sentry/react-native`, and
   * *@logtape/sentry* resolves a different `@sentry/core` module instance.
   *
   * @example
   * ```typescript
   * import * as Sentry from "@sentry/node";
   *
   * getSentrySink({ sentry: Sentry });
   * ```
   *
   * @default `@sentry/core`
   * @since 2.2.0
   */
  sentry?: SentryNamespace;
  /**
   * Enable automatic breadcrumb creation for log events.
   *
   * When enabled, non-error logs become breadcrumbs in Sentry's isolation
   * scope, providing a complete context trail when errors occur. Breadcrumbs
   * are lightweight and only appear in error reports for debugging.
   *
   * @default false
   * @deprecated Use `breadcrumbs` instead.
   * @since 1.3.0
   */
  enableBreadcrumbs?: boolean;
  /**
   * Enables and configures automatic breadcrumb creation for log events.
   *
   * Set this to `true` to use the default breadcrumb behavior, or pass an
   * options object to control which non-error log levels become breadcrumbs.
   *
   * When this option is set, it takes precedence over the deprecated
   * `enableBreadcrumbs` option.
   *
   * @default false
   * @since 2.3.0
   */
  breadcrumbs?: boolean | SentryBreadcrumbOptions;
  /**
   * Configures records sent through Sentry's Logs API.
   *
   * The Sentry SDK must still have structured logging enabled with
   * `enableLogs: true` or `_experiments.enableLogs: true`.
   *
   * @since 2.3.0
   */
  logs?: SentryLogsOptions;
  /**
   * Property names to inspect for an `Error` instance when deciding whether
   * error-level records should be sent through Sentry's `captureException()`.
   *
   * Names are checked in order, and the first property containing an `Error`
   * instance is used as the captured exception.  Set this to a custom list when
   * your application or logger stores the primary exception under another name.
   *
   * @default `["error", "err"]`
   * @since 2.3.0
   */
  errorPropertyNames?: readonly string[];
  /**
   * Optional hook to transform or filter records before sending to Sentry.
   * Return `null` to drop the record.
   *
   * @since 1.3.0
   */
  beforeSend?: (record: LogRecord) => LogRecord | null;
}
/**
 * Gets a LogTape sink that sends logs to Sentry.
 *
 * This sink uses Sentry's global capture functions from `@sentry/core` by
 * default, following Sentry v8+ best practices. Simply call `Sentry.init()`
 * before creating the sink, and it will automatically use your initialized
 * client when both packages resolve the same Sentry module instance.
 *
 * @param optionsOrClient Optional configuration. Can be:
 *   - Omitted: Uses global Sentry functions (recommended)
 *   - Object with options: Configure sink behavior
 *   - Object with `sentry`: Use an application-provided Sentry SDK namespace
 *   - Sentry client instance: Backward compatibility (deprecated)
 * @returns A LogTape sink that sends logs to Sentry.
 *
 * @example Recommended usage - no parameters
 * ```typescript
 * import { configure } from "@logtape/logtape";
 * import { getSentrySink } from "@logtape/sentry";
 * import * as Sentry from "@sentry/node";
 *
 * Sentry.init({ dsn: process.env.SENTRY_DSN });
 *
 * await configure({
 *   sinks: {
 *     sentry: getSentrySink(),  // That's it!
 *   },
 *   loggers: [
 *     { category: [], sinks: ["sentry"], lowestLevel: "error" },
 *   ],
 * });
 * ```
 *
 * @example With an application-provided Sentry namespace
 * ```typescript
 * import { configure } from "@logtape/logtape";
 * import { getSentrySink } from "@logtape/sentry";
 * import * as Sentry from "@sentry/nextjs";
 *
 * Sentry.init({ dsn: process.env.SENTRY_DSN });
 *
 * await configure({
 *   sinks: {
 *     sentry: getSentrySink({ sentry: Sentry }),
 *   },
 *   loggers: [
 *     { category: [], sinks: ["sentry"], lowestLevel: "error" },
 *   ],
 * });
 * ```
 *
 * @example With options
 * ```typescript
 * import * as Sentry from "@sentry/node";
 * Sentry.init({ dsn: process.env.SENTRY_DSN });
 *
 * await configure({
 *   sinks: {
 *     sentry: getSentrySink({
 *       breadcrumbs: true,
 *     }),
 *   },
 *   loggers: [
 *     { category: [], sinks: ["sentry"], lowestLevel: "info" },
 *   ],
 * });
 * ```
 *
 * @example Edge functions - must flush before termination
 * ```typescript
 * // Cloudflare Workers
 * export default {
 *   async fetch(request, env, ctx) {
 *     logger.error("Something happened");
 *     ctx.waitUntil(Sentry.flush(2000));  // Don't block response
 *     return new Response("OK");
 *   }
 * };
 * ```
 *
 * @example Legacy usage (v1.1.x - deprecated)
 * ```typescript
 * import { getClient } from "@sentry/node";
 * const client = getClient();
 * getSentrySink(client);  // Still works but shows deprecation warning
 * ```
 *
 * @since 1.0.0
 */
declare function getSentrySink(optionsOrClient?: SentrySinkOptions | SentryInstance): Sink;
//# sourceMappingURL=mod.d.ts.map
//#endregion
export { SentryBreadcrumbOptions, SentryInstance, SentryLogsOptions, SentryNamespace, SentrySinkOptions, getSentrySink };
//# sourceMappingURL=mod.d.cts.map