@statoss/sdk 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -0,0 +1,41 @@
+# Changelog
+
+## 0.4.0 (unreleased)
+
+- Logs: `init({ logs: true })` sends the lines of `logger` as Sentry's log
+  items. `logger.trace`, `debug`, `info`, `warn`, `error` and `fatal` take a
+  message and attributes; `logger.fmt` sends a template and its values.
+- `logger.log(level, message, attributes)` takes the app's own levels, typed
+  by the schema on the logger `init` returns. An own level is sent at its
+  range's level with its severity and the attribute `statoss.level`.
+- `beforeSendLog` changes or drops a line.
+- Lines go out 100 at a time or 5 seconds after the first, on `flush` and
+  `close`, and in Node, Bun and Deno when the process runs out of work.
+- Envelopes of log lines take at most 10 of the 30 places in the send
+  queue, so errors still go during a flood of lines.
+- A body past 64 KiB is cut there, with its size in bytes before the cut as
+  `statoss.truncated`, and an attribute's value at 8 KiB, in UTF-8 bytes,
+  as StatOSS's intake cuts and records them.
+- Every line carries a `trace_id` of 32 hex digits, one per client for its
+  life, since Sentry's Relay drops a line without one.
+
+## 0.3.0 (8 Oct 2026)
+
+- Levels, categories and fields in a typed schema: `defineSchema`, and
+  capture functions from `init` that take only the schema's names.
+- A level name is at most 32 characters, as the server keeps it (it was 64);
+  a longer name is sent as plain `error`.
+
+## 0.2.0 (8 Oct 2026)
+
+- Debug IDs: events name the debug IDs of the files their frames ran in,
+  for source maps uploaded with sentry-cli or `@statoss/cli`.
+
+## 0.1.1 (7 Oct 2026)
+
+- The first release published from GitHub Actions with trusted publishing.
+
+## 0.1.0 (7 Oct 2026)
+
+- Error tracking for browsers, Node, Bun, Deno, Cloudflare Workers and
+  Vercel Edge, in Sentry's protocol.

package/README.md

@@ -1,8 +1,8 @@
 # @statoss/sdk
 
