@statoss/sdk 0.3.0 → 0.4.0

package/dist/cjs/logs.d.ts

@@ -0,0 +1,133 @@
+import type { Logger } from "./logger.js";
+import type { LevelOf, SchemaSpec } from "./schema.js";
+import type { SentryLevel } from "./types.js";
+/**
+ * Log lines, as Sentry's logger sends them: `log` items in envelopes, each
+ * line with a level, a body and typed attributes
+ * (https://develop.sentry.dev/sdk/telemetry/logs/).
+ */
+/** The levels of a log line: OpenTelemetry's six ranges, as Sentry's logger names them. */
+export type LogLevel = "trace" | "debug" | "info" | "warn" | "error" | "fatal";
+export declare const LOG_LEVELS: readonly LogLevel[];
+/** What intake keeps of a line (docs/logs.md, In), in UTF-8 bytes: a body, and an attribute's value. */
+export declare const MAX_BODY_BYTES: number;
+export declare const MAX_ATTRIBUTE_BYTES: number;
+/** A cut body's size in bytes before the cut, as intake records it. */
+export declare const TRUNCATED = "statoss.truncated";
+/** Each level's severity number: the start of its OpenTelemetry range. */
+export declare const LOG_SEVERITY: Readonly<Record<LogLevel, number>>;
+export declare function isLogLevel(value: unknown): value is LogLevel;
+/** The level a range (a schema's `like`) or a Sentry level is logged at. */
+export declare function logLevelOf(range: string): LogLevel | undefined;
+/** The range a severity number falls in. */
+export declare function rangeOfSeverity(severity: number): LogLevel;
+/** A message made by `logger.fmt`: the text, and the template and values it came from. */
+export interface LogMessage {
+    /** The message, its values filled in. */
+    readonly text: string;
+    /** The template, each value written %s, as Sentry's logger writes it. */
+    readonly template: string;
+    readonly values: readonly unknown[];
+    toString(): string;
+}
+/**
+ * A message with parameters: logger.info(logger.fmt`Paid ${amount} for ${order}`).
+ * The line's body is the text; the template and each value go along as
+ * the attributes sentry.message.template and sentry.message.parameter.<n>.
+ */
+export declare function fmt(strings: TemplateStringsArray, ...values: unknown[]): LogMessage;
+export declare function isLogMessage(value: unknown): value is LogMessage;
+/** A line's attributes: strings, numbers and booleans are sent as they are, anything else as JSON. */
+export type LogAttributes = Record<string, unknown>;
+/** A log line before it is sent, as beforeSendLog sees it. */
+export interface Log {
+    level: LogLevel;
+    /** The message, with its values filled in. */
+    message: string;
+    attributes: LogAttributes;
+    /** 1 to 24, inside the level's range. */
+    severityNumber: number;
+    /** Seconds since the epoch, with fractions. */
+    timestamp: number;
+}
+export type LogAttributeValue = {
+    value: string;
+    type: "string";
+} | {
+    value: number;
+    type: "integer";
+} | {
+    value: number;
+    type: "double";
+} | {
+    value: boolean;
+    type: "boolean";
+};
+/** A log line as an envelope's log item holds it. */
+export interface SerializedLog {
+    timestamp: number;
+    level: LogLevel;
+    body: string;
+    /** 32 lower-case hex digits; Sentry's Relay drops a line without one. */
+    trace_id: string;
+    severity_number: number;
+    attributes: Record<string, LogAttributeValue>;
+}
+/** An attribute's value as Sentry types it; undefined and null are left out. */
+export declare function serializeAttribute(value: unknown): LogAttributeValue | undefined;
+/** A string's length in UTF-8 bytes. */
+export declare function utf8Length(s: string): number;
+/**
+ * A string cut to at most `max` UTF-8 bytes, the cut marked "...", as
+ * intake's cut writes it (intake/normalize.ts), never inside a character.
+ */
+export declare function cutBytes(s: string, max: number): string;
+/**
+ * A body past 64 KiB is cut there, with its size in bytes as
+ * statoss.truncated, as intake cuts it and records it: one huge line must
+ * not take the batch it is sent in down with it.
+ */
+export declare function cutBody(body: string, attributes: Record<string, LogAttributeValue>): string;
+/** The message, or a value in it, as text: objects as JSON. */
+export declare function bodyOf(message: unknown): string;
+/** A level of the app's own, as a line is logged at it. */
+export interface OwnLogLevel {
+    level: LogLevel;
+    severity: number;
+}
+export interface LogLevelChoice {
+    level: LogLevel;
+    severity: number;
+    /** The app's own level, when the line names one. */
+    custom?: string;
+}
+/**
+ * The level a line is logged at. One of the six (or a Sentry level) is
+ * itself; an app's own level is its range's, with its severity and its
+ * name for statoss.level; a name nobody declared ranks as error, as an
+ * event's does. Anything else is logged as info.
+ */
+export declare function chooseLogLevel(level: unknown, own: Record<string, OwnLogLevel>, logger: Logger): LogLevelChoice;
+/** The ranges of init's `levels`: a Sentry level each. */
+export declare function ownLevelsFromSentry(levels: Record<string, SentryLevel>): Record<string, OwnLogLevel>;
+/** What `logger` and the handle's `logger` take as a level, typed by the schema. */
+export type LogLevelOf<S = SchemaSpec> = LogLevel | LevelOf<S>;
+/** The logger: one method per level, any level by name, and templates. */
+export interface AppLogger<S = SchemaSpec> {
+    trace(message: string | LogMessage, attributes?: LogAttributes): void;
+    debug(message: string | LogMessage, attributes?: LogAttributes): void;
+    info(message: string | LogMessage, attributes?: LogAttributes): void;
+    warn(message: string | LogMessage, attributes?: LogAttributes): void;
+    error(message: string | LogMessage, attributes?: LogAttributes): void;
+    fatal(message: string | LogMessage, attributes?: LogAttributes): void;
+    /**
+     * A line at a level by name: one of the six, a Sentry level, or one of
+     * the app's own (with a schema, only its names). An own level is sent at
+     * its range's level with the attribute statoss.level.
+     */
+    log(level: LogLevelOf<S>, message: string | LogMessage, attributes?: LogAttributes): void;
+    /** A message with parameters: logger.fmt`Paid ${amount}`. */
+    fmt(strings: TemplateStringsArray, ...values: unknown[]): LogMessage;
+}
+/** A logger that hands each line to `capture`. */
+export declare function makeAppLogger(capture: (level: unknown, message: unknown, attributes: LogAttributes | undefined) => void): AppLogger;

