Skip to content
DocspackagesDocumentation

@lunora/fingerprint

Zero-dependency error fingerprinting — one stable grouping hash that collapses noisy errors into Issues for Studio.

PackagesFingerprint

@lunora/fingerprint is Lunora's deterministic error-grouping core: it folds every occurrence of "the same" error onto one stable 16-character hash (an Issue), no matter where the error was observed. A live observability sink event and a request-log row persisted hours earlier compute the same hash, so the Studio Issues panel describes the same object.

The core algorithm is vendored from Superlog Labs' @superlog/fingerprint (Apache-2.0, see the package NOTICE), with the Node-only crypto backend replaced by a portable synchronous SHA-256. The package is zero-dependency and runs unchanged in the browser (Studio), the Cloudflare Workers (workerd) runtime, and Node.

import { fingerprintError } from "@lunora/fingerprint";

const fp = fingerprintError({
    functionPath: "messages:list",
    message: "User 12345 not found",
    code: "NOT_FOUND", // metadata only — never part of the hash
});
// → { hash: "168d714cba85f1c8", title: "User 12345 not found",
//     culprit: "messages:list", bucket: "user <n> not found", code: "NOT_FOUND" }

The hash contract

fingerprintError({ functionPath, message, code? }) hashes over exactly

sha256("lunora::" + functionPath + "::" + bucket(message))

truncated to 16 hex characters. An empty functionPath hashes as unknown. Two things follow from that:

  • functionPath + normalized message is the whole identity. That pair is the one thing every Lunora error source can supply: an in-flight observability event carries { code, message, status }, while the durable request log (__lunora_reqlog__) stores outcome, error_message and the hash in error_fingerprint, with no stored code. The hash is computed from the raw message when the row is written, so it is the same pair. Hashing anything more would split a live Issue from one recomputed from history.
  • code is display metadata, never hashed. It rides along on the result (fp.code) for badges and filtering, but changing it does not create a new Issue.

The result also carries a title (first message line, capped at 120 chars), the culprit (the function path, or container:<name> for container lifecycle errors, which flow through the same seam), and the bucket the hash was built from, which is what you inspect when two errors did or didn't group.

fingerprintError is pure and synchronous, so it is safe to call per row when grouping a request-log page client-side.

The message bucketer

Raw messages embed per-occurrence noise: a route scanner probing 5,000 paths or a per-user id in the message must not explode one bug into 5,000 Issues. messageBucketFor(message) normalizes the message before hashing by stripping/tokenizing:

  • URLs, request paths and email addresses
  • UUIDs, long ids, and hex blobs
  • IP addresses and timestamps
  • bare numbers ("User 12345 not found" → "user <n> not found")

so a sweep of GET /wp-admin/... 404s folds into a single Issue. The bucketer (and normalizeMessage, its heavier sibling) are exported for inspection and tests.

Stack-aware variants

For telemetry that arrives over the OpenTelemetry Protocol (OTLP) and carries a real exception.stacktrace, the stack-aware fingerprint / fingerprintLog exports add top-5 user-frame normalization on top of the message bucket, the vendored superlog behavior. Inside a Lunora deployment you almost always want fingerprintError: Lunora errors carry no stack frames on the wire.

Where it feeds

  • @lunora/observability calls fingerprintError when it writes an error row to the request log, and stores the hash in error_fingerprint. readErrorIssues groups by that stored hash, and computes it only for rows that lack one.
  • @lunora/do serves the getIssues admin RPC over that readout.
  • Studio renders the grouped result in the Issues panel: one row per hash, with occurrence counts, first/last seen, and the code badge.

You normally don't install this package directly; it arrives as a dependency of @lunora/observability. Reach for it yourself only to group errors in your own tooling with the same identity Lunora uses.

Other exports

ExportPurpose
sha256Hex(message)Synchronous SHA-256 of a string as lowercase hex. The grouping hash is its first 16 characters.
stripNullBytes(value)Removes NUL bytes from a string so the value can be stored in SQLite or Postgres. null and undefined pass through.
ErrorFingerprintThe result of fingerprintError: hash, title, culprit, bucket, and the optional code.
FingerprintErrorInputThe input to fingerprintError: functionPath, message, and the optional code.