@statoss/sdk 0.2.0 → 0.4.0

package/dist/esm/client.js

@@ -1,6 +1,6 @@
 import { addDebugImages } from "./debug-ids.js";
 import { authHeader, envelopeEndpoint, envelopeUrlWithQueryAuth, parseDsn, } from "./dsn.js";
-import { clientReportEnvelope, eventEnvelope, } from "./envelope.js";
+import { clientReportEnvelope, eventEnvelope, logEnvelope, } from "./envelope.js";
 import { addInitialFrame, eventFromUnknown } from "./event.js";
 import { getCurrentScope } from "./hub.js";
 import { installClicks, installNavigation } from "./integrations/browser.js";
@@ -10,13 +10,20 @@ import { installFetch } from "./integrations/fetch.js";
 import { installGlobalHandlers } from "./integrations/handlers.js";
 import { CATEGORY_TAG, chooseLevel, isSentryLevel, LEVEL_TAG, readCategory, readLevels, } from "./levels.js";
 import { makeLogger } from "./logger.js";
+import { bodyOf, chooseLogLevel, cutBody, isLogLevel, isLogMessage, LOG_SEVERITY, logLevelOf, ownLevelsFromSentry, serializeAttribute, } from "./logs.js";
 import { describeRuntime } from "./runtime.js";
+import { readSchema, schemaLogLevels } from "./schema.js";
 import { MAX_BREADCRUMBS } from "./scope.js";
 import { fetchTransport, Sender } from "./transport.js";
 import { isObject, isThenable, normalize, now, safely, safeString, scrubUrl, truncate, unref, uuid4, } from "./utils.js";
 import { SDK_NAME, SDK_PACKAGE, SDK_VERSION } from "./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;