package/dist/cjs/logs.js

@@ -0,0 +1,235 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LOG_SEVERITY = exports.TRUNCATED = exports.MAX_ATTRIBUTE_BYTES = exports.MAX_BODY_BYTES = exports.LOG_LEVELS = void 0;
+exports.isLogLevel = isLogLevel;
+exports.logLevelOf = logLevelOf;
+exports.rangeOfSeverity = rangeOfSeverity;
+exports.fmt = fmt;
+exports.isLogMessage = isLogMessage;
+exports.serializeAttribute = serializeAttribute;
+exports.utf8Length = utf8Length;
+exports.cutBytes = cutBytes;
+exports.cutBody = cutBody;
+exports.bodyOf = bodyOf;
+exports.chooseLogLevel = chooseLogLevel;
+exports.ownLevelsFromSentry = ownLevelsFromSentry;
+exports.makeAppLogger = makeAppLogger;
+const levels_js_1 = require("./levels.js");
+const utils_js_1 = require("./utils.js");
+exports.LOG_LEVELS = [
+    "trace",
+    "debug",
+    "info",
+    "warn",
+    "error",
+    "fatal",
+];
+/** What intake keeps of a line (docs/logs.md, In), in UTF-8 bytes: a body, and an attribute's value. */
+exports.MAX_BODY_BYTES = 64 * 1024;
+exports.MAX_ATTRIBUTE_BYTES = 8 * 1024;
+/** A cut body's size in bytes before the cut, as intake records it. */
+exports.TRUNCATED = "statoss.truncated";
+/** Each level's severity number: the start of its OpenTelemetry range. */
+exports.LOG_SEVERITY = {
+    trace: 1,
+    debug: 5,
+    info: 9,
+    warn: 13,
+    error: 17,
+    fatal: 21,
+};
+function isLogLevel(value) {
+    return (typeof value === "string" &&
+        exports.LOG_LEVELS.includes(value));
+}
+/** The level a range (a schema's `like`) or a Sentry level is logged at. */
+function logLevelOf(range) {
+    if (range === "warning")
+        return "warn";
+    return isLogLevel(range) ? range : undefined;
+}
+/** The range a severity number falls in. */
+function rangeOfSeverity(severity) {
+    if (severity >= 21)
+        return "fatal";
+    if (severity >= 17)
+        return "error";
+    if (severity >= 13)
+        return "warn";
+    if (severity >= 9)
+        return "info";
+    if (severity >= 5)
+        return "debug";
+    return "trace";
+}
+/**
+ * A message with parameters: logger.info(logger.fmt`Paid ${amount} for ${order}`).
+ * The line's body is the text; the template and each value go along as
+ * the attributes sentry.message.template and sentry.message.parameter.<n>.
+ */
+function fmt(strings, ...values) {
+    const parts = Array.from(strings, (s, i) => s ?? strings.raw[i]);
+    let text = parts[0];
+    for (let i = 1; i < parts.length; i++)
+        text += `${bodyOf(values[i - 1])}${parts[i]}`;
+    return Object.freeze({
+        text,
+        template: parts.map((s) => s.replace(/%/g, "%%")).join("%s"),
+        values: Object.freeze([...values]),
+        toString: () => text,
+    });
+}
+function isLogMessage(value) {
+    return ((0, utils_js_1.isObject)(value) &&
+        typeof value.text === "string" &&
+        typeof value.template === "string" &&
+        Array.isArray(value.values));
+}
+/** An attribute's value as Sentry types it; undefined and null are left out. */
+function serializeAttribute(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value === "string")
+        return { value: cutBytes(value, exports.MAX_ATTRIBUTE_BYTES), type: "string" };
+    if (typeof value === "boolean")
+        return { value, type: "boolean" };
+    if (typeof value === "number") {
+        if (!Number.isFinite(value))
+            return { value: (0, utils_js_1.safeString)(value), type: "string" };
+        return Number.isInteger(value)
+            ? { value, type: "integer" }
+            : { value, type: "double" };
+    }
+    if (typeof value === "bigint") {
+        const n = Number(value);
+        return Number.isSafeInteger(n)
+            ? { value: n, type: "integer" }
+            : { value: value.toString(), type: "string" };
+    }
+    const text = value instanceof String
+        ? String(value)
+        : ((0, utils_js_1.safely)(() => JSON.stringify((0, utils_js_1.normalize)(value, 4, 1024, 100))) ??
+            (0, utils_js_1.safeString)(value));
+    return { value: cutBytes(text, exports.MAX_ATTRIBUTE_BYTES), type: "string" };
+}
+/** UTF-8 bytes of one UTF-16 unit at i, and how many units it takes. */
+function utf8At(s, i) {
+    const c = s.charCodeAt(i);
+    if (c < 0x80)
+        return [1, 1];
+    if (c < 0x800)
+        return [2, 1];
+    if (c >= 0xd800 &&
+        c <= 0xdbff &&
+        i + 1 < s.length &&
+        (s.charCodeAt(i + 1) & 0xfc00) === 0xdc00)
+        return [4, 2];
+    // A lone surrogate is written as U+FFFD, three bytes.
+    return [3, 1];
+}
+/** A string's length in UTF-8 bytes. */
+function utf8Length(s) {
+    let n = 0;
+    for (let i = 0; i < s.length;) {
+        const [bytes, units] = utf8At(s, i);
+        n += bytes;
+        i += units;
+    }
+    return n;
+}
+/**
+ * A string cut to at most `max` UTF-8 bytes, the cut marked "...", as
+ * intake's cut writes it (intake/normalize.ts), never inside a character.
+ */
+function cutBytes(s, max) {
+    if (s.length * 3 <= max || utf8Length(s) <= max)
+        return s;
+    let n = 0;
+    let i = 0;
+    while (i < s.length) {
+        const [bytes, units] = utf8At(s, i);
+        if (n + bytes > max - 3)
+            break;
+        n += bytes;
+        i += units;
+    }
+    // As intake: a lone high surrogate does not end a cut.
+    if (i > 0 && /[\ud800-\udbff]/.test(s[i - 1]))
+        i--;
+    return `${s.slice(0, i)}...`;
+}
+/**
+ * A body past 64 KiB is cut there, with its size in bytes as
+ * statoss.truncated, as intake cuts it and records it: one huge line must
+ * not take the batch it is sent in down with it.
+ */
+function cutBody(body, attributes) {
+    if (body.length * 3 <= exports.MAX_BODY_BYTES)
+        return body;
+    const size = utf8Length(body);
+    if (size <= exports.MAX_BODY_BYTES)
+        return body;
+    attributes[exports.TRUNCATED] = { value: size, type: "integer" };
+    return cutBytes(body, exports.MAX_BODY_BYTES);
+}
+/** The message, or a value in it, as text: objects as JSON. */
+function bodyOf(message) {
+    if (typeof message === "string")
+        return message;
+    if (isLogMessage(message))
+        return message.text;
+    if (message instanceof String)
+        return String(message);
+    if ((0, utils_js_1.isObject)(message) && !(message instanceof Error)) {
+        const json = (0, utils_js_1.safely)(() => JSON.stringify((0, utils_js_1.normalize)(message, 4)));
+        if (json !== undefined)
+            return json;
+    }
+    return (0, utils_js_1.safeString)(message);
+}
+/**
+ * The level a line is logged at. One of the six (or a Sentry level) is
+ * itself; an app's own level is its range's, with its severity and its
+ * name for statoss.level; a name nobody declared ranks as error, as an
+ * event's does. Anything else is logged as info.
+ */
+function chooseLogLevel(level, own, logger) {
+    if (isLogLevel(level))
+        return { level, severity: exports.LOG_SEVERITY[level] };
+    if ((0, levels_js_1.isSentryLevel)(level)) {
+        const as = logLevelOf(level) ?? "error";
+        return { level: as, severity: exports.LOG_SEVERITY[as] };
+    }
+    if ((0, levels_js_1.isLevelName)(level)) {
+        const found = own[level];
+        if (found)
+            return { ...found, custom: level };
+        logger.warn(`Level "${level}" is not in the schema or \`levels\`, so the line is logged as error.`);
+        return { level: "error", severity: exports.LOG_SEVERITY.error, custom: level };
+    }
+    logger.warn(`Logged "${(0, utils_js_1.safeString)(level)}" as info: use trace, debug, info, warn, error, fatal or a level name (${levels_js_1.LEVEL_RULE}).`);
+    return { level: "info", severity: exports.LOG_SEVERITY.info };
+}
+/** The ranges of init's `levels`: a Sentry level each. */
+function ownLevelsFromSentry(levels) {
+    const out = {};
+    for (const [name, sentAs] of Object.entries(levels)) {
+        const level = logLevelOf(sentAs) ?? "error";
+        out[name] = { level, severity: exports.LOG_SEVERITY[level] };
+    }
+    return out;
+}
+/** A logger that hands each line to `capture`. */
+function makeAppLogger(capture) {
+    const at = (level) => (message, attributes) => capture(level, message, attributes);
+    return Object.freeze({
+        trace: at("trace"),
+        debug: at("debug"),
+        info: at("info"),
+        warn: at("warn"),
+        error: at("error"),
+        fatal: at("fatal"),
+        log: (level, message, attributes) => capture(level, message, attributes),
+        fmt,
+    });
+}

