@statoss/sdk 0.2.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
@@ -269,20 +269,88 @@ Adding `--release <release>` to the upload is optional. Deploy the bundles as
 `inject` left them: the SDK reads their debug ids and sends them with each
 event. Frames are then shown as source and grouped by their source names.
 
-## Custom levels and categories
+## Your own levels, categories and fields
 
 Sentry has five levels: `fatal`, `error`, `warning`, `info` and `debug`.
-StatOSS lets you use your own words as well, and adds a category. Both are
-sent as tags next to the nearest Sentry level, so Sentry and any Sentry-based
-tool still read the event normally.
+StatOSS adds levels of your own, categories and fields. They travel as tags
+next to the nearest Sentry level, so Sentry and any Sentry-based tool still
+read the event normally.
+
+Declare them with `defineSchema` and give the schema to `init`. The capture
+functions `init` returns take only the schema's names, so a wrong one fails
+to compile.
 
 ```ts
-StatOSS.init({
-  dsn: "...",
+import * as StatOSS from "@statoss/sdk";
+
+export const schema = StatOSS.defineSchema({
   levels: {
-    "payment-failed": "error",
+    "payment-failed": { like: "error", label: "Payment failed" },
     "slow-query": "warning",
   },
+  categories: {
+    billing: { label: "Billing", color: "plum" },
+    auth: {},
+  },
+  fields: {
+    route: { label: "Route", filterable: true },
+    duration_ms: { type: "number", unit: "ms", label: "Duration" },
+  },
+});
+
+const statoss = StatOSS.init({ dsn: process.env.STATOSS_DSN, schema });
+
+statoss.captureException(error, {
+  level: "payment-failed",
+  category: "billing",
+  fields: { route: "/pay" },
+});
+// level "error", tags { "statoss.level": "payment-failed",
+//   "statoss.category": "billing", route: "/pay" }
+
+statoss.captureMessage("Search took 2.4 s", {
+  level: "slow-query",
+  fields: { duration_ms: 2400 },
+});
+
+// @ts-expect-error: not a level of this schema
+statoss.captureException(error, { level: "payment-faild" });
+```
+
+- A level ranks like `fatal`, `error`, `warning`, `info`, `debug` or
+  `trace`: give that alone, or `like` with an optional `severity` (1 to 24,
+  inside its range), `label` and `color`. It is sent as the nearest Sentry
+  level (`trace` as `debug`; `error` when none is given).
+- A category takes an optional `label`, `color`, `owner` (a team member's
+  email) and `hidden`.
+- A field is a tag key, with an optional `label`, `type` (`text` or
+  `number`), `unit` and `filterable`. Field values are strings, numbers or
+  booleans.
+- Categories and fields can also be lists of names.
+- `rules` set a level or a category for events that match, such as
+  `{ subject: "logger", value: "payments", category: "billing" }`. They name
+  the schema's own levels and categories.
+- Colours: `crimson`, `red`, `orange`, `amber`, `yellow`, `green`, `aqua`,
+  `teal`, `blue`, `violet`, `indigo`, `magenta`, `plum` and `grey`.
+- Names: a level is 1 to 32 characters and a category 1 to 64, of lowercase
+  letters, digits, dots, dashes and underscores. A field is any tag key not
+  starting `statoss.`.
+
+`defineSchema` refuses a wrong name, range, severity, colour or setting at
+compile time (TypeScript 5.0 or later). It returns the schema as given:
+plain data in the shape StatOSS's schema API takes. A function of yours
+that hands a schema to `init` types it as
+`<const S extends SchemaSpec & CheckSchema<S>>(schema: S)`.
+
+### Without a schema
+
+The module-level functions take any level or category name, and `levels` in
+`init` maps your names to Sentry levels:
+
+```ts
+StatOSS.init({
+  dsn: "...",
+  levels: { "payment-failed": "error", "slow-query": "warning" },
 });
 
 StatOSS.captureMessage("Card declined", "payment-failed");
@@ -295,13 +363,63 @@ StatOSS.captureException(error, {
 // level "warning", tags { "statoss.level": "slow-query", "statoss.category": "db.postgres" }
 ```
 