@@ -51,6 +58,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 = isLogLevel(log.level)
+        ? log.level
+        : (logLevelOf(safeString(log.level)) ?? "info");
+    const n = log.severityNumber;
+    const severity = typeof n === "number" &&
+        Number.isInteger(n) &&
+        n >= LOG_SEVERITY[level] &&
+        n <= LOG_SEVERITY[level] + 3
+        ? n
+        : LOG_SEVERITY[level];
+    const attributes = {};
+    if (isObject(log.attributes)) {
+        for (const [key, value] of Object.entries(log.attributes)) {
+            const typed = serializeAttribute(value);
+            if (key !== "" && typed)
+                attributes[key] = typed;
+        }
+    }
+    const body = cutBody(bodyOf(log.message), attributes);
+    return {
+        timestamp: typeof log.timestamp === "number" && Number.isFinite(log.timestamp)
+            ? log.timestamp
+            : 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 (!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)) {
@@ -97,10 +165,20 @@ export class Client {
         this.pending = new Set();
         this.teardowns = [];
         this.closed = false;
+        this.logBuffer = [];
+        this.logChars = 0;
+        this.saidLogsOff = false;
         this.options = options;
         this.logger = makeLogger(options.debug === true);
         this.runtime = describeRuntime();
-        this.levels = readLevels(options.levels, this.logger);
+        // What `levels` says wins over the schema.
+        const given = readLevels(options.levels, this.logger);
+        this.levels = { ...readSchema(options.schema, this.logger), ...given };
+        this.logLevels = {
+            ...schemaLogLevels(options.schema),
+            ...ownLevelsFromSentry(given),
+        };
+        this.logsOn = options.logs === true;
         const rate = options.sampleRate;
         if (rate !== undefined &&
             !(typeof rate === "number" && rate >= 0 && rate <= 1)) {
@@ -179,8 +257,90 @@ export 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 = chooseLogLevel(level, this.logLevels, this.logger);
+            const attrs = {};
+            if (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", SDK_NAME);
+            add("sentry.sdk.version", 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 (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[LEVEL_TAG] = choice.custom;
+            let log = {
+                level: choice.level,
+                message: bodyOf(message),
+                attributes: attrs,
+                severityNumber: choice.severity,
+                timestamp: 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 (!isObject(log)) {
+                    this.recordLoss("before_send", "log_item");
+                    return;
+                }
+            }
+            this.logTraceId ?? (this.logTraceId = 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(() => eventFromUnknown(error, { type: "generic", handled: true }), context, scope, { originalException: error });
     }
@@ -263,6 +423,7 @@ export 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
@@ -283,18 +444,63 @@ export 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))
             safely(teardown);
+        this.sendLogs();
+    }
+    keepLog(log) {
+        const size = 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 = safely(() => setTimeout(() => {
+                this.logTimer = undefined;
+                this.sendLogs();
+            }, LOG_WAIT_MS));
+            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(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 = () => safely(() => this.sendLogs());
+        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")
-                safely(() => this.sendClientReport());
+            if (doc.visibilityState !== "hidden")
+                return;
+            safely(() => this.sendLogs());
+            safely(() => this.sendClientReport());
         };
         doc.addEventListener("visibilitychange", onChange);
         this.teardowns.push(() => doc.removeEventListener?.("visibilitychange", onChange));
@@ -326,6 +532,7 @@ export class Client {
         const tags = {
             ...scope._tags,
             ...ctx.tags,
+            ...fieldTags(ctx.fields, this.logger),
             ...base.tags,
         };
         if (choice.custom)

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

@@ -1,6 +1,7 @@
 import { dsnToString } from "./dsn.js";
 import { normalize } from "./utils.js";
 import { SDK_NAME, SDK_VERSION } from "./version.js";
+export const LOG_CONTENT_TYPE = "application/vnd.sentry.items.log+json";
 function sdkHeader() {
     return { name: SDK_NAME, version: SDK_VERSION };
 }
@@ -25,9 +26,44 @@ export function clientReportEnvelope(discarded, dsn, timestamp = Date.now() / 10
         [[{ type: "client_report" }, { timestamp, discarded_events: discarded }]],
     ];
 }
+/** Log lines in one envelope, as Sentry's logger sends them. */
+export function logEnvelope(logs, dsn) {
+    return [
+        {
+            sent_at: new Date().toISOString(),
+            dsn: dsnToString(dsn),
+            sdk: sdkHeader(),
+        },
+        [
+            [
+                {
+                    type: "log",
+                    item_count: logs.length,
+                    content_type: LOG_CONTENT_TYPE,
+                },
+                { version: 2, items: logs },
+            ],
+        ],
+    ];
+}
 /** Sentry's rate-limit category for an envelope item. */
 export 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. */
+export function itemQuantity(item) {
+    return item[0].type === "log" ? item[0].item_count : 1;
+}
+/** True for an envelope of log lines. */
+export function isLogEnvelope(envelope) {
+    return envelope[1].some((item) => item[0].type === "log");
 }
 function stringify(payload) {
     try {

package/dist/esm/index.d.ts

@@ -1,14 +1,25 @@
+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";
 export { SDK_NAME, SDK_VERSION } from "./version.js";
 export type { Breadcrumb, BreadcrumbHint, CaptureContext, DebugImage, Event, EventHint, Exception, InitOptions, IntegrationToggles, Level, Mechanism, Primitive, RequestInfo, ScopeData, SdkInfo, SentryLevel, StackFrame, Transport, TransportRequest, TransportResponse, User, } from "./types.js";
 /**
  * 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 and logger it returns take
+ * only the schema's levels, categories and fields.
  */
-export declare function init(options?: InitOptions): void;
+export declare function init<const S extends SchemaSpec & CheckSchema<S> = SchemaSpec>(options?: InitOptions & {
+    schema?: S;
+}): Handle<S>;
 /** Sends an error (or anything thrown). Returns the event id. */
 export declare function captureException(error: unknown, context?: CaptureContext): string;
 /**
@@ -18,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/esm/index.js

@@ -1,13 +1,10 @@
 import { Client } from "./client.js";
 import { captureWith, getCarrier, getCurrentScope, messageContext, } from "./hub.js";
+import { makeAppLogger } from "./logs.js";
 import { isObject, safely } from "./utils.js";
 export { withScope } from "./hub.js";
+export { defineSchema } from "./schema.js";
 export { SDK_NAME, SDK_VERSION } from "./version.js";
-/**
- * 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.
- */
 export function init(options = {}) {
     try {
         const carrier = getCarrier();
@@ -26,6 +23,7 @@ export function init(options = {}) {
             safely(() => console.error("[StatOSS] init failed:", error));
         }
     }
+    return HANDLE;
 }
 /** Sends an error (or anything thrown). Returns the event id. */
 export function captureException(error, context) {
@@ -42,6 +40,20 @@ export function captureMessage(message, levelOrContext) {
 export function captureEvent(event, context) {
     return 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.
+ */
+export const logger = makeAppLogger((level, message, attributes) => safely(() => getCarrier().client?.captureLog(level, message, attributes, 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,
+});
 /** Pass null to forget the user. */
 export function setUser(user) {
     safely(() => getCurrentScope().setUser(user));

package/dist/esm/levels.d.ts

@@ -1,10 +1,13 @@
 import type { Logger } from "./logger.js";
 import type { SentryLevel } from "./types.js";
 export declare const SENTRY_LEVELS: readonly SentryLevel[];
+export declare const LEVEL_RULE = "use 1 to 32 lowercase letters, digits, dots, dashes or underscores";
+export declare const CATEGORY_RULE = "use 1 to 64 lowercase letters, digits, dots, dashes or underscores";
 export declare const LEVEL_TAG = "statoss.level";
 export declare const CATEGORY_TAG = "statoss.category";
 export declare function isSentryLevel(value: unknown): value is SentryLevel;
-export declare function isValidName(value: unknown): value is string;
+export declare function isLevelName(value: unknown): value is string;
+export declare function isCategoryName(value: unknown): value is string;
 /** Keeps the entries of init's `levels` that are usable, logging the rest in debug mode. */
 export declare function readLevels(input: unknown, logger: Logger): Record<string, SentryLevel>;
 export interface LevelChoice {

package/dist/esm/levels.js

@@ -6,16 +6,26 @@ export const SENTRY_LEVELS = [
     "info",
     "debug",
 ];
-/** Custom level and category names: what the server accepts as tag values to filter on. */
-const NAME_RE = /^[a-z0-9._-]{1,64}$/;
+/**
+ * Names of your own: lowercase letters, digits, dots, dashes and
+ * underscores. A level is at most 32 characters, as the server keeps it; a
+ * category at most 64.
+ */
+const LEVEL_RE = /^[a-z0-9._-]{1,32}$/;
+const CATEGORY_RE = /^[a-z0-9._-]{1,64}$/;
+export const LEVEL_RULE = "use 1 to 32 lowercase letters, digits, dots, dashes or underscores";
+export const CATEGORY_RULE = "use 1 to 64 lowercase letters, digits, dots, dashes or underscores";
 export const LEVEL_TAG = "statoss.level";
 export const CATEGORY_TAG = "statoss.category";
 export function isSentryLevel(value) {
     return (typeof value === "string" &&
         SENTRY_LEVELS.includes(value));
 }
-export function isValidName(value) {
-    return typeof value === "string" && NAME_RE.test(value);
+export function isLevelName(value) {
+    return typeof value === "string" && LEVEL_RE.test(value);
+}
+export function isCategoryName(value) {
+    return typeof value === "string" && CATEGORY_RE.test(value);
 }
 /** Keeps the entries of init's `levels` that are usable, logging the rest in debug mode. */
 export function readLevels(input, logger) {
@@ -30,8 +40,8 @@ export function readLevels(input, logger) {
         if (isSentryLevel(name)) {
             logger.warn(`Ignored level "${name}" in \`levels\`: it is already a Sentry level.`);
         }
-        else if (!isValidName(name)) {
-            logger.warn(`Ignored level "${name}" in \`levels\`: use 1 to 64 lowercase letters, digits, dots, dashes or underscores.`);
+        else if (!isLevelName(name)) {
+            logger.warn(`Ignored level "${name}" in \`levels\`: ${LEVEL_RULE}.`);
         }
         else if (!isSentryLevel(level)) {
             logger.warn(`Ignored level "${name}" in \`levels\`: map it to fatal, error, warning, info or debug.`);
@@ -52,18 +62,18 @@ export function chooseLevel(candidates, levels, fallback, logger) {
             continue;
         if (isSentryLevel(candidate))
             return { level: candidate };
-        if (isValidName(candidate)) {
+        if (isLevelName(candidate)) {
             return { level: levels[candidate] ?? "error", custom: candidate };
         }
-        logger.warn(`Ignored level "${safeString(candidate)}": use a Sentry level or 1 to 64 lowercase letters, digits, dots, dashes or underscores.`);
+        logger.warn(`Ignored level "${safeString(candidate)}": use a Sentry level or 1 to 32 lowercase letters, digits, dots, dashes or underscores.`);
     }
     return { level: fallback };
 }
 export function readCategory(value, logger) {
     if (value === undefined || value === null)
         return undefined;
-    if (isValidName(value))
+    if (isCategoryName(value))
         return value;
-    logger.warn(`Ignored category "${safeString(value)}": use 1 to 64 lowercase letters, digits, dots, dashes or underscores.`);
+    logger.warn(`Ignored category "${safeString(value)}": ${CATEGORY_RULE}.`);
     return undefined;
 }