package/dist/cjs/schema.d.ts

@@ -1,4 +1,5 @@
 import type { Logger } from "./logger.js";
+import { type AppLogger, type OwnLogLevel } from "./logs.js";
 import type { CaptureContext, Event, Level, SentryLevel } from "./types.js";
 /** The ranges a level ranks in: Sentry's five and OpenTelemetry's trace. */
 export declare const LIKES: readonly ["fatal", "error", "warning", "info", "debug", "trace"];
@@ -190,7 +191,18 @@ export interface Handle<S = SchemaSpec> {
     captureMessage(message: string, levelOrContext?: LevelOf<S> | SchemaContext<S>): string;
     /** Sends an event you built in Sentry's schema. Returns the event id. */
     captureEvent(event: Event, context?: SchemaContext<S>): string;
+    /**
+     * Log lines, sent when init has `logs: true`; `log` takes the schema's
+     * own levels.
+     */
+    logger: AppLogger<S>;
 }
+/**
+ * How a line at each level of init's `schema` is logged: at its range's
+ * level (trace stays trace), with its severity when it gives one inside
+ * that range. Names readSchema refuses are left out.
+ */
+export declare function schemaLogLevels(schema: unknown): Record<string, OwnLogLevel>;
 /**
  * The Sentry level each level of init's `schema` is sent as. Built-in
  * levels are left out; names the SDK cannot send are logged in debug mode.

package/dist/cjs/schema.js

@@ -2,8 +2,10 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.FIELD_TYPES = exports.RULE_MATCHES = exports.RULE_SUBJECTS = exports.SCHEMA_COLORS = exports.LIKES = void 0;
 exports.defineSchema = defineSchema;
+exports.schemaLogLevels = schemaLogLevels;
 exports.readSchema = readSchema;
 const levels_js_1 = require("./levels.js");
+const logs_js_1 = require("./logs.js");
 const utils_js_1 = require("./utils.js");
 // The server's own lists (src/lib/app-schema.ts, src/lib/schema-colors.ts,
 // src/db/schema.ts), kept equal by a test.
@@ -79,6 +81,44 @@ function sentAs(name, value, logger) {
         return "info";
     return "debug";
 }
+/**
+ * How a line at each level of init's `schema` is logged: at its range's
+ * level (trace stays trace), with its severity when it gives one inside
+ * that range. Names readSchema refuses are left out.
+ */
+function schemaLogLevels(schema) {
+    const out = {};
+    if (!(0, utils_js_1.isObject)(schema) || Array.isArray(schema))
+        return out;
+    const { levels } = schema;
+    if (!(0, utils_js_1.isObject)(levels) || Array.isArray(levels))
+        return out;
+    for (const [name, value] of Object.entries(levels)) {
+        if ((0, levels_js_1.isSentryLevel)(name) || !(0, levels_js_1.isLevelName)(name))
+            continue;
+        const settings = (0, utils_js_1.isObject)(value) ? value : {};
+        const like = typeof value === "string" ? value : settings.like;
+        const given = settings.severity;
+        const severity = typeof given === "number" &&
+            Number.isInteger(given) &&
+            given >= 1 &&
+            given <= 24
+            ? given
+            : undefined;
+        let level = "error";
+        if (typeof like === "string" && exports.LIKES.includes(like))
+            level = (0, logs_js_1.logLevelOf)(like) ?? "error";
+        else if (like === undefined && severity !== undefined)
+            level = (0, logs_js_1.rangeOfSeverity)(severity);
+        out[name] = {
+            level,
+            severity: severity !== undefined && (0, logs_js_1.rangeOfSeverity)(severity) === level
+                ? severity
+                : logs_js_1.LOG_SEVERITY[level],
+        };
+    }
+    return out;
+}
 /**
  * The Sentry level each level of init's `schema` is sent as. Built-in
  * levels are left out; names the SDK cannot send are logged in debug mode.

package/dist/cjs/transport.d.ts

@@ -2,6 +2,8 @@ import { type Envelope } from "./envelope.js";
 import type { Logger } from "./logger.js";
 import type { Transport } from "./types.js";
 export declare const QUEUE_LIMIT = 30;
+/** Of the queue, what log envelopes may take, so a flood of lines never pushes out an error. */
+export declare const LOG_QUEUE_LIMIT = 10;
 export declare const CONCURRENCY = 5;
 /** The default transport: fetch, called on globalThis (Workers refuse any other this). */
 export declare function fetchTransport(browserLike: boolean): Transport;