-Error tracking for [StatOSS](https://statoss.com). One package for browsers,
-Node, Bun, Deno, Cloudflare Workers and Vercel Edge, with TypeScript types
-included and no dependencies.
+Error tracking and logs for [StatOSS](https://statoss.com). One package for
+browsers, Node, Bun, Deno, Cloudflare Workers and Vercel Edge, with
+TypeScript types included and no dependencies.
 
 The SDK speaks Sentry's protocol (envelopes, event schema, rate limits,
 client reports), so it can also send to Sentry, and Sentry's own SDKs can
@@ -369,6 +369,57 @@ StatOSS.captureException(error, {
   one.
 - StatOSS filters and groups on these tags like any other.
 
+## Logs
+
+With `logs: true`, `logger`'s lines are sent as Sentry's log items, which
+StatOSS's Logs area searches. Without it they are dropped.
+
+```ts
+import * as StatOSS from "@statoss/sdk";
+
+StatOSS.init({ dsn: "...", logs: true });
+
+StatOSS.logger.info("Order paid", { orderId: 7, amount: 12.5 });
+StatOSS.logger.warn(StatOSS.logger.fmt`Search for ${term} took ${ms} ms`);
+StatOSS.logger.log("error", "Card declined", { orderId: 7 });
+```
+
+- `trace`, `debug`, `info`, `warn`, `error` and `fatal` each take a message
+  and attributes. Strings, numbers and booleans are sent typed; anything
+  else as JSON.
+- `logger.fmt` fills the values in and sends the template and each value
+  as `sentry.message.template` and `sentry.message.parameter.<n>`.
+- `logger.log(level, message, attributes)` takes a level by name: one of the
+  six, a Sentry level (`warning`), or one of your own. Your own level is
+  sent at its range's level (`trace` stays `trace`), with its severity if
+  the schema gives one, and its name as the attribute `statoss.level`. A
+  name in neither the schema nor `levels` is sent as `error`.
+- Each line carries `sentry.environment`, `sentry.release`,
+  `sentry.sdk.name`, `sentry.sdk.version` and `server.address`, and with
+  `sendDefaultPii: true` the scope's `user.id`, `user.email` and
+  `user.name`. A line's own attributes win.
+- Each line carries a `trace_id` of 32 hex digits, one for the life of the
+  client, since Sentry's Relay drops a line without one.
+- `beforeSendLog(log)` changes a line or drops it (return `null`).
+- A body past 64 KiB is cut there, with its size in bytes as
+  `statoss.truncated`, and an attribute's value at 8 KiB, in UTF-8 bytes,
+  as StatOSS's intake cuts and records them.
+- Lines go out 100 at a time, or 5 seconds after the first waits; `flush`
+  and `close` send what waits, and in Node, Bun and Deno so does the
+  process running out of work.
+
+With a schema, the logger `init` returns takes only its levels:
+
+```ts
+const statoss = StatOSS.init({ dsn: "...", schema, logs: true });
+
+statoss.logger.log("payment-failed", "Card declined", { orderId: 7 });
+// level "error", severity 17, attributes { "statoss.level": "payment-failed", orderId: 7 }
+
+// @ts-expect-error: not a level of the schema
+statoss.logger.log("payment-faild", "Card declined");
+```
+
 ## What is captured
 
 | Integration      | Runtimes                 | What it does                                          |
@@ -423,8 +474,11 @@ await StatOSS.withScope(async (scope) => {
 ## API
 
 ```ts
-init(options): handle                                // handle.captureException, captureMessage, captureEvent
+init(options): handle                                // handle.captureException, captureMessage, captureEvent, logger
 defineSchema(schema): schema                         // the schema as given, its names as types
+logger.trace, debug, info, warn, error, fatal(message, attributes?)
+logger.log(level, message, attributes?)              // a level by name, your own too
+logger.fmt`text ${value}`                            // a message with its template and values
 captureException(error, context?): string            // returns the event id
 captureMessage(message, levelOrContext?): string
 captureEvent(event, context?): string
@@ -458,11 +512,13 @@ that one event.
 | `beforeSend`       |                | `(event, hint) => event \| null`, may be async         |
 | `beforeBreadcrumb` |                | `(breadcrumb, hint) => breadcrumb \| null`             |
 | `maxBreadcrumbs`   | `100`          | 100 at most                                            |
-| `sendDefaultPii`   | `false`        | Record the sender's IP address                         |
+| `sendDefaultPii`   | `false`        | Record the sender's IP address; the user on log lines  |
 | `tags`             |                | Tags on every event                                    |
 | `initialScope`     |                | `{ tags, extra, contexts, user, level, fingerprint }`  |
 | `schema`           |                | From `defineSchema`: your levels, categories, fields   |
 | `levels`           |                | Your level names and the Sentry level each is sent as  |
+| `logs`             | `false`        | Send `logger`'s lines                                  |
+| `beforeSendLog`    |                | `(log) => log \| null`                                 |
 | `integrations`     | all on         | See above                                              |
 | `enabled`          | `true`         |                                                        |
 | `debug`            | `false`        | Log what the SDK does                                  |
@@ -470,14 +526,16 @@ that one event.
 
 ## Sending to Sentry
 
-Use a Sentry DSN instead. Events, client reports, rate limits (including a
-used-up quota) and the `X-Sentry-Auth` header all follow Sentry's protocol.
-Custom levels arrive as Sentry levels with the `statoss.level` tag.
+Use a Sentry DSN instead. Events, log lines, client reports, rate limits
+(including a used-up quota) and the `X-Sentry-Auth` header all follow
+Sentry's protocol. Custom levels arrive as Sentry levels with the
+`statoss.level` tag, on events and log lines alike.
 
 ## Network behaviour
 
 Envelopes go to `https://<host>/api/<app number>/envelope/`, at most 5 at a
-time and 30 queued or in flight; more are dropped and counted. When the server answers 429, the SDK holds back
+time and 30 queued or in flight, of them at most 10 of log lines; more are
+dropped and counted. When the server answers 429, the SDK holds back
 the limited categories for as long as `Retry-After` or `X-Sentry-Rate-Limits`
 says. Events it could not send (queue full, rate limited, network error,
 sampled out, dropped by `beforeSend`) are counted and reported as Sentry

package/dist/cjs/client.d.ts

@@ -16,6 +16,8 @@ export declare class Client {
     private readonly endpoint?;
     private readonly sender?;
     private readonly levels;
+    private readonly logLevels;
+    private readonly logsOn;
     private readonly sampleRate;
     private readonly maxBreadcrumbs;
     private readonly discarded;
@@ -24,9 +26,22 @@ export declare class Client {
     private reportTimer?;
     private previousSignature?;
     private closed;
+    private logBuffer;
+    private logChars;
+    private logTimer?;
+    private saidLogsOff;
+    /** The trace id of every log line: one per client, as Sentry's SDKs do without tracing. */
+    private logTraceId;
     constructor(options: ClientOptions);
     /** Installs the integrations that apply to this runtime. */
     setup(): void;
+    /**
+     * Keeps a log line for the next envelope of lines. The level is one of
+     * the six, a Sentry level, or the app's own (sent at its range's level
+     * with statoss.level); attributes go along typed, as Sentry's logger
+     * sends them.
+     */
+    captureLog(level: unknown, message: unknown, attributes: unknown, scope: Scope): void;
     captureException(error: unknown, context: CaptureContext | undefined, scope: Scope): string;
     captureMessage(message: unknown, context: CaptureContext | undefined, scope: Scope): string;
     captureEvent(event: Event, context: CaptureContext | undefined, scope: Scope): string;
@@ -41,8 +56,16 @@ export declare class Client {
     flush(timeoutMs?: number): Promise<boolean>;
     /** Flushes, then removes the integrations. Nothing is captured afterwards. */
     close(timeoutMs?: number): Promise<boolean>;
-    /** Removes the integrations at once, without waiting. */
+    /** Removes the integrations at once, without waiting; log lines kept go out. */
     teardown(): void;
+    private keepLog;
+    /** Sends the log lines kept, as one envelope. */
+    private sendLogs;
+    /**
+     * In Node, Bun and Deno: sends the lines kept when the process runs out
+     * of work, since the timer that would send them does not keep it alive.
+     */
+    private sendLogsBeforeExit;
     private flushReportsWhenHidden;
     private capture;
     /** Merges scope, context and options into the event, in Sentry's field order. */

package/dist/cjs/client.js

@@ -13,6 +13,7 @@ const fetch_js_1 = require("./integrations/fetch.js");
 const handlers_js_1 = require("./integrations/handlers.js");
 const levels_js_1 = require("./levels.js");
 const logger_js_1 = require("./logger.js");
+const logs_js_1 = require("./logs.js");
 const runtime_js_1 = require("./runtime.js");
 const schema_js_1 = require("./schema.js");
 const scope_js_1 = require("./scope.js");
@@ -21,6 +22,11 @@ const utils_js_1 = require("./utils.js");
 const version_js_1 = require("./version.js");
 const REPORT_INTERVAL_MS = 30000;
 const DEFAULT_FLUSH_MS = 2000;
+// Log lines go out 100 at a time, or 5 seconds after the first waits, as
+// Sentry's logger sends them, and well under an envelope item's 1 MiB.
+const LOG_BATCH = 100;
+const LOG_WAIT_MS = 5000;
+const LOG_BATCH_CHARS = 800000;
 // The server drops event items over 1 MiB.
 const MAX_EVENT_CHARS = 1000000;
 const MAX_TAG_VALUE = 200;
@@ -55,6 +61,41 @@ function cleanTags(tags) {
     }
     return out;
 }
+/**
+ * A line as a log item holds it, made valid again after beforeSendLog: one
+ * of the six levels, a severity inside its range, typed attributes.
+ */
+function serializeLog(log, traceId) {
+    const level = (0, logs_js_1.isLogLevel)(log.level)
+        ? log.level
+        : ((0, logs_js_1.logLevelOf)((0, utils_js_1.safeString)(log.level)) ?? "info");
+    const n = log.severityNumber;
+    const severity = typeof n === "number" &&
+        Number.isInteger(n) &&
+        n >= logs_js_1.LOG_SEVERITY[level] &&
+        n <= logs_js_1.LOG_SEVERITY[level] + 3
+        ? n
+        : logs_js_1.LOG_SEVERITY[level];
+    const attributes = {};
+    if ((0, utils_js_1.isObject)(log.attributes)) {
+        for (const [key, value] of Object.entries(log.attributes)) {
+            const typed = (0, logs_js_1.serializeAttribute)(value);
+            if (key !== "" && typed)
+                attributes[key] = typed;
+        }
+    }
+    const body = (0, logs_js_1.cutBody)((0, logs_js_1.bodyOf)(log.message), attributes);
+    return {
+        timestamp: typeof log.timestamp === "number" && Number.isFinite(log.timestamp)
+            ? log.timestamp
+            : (0, utils_js_1.now)(),
+        level,
+        body,
+        trace_id: traceId,
+        severity_number: severity,
+        attributes,
+    };
+}
 /** A capture's fields, as tags. Keys starting statoss. are not fields. */
 function fieldTags(fields, logger) {
     const out = {};
@@ -127,14 +168,20 @@ class Client {
         this.pending = new Set();
         this.teardowns = [];
         this.closed = false;
+        this.logBuffer = [];
+        this.logChars = 0;
+        this.saidLogsOff = false;
         this.options = options;
         this.logger = (0, logger_js_1.makeLogger)(options.debug === true);
         this.runtime = (0, runtime_js_1.describeRuntime)();
         // What `levels` says wins over the schema.
-        this.levels = {
-            ...(0, schema_js_1.readSchema)(options.schema, this.logger),
-            ...(0, levels_js_1.readLevels)(options.levels, this.logger),
+        const given = (0, levels_js_1.readLevels)(options.levels, this.logger);
+        this.levels = { ...(0, schema_js_1.readSchema)(options.schema, this.logger), ...given };
+        this.logLevels = {
+            ...(0, schema_js_1.schemaLogLevels)(options.schema),
+            ...(0, logs_js_1.ownLevelsFromSentry)(given),
         };
+        this.logsOn = options.logs === true;
         const rate = options.sampleRate;
         if (rate !== undefined &&
             !(typeof rate === "number" && rate >= 0 && rate <= 1)) {
@@ -213,8 +260,90 @@ class Client {
             this.integrations.push("Dedupe");
         if (browser)
             this.flushReportsWhenHidden();
+        if (this.logsOn)
+            this.sendLogsBeforeExit();
         this.logger.log(`Integrations: ${this.integrations.join(", ") || "none"}.`);
     }
+    /**
+     * Keeps a log line for the next envelope of lines. The level is one of
+     * the six, a Sentry level, or the app's own (sent at its range's level
+     * with statoss.level); attributes go along typed, as Sentry's logger
+     * sends them.
+     */
+    captureLog(level, message, attributes, scope) {
+        if (!this.enabled || this.closed)
+            return;
+        if (!this.logsOn) {
+            if (!this.saidLogsOff) {
+                this.saidLogsOff = true;
+                this.logger.log("Log lines are not sent: init has no logs: true.");
+            }
+            return;
+        }
+        try {
+            const choice = (0, logs_js_1.chooseLogLevel)(level, this.logLevels, this.logger);
+            const attrs = {};
+            if ((0, utils_js_1.isObject)(attributes) && !Array.isArray(attributes)) {
+                for (const [key, value] of Object.entries(attributes))
+                    if (key !== "")
+                        attrs[key] = value;
+            }
+            else if (attributes !== undefined && attributes !== null) {
+                this.logger.warn("Ignored a log line's attributes: they should be an object such as { orderId: 7 }.");
+            }
+            // What the line says wins over what the SDK adds.
+            const add = (key, value) => {
+                if (value !== undefined && value !== null && !(key in attrs))
+                    attrs[key] = value;
+            };
+            add("sentry.environment", this.options.environment ?? "production");
+            add("sentry.release", this.options.release);
+            add("sentry.sdk.name", version_js_1.SDK_NAME);
+            add("sentry.sdk.version", version_js_1.SDK_VERSION);
+            add("server.address", this.options.serverName ?? this.runtime.serverName);
+            // The user goes on a line only with sendDefaultPii.
+            const user = scope._user;
+            if (user && this.options.sendDefaultPii) {
+                add("user.id", user.id);
+                add("user.email", user.email);
+                add("user.name", user.username);
+            }
+            if ((0, logs_js_1.isLogMessage)(message) && message.values.length > 0) {
+                attrs["sentry.message.template"] = message.template;
+                message.values.forEach((value, i) => {
+                    attrs[`sentry.message.parameter.${i}`] = value;
+                });
+            }
+            if (choice.custom)
+                attrs[levels_js_1.LEVEL_TAG] = choice.custom;
+            let log = {
+                level: choice.level,
+                message: (0, logs_js_1.bodyOf)(message),
+                attributes: attrs,
+                severityNumber: choice.severity,
+                timestamp: (0, utils_js_1.now)(),
+            };
+            if (this.options.beforeSendLog) {
+                try {
+                    log = this.options.beforeSendLog(log);
+                }
+                catch (error) {
+                    this.logger.error("beforeSendLog threw, so the line was dropped:", error);
+                    this.recordLoss("internal_sdk_error", "log_item");
+                    return;
+                }
+                if (!(0, utils_js_1.isObject)(log)) {
+                    this.recordLoss("before_send", "log_item");
+                    return;
+                }
+            }
+            this.logTraceId ?? (this.logTraceId = (0, utils_js_1.uuid4)());
+            this.keepLog(serializeLog(log, this.logTraceId));
+        }
+        catch (error) {
+            this.logger.error("Could not capture a log line:", error);
+        }
+    }
     captureException(error, context, scope) {
         return this.capture(() => (0, event_js_1.eventFromUnknown)(error, { type: "generic", handled: true }), context, scope, { originalException: error });
     }
@@ -297,6 +426,7 @@ class Client {
     async flush(timeoutMs = DEFAULT_FLUSH_MS) {
         if (!this.sender)
             return true;
+        this.sendLogs();
         const deadline = Date.now() + timeoutMs;
         const left = () => Math.max(0, deadline - Date.now());
         const processed = this.pending.size
@@ -317,18 +447,63 @@ class Client {
         this.teardown();
         return this.flush(timeoutMs);
     }
-    /** Removes the integrations at once, without waiting. */
+    /** Removes the integrations at once, without waiting; log lines kept go out. */
     teardown() {
         for (const teardown of this.teardowns.splice(0))
             (0, utils_js_1.safely)(teardown);
+        this.sendLogs();
+    }
+    keepLog(log) {
+        const size = (0, utils_js_1.safely)(() => JSON.stringify(log).length, 0) ?? 0;
+        if (this.logBuffer.length > 0 && this.logChars + size > LOG_BATCH_CHARS)
+            this.sendLogs();
+        this.logBuffer.push(log);
+        this.logChars += size;
+        if (this.logBuffer.length >= LOG_BATCH) {
+            this.sendLogs();
+        }
+        else if (this.logTimer === undefined) {
+            this.logTimer = (0, utils_js_1.safely)(() => setTimeout(() => {
+                this.logTimer = undefined;
+                this.sendLogs();
+            }, LOG_WAIT_MS));
+            (0, utils_js_1.unref)(this.logTimer);
+        }
+    }
+    /** Sends the log lines kept, as one envelope. */
+    sendLogs() {
+        if (this.logTimer !== undefined) {
+            clearTimeout(this.logTimer);
+            this.logTimer = undefined;
+        }
+        if (this.logBuffer.length === 0 || !this.sender || !this.dsn)
+            return;
+        const logs = this.logBuffer;
+        this.logBuffer = [];
+        this.logChars = 0;
+        this.sender.send((0, envelope_js_1.logEnvelope)(logs, this.dsn));
+    }
+    /**
+     * In Node, Bun and Deno: sends the lines kept when the process runs out
+     * of work, since the timer that would send them does not keep it alive.
+     */
+    sendLogsBeforeExit() {
+        const proc = globalThis.process;
+        if (!proc || typeof proc.on !== "function")
+            return;
+        const onBeforeExit = () => (0, utils_js_1.safely)(() => this.sendLogs());
+        (0, utils_js_1.safely)(() => proc.on("beforeExit", onBeforeExit));
+        this.teardowns.push(() => proc.removeListener?.("beforeExit", onBeforeExit));
     }
     flushReportsWhenHidden() {
         const doc = globalThis.document;
         if (!doc || typeof doc.addEventListener !== "function")
             return;
         const onChange = () => {
-            if (doc.visibilityState === "hidden")
-                (0, utils_js_1.safely)(() => this.sendClientReport());
+            if (doc.visibilityState !== "hidden")
+                return;
+            (0, utils_js_1.safely)(() => this.sendLogs());
+            (0, utils_js_1.safely)(() => this.sendClientReport());
         };
         doc.addEventListener("visibilitychange", onChange);
         this.teardowns.push(() => doc.removeEventListener?.("visibilitychange", onChange));

package/dist/cjs/envelope.d.ts

@@ -1,4 +1,5 @@
 import { type Dsn } from "./dsn.js";
+import type { SerializedLog } from "./logs.js";
 import type { Event } from "./types.js";
 export interface DiscardedEvent {
     reason: string;
@@ -26,11 +27,29 @@ export type ClientReportItem = [
         discarded_events: DiscardedEvent[];
     }
 ];
-export type EnvelopeItem = EventItem | ClientReportItem;
+export declare const LOG_CONTENT_TYPE = "application/vnd.sentry.items.log+json";
+export type LogItem = [
+    {
+        type: "log";
+        item_count: number;
+        content_type: typeof LOG_CONTENT_TYPE;
+    },
+    {
+        version: 2;
+        items: SerializedLog[];
+    }
+];
+export type EnvelopeItem = EventItem | ClientReportItem | LogItem;
 export type Envelope = [EnvelopeHeader, EnvelopeItem[]];
 export declare function eventEnvelope(event: Event, dsn: Dsn): Envelope;
 export declare function clientReportEnvelope(discarded: DiscardedEvent[], dsn: Dsn, timestamp?: number): Envelope;
+/** Log lines in one envelope, as Sentry's logger sends them. */
+export declare function logEnvelope(logs: SerializedLog[], dsn: Dsn): Envelope;
 /** Sentry's rate-limit category for an envelope item. */
 export declare function itemCategory(item: EnvelopeItem): string;
+/** How many things an item holds, as client reports count them. */
+export declare function itemQuantity(item: EnvelopeItem): number;
+/** True for an envelope of log lines. */
+export declare function isLogEnvelope(envelope: Envelope): boolean;
 /** Byte for byte what Sentry's serializeEnvelope produces for string payloads. */
 export declare function serializeEnvelope(envelope: Envelope): string;

package/dist/cjs/envelope.js

@@ -1,12 +1,17 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.LOG_CONTENT_TYPE = void 0;
 exports.eventEnvelope = eventEnvelope;
 exports.clientReportEnvelope = clientReportEnvelope;
+exports.logEnvelope = logEnvelope;
 exports.itemCategory = itemCategory;
+exports.itemQuantity = itemQuantity;
+exports.isLogEnvelope = isLogEnvelope;
 exports.serializeEnvelope = serializeEnvelope;
 const dsn_js_1 = require("./dsn.js");
 const utils_js_1 = require("./utils.js");
 const version_js_1 = require("./version.js");
+exports.LOG_CONTENT_TYPE = "application/vnd.sentry.items.log+json";
 function sdkHeader() {
     return { name: version_js_1.SDK_NAME, version: version_js_1.SDK_VERSION };
 }
@@ -31,9 +36,44 @@ function clientReportEnvelope(discarded, dsn, timestamp = Date.now() / 1000) {
         [[{ type: "client_report" }, { timestamp, discarded_events: discarded }]],
     ];
 }
+/** Log lines in one envelope, as Sentry's logger sends them. */
+function logEnvelope(logs, dsn) {
+    return [
+        {
+            sent_at: new Date().toISOString(),
+            dsn: (0, dsn_js_1.dsnToString)(dsn),
+            sdk: sdkHeader(),
+        },
+        [
+            [
+                {
+                    type: "log",
+                    item_count: logs.length,
+                    content_type: exports.LOG_CONTENT_TYPE,
+                },
+                { version: 2, items: logs },
+            ],
+        ],
+    ];
+}
 /** Sentry's rate-limit category for an envelope item. */
 function itemCategory(item) {
-    return item[0].type === "event" ? "error" : "internal";
+    switch (item[0].type) {
+        case "event":
+            return "error";
+        case "log":
+            return "log_item";
+        default:
+            return "internal";
+    }
+}
+/** How many things an item holds, as client reports count them. */
+function itemQuantity(item) {
+    return item[0].type === "log" ? item[0].item_count : 1;
+}
+/** True for an envelope of log lines. */
+function isLogEnvelope(envelope) {
+    return envelope[1].some((item) => item[0].type === "log");
 }
 function stringify(payload) {
     try {

package/dist/cjs/index.d.ts

@@ -1,6 +1,8 @@
+import { type AppLogger } from "./logs.js";
 import type { CheckSchema, Handle, SchemaSpec } from "./schema.js";
 import type { Breadcrumb, CaptureContext, Event, InitOptions, Level, Primitive, User } from "./types.js";
 export { withScope } from "./hub.js";
+export type { AppLogger, Log, LogAttributes, LogAttributeValue, LogLevel, LogLevelOf, LogMessage, SerializedLog, } from "./logs.js";
 export { defineSchema } from "./schema.js";
 export type { CategoryOf, CategorySettings, CheckSchema, FieldOf, FieldSettings, FieldType, FieldValue, Handle, LevelOf, LevelSettings, Like, RuleMatch, RuleSubject, SchemaColor, SchemaContext, SchemaRule, SchemaSpec, Severity, } from "./schema.js";
 export type { Scope } from "./scope.js";
@@ -9,11 +11,11 @@ export type { Breadcrumb, BreadcrumbHint, CaptureContext, DebugImage, Event, Eve
 /**
  * Starts the SDK. Call it once, as early as you can. Calling it again replaces
  * the earlier setup. Without a valid DSN, or with enabled: false, nothing is
- * sent and nothing is patched.
+ * sent and nothing is patched. With `logs: true`, `logger`'s lines are sent.
  *
  * With a `schema` from defineSchema, its levels are sent as the Sentry level
- * each ranks like, and the capture functions it returns take only the
- * schema's levels, categories and fields.
+ * each ranks like, and the capture functions and logger it returns take
+ * only the schema's levels, categories and fields.
  */
 export declare function init<const S extends SchemaSpec & CheckSchema<S> = SchemaSpec>(options?: InitOptions & {
     schema?: S;
@@ -27,6 +29,12 @@ export declare function captureException(error: unknown, context?: CaptureContex
 export declare function captureMessage(message: string, levelOrContext?: Level | CaptureContext): string;
 /** Sends an event you built in Sentry's schema. Returns the event id. */
 export declare function captureEvent(event: Event, context?: CaptureContext): string;
+/**
+ * Log lines, sent when init has `logs: true`: logger.info("Paid", { orderId: 7 }),
+ * logger.warn(logger.fmt`Took ${ms} ms`), logger.log("payment-failed", "Card declined").
+ * Lines go out in batches; flush() and close() send what waits.
+ */
+export declare const logger: AppLogger;
 /** Pass null to forget the user. */
 export declare function setUser(user: User | null): void;
 export declare function setTag(key: string, value: Primitive): void;

package/dist/cjs/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SDK_VERSION = exports.SDK_NAME = exports.defineSchema = exports.withScope = void 0;
+exports.logger = exports.SDK_VERSION = exports.SDK_NAME = exports.defineSchema = exports.withScope = void 0;
 exports.init = init;
 exports.captureException = captureException;
 exports.captureMessage = captureMessage;
@@ -16,6 +16,7 @@ exports.close = close;
 exports.lastEventId = lastEventId;
 const client_js_1 = require("./client.js");
 const hub_js_1 = require("./hub.js");
+const logs_js_1 = require("./logs.js");
 const utils_js_1 = require("./utils.js");
 var hub_js_2 = require("./hub.js");
 Object.defineProperty(exports, "withScope", { enumerable: true, get: function () { return hub_js_2.withScope; } });
@@ -59,12 +60,19 @@ function captureMessage(message, levelOrContext) {
 function captureEvent(event, context) {
     return (0, hub_js_1.captureWith)(undefined, (client, scope) => client.captureEvent(event, context, scope));
 }
+/**
+ * Log lines, sent when init has `logs: true`: logger.info("Paid", { orderId: 7 }),
+ * logger.warn(logger.fmt`Took ${ms} ms`), logger.log("payment-failed", "Card declined").
+ * Lines go out in batches; flush() and close() send what waits.
+ */
+exports.logger = (0, logs_js_1.makeAppLogger)((level, message, attributes) => (0, utils_js_1.safely)(() => (0, hub_js_1.getCarrier)().client?.captureLog(level, message, attributes, (0, hub_js_1.getCurrentScope)())));
 // What init returns: the same functions, typed by the schema. The client
 // reads a context's fields whichever function it came through.
 const HANDLE = Object.freeze({
     captureException,
     captureMessage,
     captureEvent,
+    logger: exports.logger,
 });
 /** Pass null to forget the user. */
 function setUser(user) {