Logs, audit and telemetry

log gives every app structured logs with redaction built in and a tamper-evident audit log. Errors thrown with MainError carry a stable code and a fix.

logging: { audit: true, redact: [personal, sensitive, child, phi] }
telemetry:
  to: [terminal, otel]
  otel: { endpoint: https://otel.pinecart.dev:4318, headers: { authorization: secret:OTEL_TOKEN } }
  sample: 0.2
logging:
  errors:
    driver: otlp            # otlp | sentry | local
    release: auto           # the build hash, else MAINSDK_RELEASE, else the package version
    process: true           # capture uncaught errors, flush, exit 1
    browser: false          # serve POST /_mainsdk/errors for reportErrors()
    ignore: [AbortError]
    alert: { new: warning, spike: { over: 50, per: 5m, severity: critical } }

import { log, MainError } from "mainsdk";

log.info("order shipped", { orderId: order.id });
throw new MainError("MAIN-DATA-0007", { fix: "Query with db.orders.for(user)" });

import { describe, it } from "node:test";
import assert from "node:assert/strict";
import { createTestApp } from "@mainsdk/testing";
import { MainError } from "mainsdk";

describe("logging", () => {
  it("redacts personal fields and chains audit records", () => {
    const app = createTestApp({ main: "./main.yaml" });
    app.log.info("signup", { email: "a@b.co" });
    assert.equal(app.log.records.at(-1)?.attributes.email, "[redacted]");

    app.log.audit({ actor: { kind: "user", id: "u1" }, action: "plan.change", decision: "allow" });
    assert.equal(app.log.verifyAudit().ok, true);
  });

  it("turns a MainError into problem details", () => {
    const body = new MainError("MAIN-DATA-0007", "Not yours", { status: 403, fix: "Read through db.orders.for(user)" }).toProblem();
    assert.equal(body.code, "MAIN-DATA-0007");
  });
});

telemetry:
  to: terminal

Quick start

Logging works with no configuration: records print to the terminal, one line each.

import { auth, log } from "mainsdk";

export async function POST(req: Request, { params }: { params: Promise<{ id: string }> }) {
  const session = await auth.require(req);
  const { id } = await params;
  log.info("order shipped", { orderId: id, by: session.user });
  return new Response(null, { status: 204 });
}

use mainsdk::prelude::*;
let app = App::test();
app.log().info("signed in").field("plan", "pro").await;
assert_eq!(app.log().records().len(), 1);

Each record has an id, an RFC 3339 UTC time, a severity (DEBUG, INFO, WARN, ERROR), a body and attributes. Inside a request that carries a trace, attributes.trace_id holds it, and in a tenant, attributes["tenant.id"] does.

Configuration

logging:
  audit: true                               # write the hash-chained audit log (default true)
  redact: [personal, sensitive, child, phi] # labels redacted before any write

A push to the config store can only tighten these: add a label or turn audit on, never the reverse.

How long a person's log records are kept under data rights is set in privacy.retention.logs.

What gets redacted

Before a record reaches any sink:

• Attributes labelled personal or another listed label (email, phone and name by default) are replaced with [redacted].
• authorization, cookie, set-cookie, password and pan are always redacted.
• Anything resolved from a secret: reference, and known key formats such as sk_live_…, AKIA… and GitHub tokens, are masked in messages and attributes.
• An ip attribute is trimmed to its /24 (IPv4) or /48 (IPv6).

What you get

Logs and the audit log are free and local from the first run. Redaction happens in process before any record is written. problem() turns a MainError into an RFC 9457 response. Reach for log everywhere you would use console.log, and wherever a decision must be provable later.

Examples

Throw an error with a fix

MainError takes a code, a message and options. problem() serialises it as application/problem+json; any other thrown value becomes a 500 that hides its message.

import { auth, MainError, models, problem, s } from "mainsdk";

const { orders } = models({
  orders: s.object({ item: s.string(), total: s.int() }),
});

export async function GET(req: Request, { params }: { params: Promise<{ id: string }> }) {
  try {
    const session = await auth.require(req);
    const { id } = await params;
    const order = await orders.for(session.user).get(id);
    if (!order) {
      throw new MainError("MAIN-DATA-0007", "This record belongs to another owner", {
        status: 403,
        fix: "Query with db.orders.for(user)",
      });
    }
    return Response.json(order);
  } catch (err) {
    return problem(err);
  }
}

{
  "type": "https://mainsdk.dev/errors/MAIN-DATA-0007",
  "title": "This record belongs to another owner",
  "status": 403,
  "code": "MAIN-DATA-0007",
  "fix": "Query with db.orders.for(user)"
}

retryable: true appears when the error is retryable, and retryAfter sets a Retry-After header. log.error(err) writes the code and fix with the record.

Write and verify an audit record

Policy decisions are audited for you. Write your own records for business events that must be provable. An event names the actor (kind is user, agent, system or service), the action, an optional resource string and a decision (allow, deny, pending or approved).

import { auth, log } from "mainsdk";

export async function PUT(req: Request, { params }: { params: Promise<{ id: string }> }) {
  const session = await auth.require(req, { role: "admin" });
  const { id } = await params;
  log.audit({
    actor: { kind: "user", id: session.user },
    action: "refund_limit.grant",
    resource: `user:${id}`,
    decision: "allow",
  });
  return new Response(null, { status: 204 });
}

import { log } from "mainsdk";

const result = log.verifyAudit({ from: "2026-10-01T00:00:00Z" });
if (!result.ok) {
  console.error(`Audit chain broken at ${result.brokenAt}`);
  process.exit(1);
}

Each record carries the hash of the previous one, and each tenant has its own chain, so an edit, deletion or reorder makes verifyAudit return ok: false with the first broken record's id. To check records you read back from a file, use verifyChain(records).

Keep records in a file and read them with the CLI

Passing sinks replaces the terminal output. fileSink appends JSON lines, and mainsdk logs reads .mainsdk/events/*.jsonl.

import { configure, fileSink } from "mainsdk";

configure({ sinks: [fileSink(".mainsdk/events/app.jsonl")] });

npx mainsdk logs --level error
npx mainsdk logs --trace 4bf92f3577b34da6a3ce929d0e0e4736 --json
npx mainsdk logs --follow

Without --json, each line is the time, the severity and the message.

Error reporting

Every unhandled error is captured with no wiring: a request whose handler throws or answers 5xx, a job that lands in the dead-letter queue, a workflow run that fails, log.error(err) with an Error, and (by default) an uncaught exception or unhandled rejection. A MainError with a status under 500 is the caller's error and is skipped. Each capture is redacted, given a fingerprint, counted into a group and queued for export, and none of it waits on the network.

The fingerprint is the first 16 hex characters of SHA-256 over the error's code or name and its first three frames in your code (path relative to the project, function name, no line number). It stays the same across restarts, machines and line moves. With no frame in your code it uses the message with digits, long hex and UUIDs replaced by <n>.

logging:
  errors:
    driver: otlp          # otlp (through telemetry.otel) | sentry | local
    release: auto         # the build hash, else MAINSDK_RELEASE, else the package version
    process: true         # capture uncaught errors, flush for at most 2 s, exit 1
    browser: false        # serve POST /_mainsdk/errors for reportErrors()
    ignore: [AbortError]
    alert:
      new: warning        # a group new in this release; off to disable
      spike: { over: 50, per: 5m, severity: critical }

import { log } from "mainsdk";

const page = await log.errors.list({ since: "1h", limit: 20 }); // newest first, with a next cursor
const group = await log.errors.get(page.items[0]?.fingerprint ?? ""); // 404 when unknown
console.log(group.count, group.frame?.file, group.isNew);

npx mainsdk errors --since 1h --json   # the groups under mainsdk dev, newest first

A browser reporter is one opt-in call, with logging.errors.browser: true on the server:

import { reportErrors } from "mainsdk/log/client";

const stop = reportErrors({ sample: 0.5 }); // listeners for error and unhandledrejection; stop() removes them

It sends { name, message, stack, path, release } with the query and fragment removed, one report per distinct error per page load and at most 10 a minute. The server answers 404 when browser is off, 413 over 16 KB and 429 over 10 a minute per session or address (MAIN-REPORT-0004).

Newness is decided across instances through kv when the app declares a kv section; without it, each instance decides for itself. A new group logs MAIN-REPORT-0001 and raises error:<fingerprint> once; a spike logs MAIN-REPORT-0002 and raises error-spike:<fingerprint>, resolved when the window empties. The sentry driver writes Sentry's envelope itself, through the network allowlist, with no Sentry SDK; it is written from Sentry's documented shapes and is not yet verified against a live Sentry server.

Reference

Calls beyond the examples above.

Errors and checks

Every code is listed in error codes and check codes.

Swapping drivers

The terminal sink is the only built-in destination, plus fileSink and any function of your own with the Sink shape. A planned otel driver will export to Datadog, Grafana, Sentry or any OpenTelemetry backend, and a planned mainsdk driver to MainSDK Cloud; your log.* calls and audit records stay the same.

Testing

The test app keeps every record in memory, so assert on app.log.records and app.log.auditRecords.

import { describe, it } from "node:test";
import assert from "node:assert/strict";
import { createTestApp } from "@mainsdk/testing";
import { MainError } from "mainsdk";

describe("logging", () => {
  it("redacts personal fields and chains audit records", () => {
    const app = createTestApp({ main: "./main.yaml" });
    app.log.info("signup", { email: "a@b.co" });
    assert.equal(app.log.records.at(-1)?.attributes.email, "[redacted]");

    app.log.audit({ actor: { kind: "user", id: "u1" }, action: "plan.change", decision: "allow" });
    assert.equal(app.log.verifyAudit().ok, true);
  });

  it("turns a MainError into problem details", () => {
    const body = new MainError("MAIN-DATA-0007", "Not yours", { status: 403, fix: "Read through db.orders.for(user)" }).toProblem();
    assert.equal(body.code, "MAIN-DATA-0007");
  });
});

See the Testing kit.

Security and privacy

• Redaction runs in process before any write: labelled fields, secrets and known key formats.
• IP addresses are trimmed; authorization, cookie and set-cookie values never appear.
• Nothing leaves your app: no destination is built that sends logs elsewhere. When export arrives it will be opt-in, with a field contract that drops anything not listed.

FAQ

Is the audit log ever sampled? No. Every audit event is chained and kept.

Where does the audit log live in production? In memory, plus any sink you pass, such as fileSink. A database-backed or OCSF-stream sink is not decided yet.

What if an audit sink fails? The record stays in memory, an ERROR record with MAIN-LOG-0010 is written, and the call does not throw.

Next

• Error codes: every MAIN- code with its cause and fix.
• Policy decisions: decisions written to the audit log.
• Debug your app: from an error to a fix.
• Fail static: why logging never blocks a request.

Helpers for wiring and tests