@@ -16,12 +18,15 @@ export interface SenderOptions {
 }
 /**
  * Sends envelopes in order of arrival, a few at a time, keeping at most 30
- * waiting or in flight. Whatever cannot be sent is counted for client reports.
+ * waiting or in flight, of them at most 10 of log lines. Whatever cannot
+ * be sent is counted for client reports.
  */
 export declare class Sender {
     private readonly options;
     private readonly queue;
     private active;
+    /** Log envelopes waiting or in flight. */
+    private logs;
     private limits;
     private waiters;
     private keepaliveBytes;

package/dist/cjs/transport.js

@@ -1,11 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Sender = exports.CONCURRENCY = exports.QUEUE_LIMIT = void 0;
+exports.Sender = exports.CONCURRENCY = exports.LOG_QUEUE_LIMIT = exports.QUEUE_LIMIT = void 0;
 exports.fetchTransport = fetchTransport;
 const envelope_js_1 = require("./envelope.js");
 const ratelimit_js_1 = require("./ratelimit.js");
 const utils_js_1 = require("./utils.js");
 exports.QUEUE_LIMIT = 30;
+/** Of the queue, what log envelopes may take, so a flood of lines never pushes out an error. */
+exports.LOG_QUEUE_LIMIT = 10;
 exports.CONCURRENCY = 5;
 const REQUEST_TIMEOUT_MS = 30000;
 // Browsers refuse keepalive requests past 64 KiB in flight in total.
@@ -61,13 +63,16 @@ function header(response, name) {
 }
 /**
  * Sends envelopes in order of arrival, a few at a time, keeping at most 30
- * waiting or in flight. Whatever cannot be sent is counted for client reports.
+ * waiting or in flight, of them at most 10 of log lines. Whatever cannot
+ * be sent is counted for client reports.
  */
 class Sender {
     constructor(options) {
         this.options = options;
         this.queue = [];
         this.active = 0;
+        /** Log envelopes waiting or in flight. */
+        this.logs = 0;
         this.limits = {};
         this.waiters = [];
         this.keepaliveBytes = 0;
@@ -77,11 +82,15 @@ class Sender {
         const allowed = this.withoutLimited(envelope);
         if (!allowed)
             return;
-        if (this.queue.length + this.active >= exports.QUEUE_LIMIT) {
+        const log = (0, envelope_js_1.isLogEnvelope)(allowed);
+        if (this.queue.length + this.active >= exports.QUEUE_LIMIT ||
+            (log && this.logs >= exports.LOG_QUEUE_LIMIT)) {
             this.options.logger.warn("Dropped an envelope: the send queue is full.");
             this.lose(allowed, "queue_overflow");
             return;
         }
+        if (log)
+            this.logs++;
         this.queue.push(allowed);
         this.pump();
     }
@@ -130,7 +139,7 @@ class Sender {
             if (!(0, ratelimit_js_1.isRateLimited)(this.limits, category, now))
                 return true;
             if (category !== "internal")
-                this.options.recordLoss("ratelimit_backoff", category);
+                this.options.recordLoss("ratelimit_backoff", category, (0, envelope_js_1.itemQuantity)(item));
             return false;
         });
         if (items.length < envelope[1].length) {
@@ -140,13 +149,20 @@ class Sender {
     }
     pump() {
         while (this.active < exports.CONCURRENCY && this.queue.length > 0) {
+            const waited = this.queue.shift();
+            const log = (0, envelope_js_1.isLogEnvelope)(waited);
             // A 429 may have come in while it waited.
-            const next = this.withoutLimited(this.queue.shift());
-            if (!next)
+            const next = this.withoutLimited(waited);
+            if (!next) {
+                if (log)
+                    this.logs--;
                 continue;
+            }
             this.active++;
             const done = () => {
                 this.active--;
+                if (log)
+                    this.logs--;
                 this.pump();
             };
             void this.deliver(next).then(done, done);
@@ -211,7 +227,7 @@ class Sender {
             const category = (0, envelope_js_1.itemCategory)(item);
             // A lost client report is not reported again.
             if (category !== "internal")
-                this.options.recordLoss(reason, category);
+                this.options.recordLoss(reason, category, (0, envelope_js_1.itemQuantity)(item));
         }
     }
 }

package/dist/cjs/types.d.ts

@@ -1,3 +1,4 @@
+import type { Log } from "./logs.js";
 /** The five levels Sentry knows. */
 export type SentryLevel = "fatal" | "error" | "warning" | "info" | "debug";
 /**
@@ -174,7 +175,10 @@ export interface InitOptions {
     beforeBreadcrumb?: (breadcrumb: Breadcrumb, hint?: BreadcrumbHint) => Breadcrumb | null;
     /** Defaults to 100, which is also the most kept. */
     maxBreadcrumbs?: number;
-    /** When true, browsers ask the server to record the sender's IP address. Defaults to false. */
+    /**
+     * When true, browsers ask the server to record the sender's IP address,
+     * and log lines carry the scope's user. Defaults to false.
+     */
     sendDefaultPii?: boolean;
     /** Tags on every event. */
     tags?: Record<string, Primitive>;
@@ -187,4 +191,8 @@ export interface InitOptions {
     integrations?: IntegrationToggles;
     /** Your own level names and the Sentry level each is sent as, such as { "payment-failed": "error" }. */
     levels?: Record<string, SentryLevel>;
+    /** Sends the lines of `logger`, as Sentry's enableLogs does. Defaults to false. */
+    logs?: boolean;
+    /** Change or drop (return null) a log line before it is sent. */
+    beforeSendLog?: (log: Log) => Log | null;
 }

package/dist/cjs/version.d.ts

@@ -1,3 +1,3 @@
 export declare const SDK_NAME = "statoss.javascript";
-export declare const SDK_VERSION = "0.3.0";
+export declare const SDK_VERSION = "0.4.0";
 export declare const SDK_PACKAGE = "npm:@statoss/sdk";

package/dist/cjs/version.js

@@ -3,5 +3,5 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.SDK_PACKAGE = exports.SDK_VERSION = exports.SDK_NAME = void 0;
 exports.SDK_NAME = "statoss.javascript";
 // Kept equal to package.json by a test.
-exports.SDK_VERSION = "0.3.0";
+exports.SDK_VERSION = "0.4.0";
 exports.SDK_PACKAGE = "npm:@statoss/sdk";

package/dist/esm/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. */