@statoss/sdk 0.3.0 → 0.5.0

package/dist/esm/logs.js

@@ -0,0 +1,219 @@
+import { isLevelName, isSentryLevel, LEVEL_RULE } from "./levels.js";
+import { isObject, normalize, safely, safeString } from "./utils.js";
+export const 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. */
+export const MAX_BODY_BYTES = 64 * 1024;
+export const MAX_ATTRIBUTE_BYTES = 8 * 1024;
+/** A cut body's size in bytes before the cut, as intake records it. */
+export const TRUNCATED = "statoss.truncated";
+/** Each level's severity number: the start of its OpenTelemetry range. */
+export const LOG_SEVERITY = {
+    trace: 1,
+    debug: 5,
+    info: 9,
+    warn: 13,
+    error: 17,
+    fatal: 21,
+};
+export function isLogLevel(value) {
+    return (typeof value === "string" &&
+        LOG_LEVELS.includes(value));
+}
+/** The level a range (a schema's `like`) or a Sentry level is logged at. */
+export function logLevelOf(range) {
+    if (range === "warning")
+        return "warn";
+    return isLogLevel(range) ? range : undefined;
+}
+/** The range a severity number falls in. */
+export 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>.
+ */
+export 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,
+    });
+}
+export function isLogMessage(value) {
+    return (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. */
+export function serializeAttribute(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value === "string")
+        return { value: cutBytes(value, MAX_ATTRIBUTE_BYTES), type: "string" };
+    if (typeof value === "boolean")
+        return { value, type: "boolean" };
+    if (typeof value === "number") {
+        if (!Number.isFinite(value))
+            return { value: 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)
+        : (safely(() => JSON.stringify(normalize(value, 4, 1024, 100))) ??
+            safeString(value));
+    return { value: cutBytes(text, 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. */
+export 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.
+ */
+export 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.
+ */
+export function cutBody(body, attributes) {
+    if (body.length * 3 <= MAX_BODY_BYTES)
+        return body;
+    const size = utf8Length(body);
+    if (size <= MAX_BODY_BYTES)
+        return body;
+    attributes[TRUNCATED] = { value: size, type: "integer" };
+    return cutBytes(body, MAX_BODY_BYTES);
+}
+/** The message, or a value in it, as text: objects as JSON. */
+export function bodyOf(message) {
+    if (typeof message === "string")
+        return message;
+    if (isLogMessage(message))
+        return message.text;
+    if (message instanceof String)
+        return String(message);
+    if (isObject(message) && !(message instanceof Error)) {
+        const json = safely(() => JSON.stringify(normalize(message, 4)));
+        if (json !== undefined)
+            return json;
+    }
+    return 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.
+ */
+export function chooseLogLevel(level, own, logger) {
+    if (isLogLevel(level))
+        return { level, severity: LOG_SEVERITY[level] };
+    if (isSentryLevel(level)) {
+        const as = logLevelOf(level) ?? "error";
+        return { level: as, severity: LOG_SEVERITY[as] };
+    }
+    if (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: LOG_SEVERITY.error, custom: level };
+    }
+    logger.warn(`Logged "${safeString(level)}" as info: use trace, debug, info, warn, error, fatal or a level name (${LEVEL_RULE}).`);
+    return { level: "info", severity: LOG_SEVERITY.info };
+}
+/** The ranges of init's `levels`: a Sentry level each. */
+export function ownLevelsFromSentry(levels) {
+    const out = {};
+    for (const [name, sentAs] of Object.entries(levels)) {
+        const level = logLevelOf(sentAs) ?? "error";
+        out[name] = { level, severity: LOG_SEVERITY[level] };
+    }
+    return out;
+}
+/** A logger that hands each line to `capture`. */
+export 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/esm/schema.d.ts

@@ -1,10 +1,11 @@
 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"];
 export type Like = (typeof LIKES)[number];
 /** The colours a level or a category takes, by name. */
-export declare const SCHEMA_COLORS: readonly ["crimson", "red", "orange", "amber", "yellow", "green", "aqua", "teal", "blue", "violet", "indigo", "magenta", "plum", "grey"];
+export declare const SCHEMA_COLORS: readonly ["crimson", "red", "orange", "amber", "yellow", "green", "aqua", "teal", "blue", "violet", "indigo", "magenta", "plum", "grey", "ink", "ash"];
 export type SchemaColor = (typeof SCHEMA_COLORS)[number];
 /** What a rule tests: a tag by key, the logger, or one of the event's own fields. */
 export declare const RULE_SUBJECTS: readonly ["tag", "logger", "exception", "culprit", "title", "message"];
@@ -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/esm/schema.js

@@ -1,4 +1,5 @@
 import { CATEGORY_RULE, isCategoryName, isLevelName, isSentryLevel, LEVEL_RULE, } from "./levels.js";
+import { LOG_SEVERITY, logLevelOf, rangeOfSeverity, } from "./logs.js";
 import { isObject, safeString } from "./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.
@@ -27,6 +28,8 @@ export const SCHEMA_COLORS = [
     "magenta",
     "plum",
     "grey",
+    "ink",
+    "ash",
 ];
 /** What a rule tests: a tag by key, the logger, or one of the event's own fields. */
 export const RULE_SUBJECTS = [
@@ -74,6 +77,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.
+ */
+export function schemaLogLevels(schema) {
+    const out = {};
+    if (!isObject(schema) || Array.isArray(schema))
+        return out;
+    const { levels } = schema;
+    if (!isObject(levels) || Array.isArray(levels))
+        return out;
+    for (const [name, value] of Object.entries(levels)) {
+        if (isSentryLevel(name) || !isLevelName(name))
+            continue;
+        const settings = 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" && LIKES.includes(like))
+            level = logLevelOf(like) ?? "error";
+        else if (like === undefined && severity !== undefined)
+            level = rangeOfSeverity(severity);
+        out[name] = {
+            level,
+            severity: severity !== undefined && rangeOfSeverity(severity) === level
+                ? severity
+                : 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/esm/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/esm/transport.js

@@ -1,7 +1,9 @@
-import { itemCategory, serializeEnvelope } from "./envelope.js";
+import { isLogEnvelope, itemCategory, itemQuantity, serializeEnvelope, } from "./envelope.js";
 import { isRateLimited, updateRateLimits, } from "./ratelimit.js";
 import { safely, unref } from "./utils.js";
 export const QUEUE_LIMIT = 30;
+/** Of the queue, what log envelopes may take, so a flood of lines never pushes out an error. */
+export const LOG_QUEUE_LIMIT = 10;
 export const CONCURRENCY = 5;
 const REQUEST_TIMEOUT_MS = 30000;
 // Browsers refuse keepalive requests past 64 KiB in flight in total.
@@ -57,13 +59,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.
  */
 export 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;
@@ -73,11 +78,15 @@ export class Sender {
         const allowed = this.withoutLimited(envelope);
         if (!allowed)
             return;
-        if (this.queue.length + this.active >= QUEUE_LIMIT) {
+        const log = isLogEnvelope(allowed);
+        if (this.queue.length + this.active >= QUEUE_LIMIT ||
+            (log && this.logs >= 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();
     }
@@ -126,7 +135,7 @@ export class Sender {
             if (!isRateLimited(this.limits, category, now))
                 return true;
             if (category !== "internal")
-                this.options.recordLoss("ratelimit_backoff", category);
+                this.options.recordLoss("ratelimit_backoff", category, itemQuantity(item));
             return false;
         });
         if (items.length < envelope[1].length) {
@@ -136,13 +145,20 @@ export class Sender {
     }
     pump() {
         while (this.active < CONCURRENCY && this.queue.length > 0) {
+            const waited = this.queue.shift();
+            const log = 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);
@@ -207,7 +223,7 @@ export class Sender {
             const category = itemCategory(item);
             // A lost client report is not reported again.
             if (category !== "internal")
-                this.options.recordLoss(reason, category);
+                this.options.recordLoss(reason, category, itemQuantity(item));
         }
     }
 }

package/dist/esm/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/esm/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.5.0";
 export declare const SDK_PACKAGE = "npm:@statoss/sdk";

package/dist/esm/version.js

@@ -1,4 +1,4 @@
 export const SDK_NAME = "statoss.javascript";
 // Kept equal to package.json by a test.
-export const SDK_VERSION = "0.3.0";
+export const SDK_VERSION = "0.5.0";
 export const SDK_PACKAGE = "npm:@statoss/sdk";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@statoss/sdk",
-  "version": "0.3.0",
-  "description": "Error tracking for StatOSS: browsers, Node, Bun, Deno, Cloudflare Workers and Vercel Edge. Speaks Sentry's protocol.",
+  "version": "0.5.0",
+  "description": "Error tracking and logs for StatOSS: browsers, Node, Bun, Deno, Cloudflare Workers and Vercel Edge. Speaks Sentry's protocol.",
   "license": "MIT",
   "author": "StatOSS",
   "homepage": "https://statoss.com",
@@ -14,6 +14,7 @@
     "statoss",
     "errors",
     "error-tracking",
+    "logs",
     "sentry",
     "monitoring"
   ],
@@ -38,6 +39,7 @@
   "files": [
     "dist",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "engines": {