-- `level` takes a Sentry level or any name of your own. A name that is not in
-  `levels` is sent as `error`.
-- `category` sets the `statoss.category` tag.
-- Names are 1 to 64 characters of lowercase letters, digits, dots, dashes and
-  underscores. Others are ignored; with `debug: true` the SDK logs each one.
+- A name in neither `levels` nor the schema is sent as `error`. Given both,
+  `levels` wins.
+- Names the SDK cannot send are ignored; with `debug: true` it logs each
+  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                                          |
@@ -356,7 +474,11 @@ await StatOSS.withScope(async (scope) => {
 ## API
 
 ```ts
-init(options): void
+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
@@ -374,8 +496,9 @@ scope.setUser, setTag, setTags, setExtra, setExtras, setContext, setLevel,
 scope.captureException, captureMessage, captureEvent // with this scope
 ```
 
-`context` is `{ level, tags, extra, contexts, user, fingerprint, category }`.
-It wins over the scope for that one event.
+`context` is `{ level, tags, extra, contexts, user, fingerprint, category }`,
+and on the handle `init` returns also `fields`. It wins over the scope for
+that one event.
 
 ### Options
 
@@ -389,10 +512,13 @@ It wins over the scope for 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                                  |
@@ -400,14 +526,16 @@ It wins over the scope for 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

@@ -2,6 +2,10 @@ import { type Logger } from "./logger.js";
 import { type RuntimeInfo } from "./runtime.js";
 import { type Scope } from "./scope.js";
 import type { Breadcrumb, BreadcrumbHint, CaptureContext, Event, InitOptions } from "./types.js";
+/** init's options as the client reads them: init may pass a schema. */
+export type ClientOptions = InitOptions & {
+    schema?: unknown;
+};
 export declare class Client {
     readonly logger: Logger;
     readonly runtime: RuntimeInfo;
@@ -12,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;
@@ -20,9 +26,22 @@ export declare class Client {
     private reportTimer?;
     private previousSignature?;
     private closed;
-    constructor(options: InitOptions);
+    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;
@@ -37,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,13 +13,20 @@ 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");
 const transport_js_1 = require("./transport.js");
 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;
@@ -54,6 +61,67 @@ 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 = {};
+    if (fields === undefined || fields === null)
+        return out;
+    if (!(0, utils_js_1.isObject)(fields) || Array.isArray(fields)) {
+        logger.warn('Ignored `fields`: it should be an object such as { route: "/pay" }.');
+        return out;
+    }
+    for (const [key, value] of Object.entries(fields)) {
+        if (value === undefined || value === null)
+            continue;
+        if (key === "" || key.startsWith("statoss.")) {
+            logger.warn(`Ignored field "${key}": fields are not empty and do not start statoss.`);
+        }
+        else if (typeof value === "string" ||
+            typeof value === "number" ||
+            typeof value === "boolean") {
+            out[key] = value;
+        }
+        else {
+            logger.warn(`Ignored field "${key}": its value should be a string, number or boolean.`);
+        }
+    }
+    return out;
+}
 function cleanContexts(contexts) {
     const out = {};
     for (const [name, value] of Object.entries(contexts)) {
@@ -100,10 +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)();
-        this.levels = (0, levels_js_1.readLevels)(options.levels, this.logger);
+        // What `levels` says wins over the schema.
+        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)) {
@@ -182,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 });
     }
@@ -266,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
@@ -286,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));
@@ -329,6 +535,7 @@ class Client {
         const tags = {
             ...scope._tags,
             ...ctx.tags,
+            ...fieldTags(ctx.fields, this.logger),
             ...base.tags,
         };
         if (choice.custom)

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;