@statoss/sdk 0.3.0 → 0.5.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,14 +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 } from "./schema.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;
@@ -52,6 +58,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 = 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 = {};
@@ -124,14 +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();
         // What `levels` says wins over the schema.
-        this.levels = {
-            ...readSchema(options.schema, this.logger),
-            ...readLevels(options.levels, this.logger),
+        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)) {
@@ -210,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 });
     }
@@ -294,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
@@ -314,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));

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,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/esm/index.js

@@ -1,5 +1,6 @@
 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";
@@ -39,12 +40,19 @@ 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) {

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