The only tool you need to know what is happening and how to fix it.
Go alertingexception-trackerissue-trackinglogsmetricsmonitoringobservability-platformopen-telemetryotelsession-replaytelemetrytraces
add: docs about fingerprinting issues
dduxbedbc58ac74e
diff --git a/docs/pages/learn/alerts.mdx b/docs/pages/learn/alerts.mdxindex e0dd44ab..a79ee768 100644--- a/docs/pages/learn/alerts.mdx+++ b/docs/pages/learn/alerts.mdx@@ -145,7 +145,7 @@ Rules belong to a project and only evaluate that project's data. Frontend projec### New Issue-Fires the first time an error with a given fingerprint is seen. Errors are grouped by a normalized stack trace hash (see [Issues](/learn/issues)), so the same logical error reported many times produces a single alert. If you archive an issue and it occurs again, that first re-occurrence counts as new and fires the rule.+Fires the first time an error with a given [fingerprint](/learn/issues#fingerprinting) is seen. Errors are grouped by a normalized stack trace hash, so the same logical error reported many times produces a single alert rather than one per occurrence. If you archive an issue and it occurs again, that first re-occurrence counts as new and fires the rule.The notification includes the error type, stack trace, app version, server name, the endpoint or task it occurred on, and a deep link to the issue.@@ -157,7 +157,7 @@ The cooldown applies per error, not per rule: two different new errors arriving### Error Regression-Fires when an error whose issue was archived (resolved) occurs again. Use this to catch fixes that did not stick. The cooldown applies per error. There is no extra configuration.+Fires when an error whose issue was archived (resolved) occurs again. Regressions are detected by the same [grouping](/learn/issues#fingerprinting), so the alert means the same failure is back, not that a similar-looking one appeared. Use this to catch fixes that did not stick. The cooldown applies per error. There is no extra configuration.### Error Ratediff --git a/docs/pages/learn/issues.mdx b/docs/pages/learn/issues.mdxindex 402d5673..c9f46cab 100644--- a/docs/pages/learn/issues.mdx+++ b/docs/pages/learn/issues.mdx@@ -35,16 +35,49 @@ This linkage means:Issues captured outside of a trace context (no active request or task) are recorded as standalone issues without a trace link.-## Automatic Grouping+## Fingerprinting-Traceway groups similar exceptions into a single issue by normalizing stack traces:+Every error is assigned a **fingerprint**: a 16-character hash of its normalized stack trace. The fingerprint is the identity of an issue. All occurrences that share it fold into a single issue, the issue URL contains it (`/issues/<hash>`), and archiving, regression detection, and alerting all key on it.-- Variable values (user IDs, timestamps) are replaced with placeholders-- Memory addresses and file paths are normalized-- UUIDs, IP addresses, and numeric IDs are generalized-- A hash is generated from the normalized trace+### Why Group Errors-This means the same bug produces one issue, not thousands of duplicates with different runtime data.+Without grouping, one bug in a hot path produces thousands of raw exceptions that differ only in runtime data: another user ID, another memory address, another server. Grouping reduces that stream to one issue with an occurrence count, which keeps two things useful:++- **The issues list stays readable.** One row per root cause instead of pages of near-duplicates, so the list ranks real problems rather than repetitions of the same one.+- **Alerts stay consistent.** A [New Issue](/learn/alerts#new-issue) rule fires once per group, not once per occurrence, and [Error Regression](/learn/alerts#error-regression) can tell that a previously resolved error has genuinely returned. If grouping were unstable, every alert rule would either flood you or stay silent.++### How the Hash Is Computed++Before hashing, Traceway normalizes the stack trace so values that vary between occurrences of the same bug never affect the hash:++| Normalization | Effect |+|---------------|--------|+| Error message | Only the error type is kept (`TimeoutError`, `*net.OpError`). The message text, which often embeds user data, is dropped, including the messages on JVM `Caused by:` lines. |+| Runtime values | Hex addresses, UUIDs, IP addresses and ports, email addresses, goroutine numbers, and long numbers (epoch timestamps, numeric IDs) are replaced with placeholders. |+| File locations | Absolute paths collapse to `filename:line`, URL origins are stripped from browser frames, and `@v1.2.3` module version suffixes are removed so a dependency bump does not split a group. |+| JVM frames | Line numbers inside `(File.java:123)` are dropped, and `... 12 more` becomes `... more`. |+| Column numbers | Dropped everywhere except line 1, where they are kept: minified bundles put everything on line 1, and the column is the only thing distinguishing frames there. |+| Resolved function names | Function names produced by the [symbolicator](/symbolicator/javascript) are excluded from the hash, so uploading source maps later improves readability without reshuffling existing groups. |+| Whitespace | Runs of spaces and blank lines are collapsed. |++The normalized trace is hashed with SHA-256 and truncated to 16 characters.++### What Stays Together, What Splits++The same logical error keeps the same hash across servers, environments, app versions, and users. A new hash (and therefore a new issue and a New Issue alert) appears when the failure itself changes: a different error type, or a different code path with different frames. Line numbers are part of the hash, so a refactor that moves code within a file can legitimately re-group an error after a deploy.++### Messages++Captured messages (strings sent through `CaptureMessage`, without an exception) skip stack trace normalization and group by their exact text. Keep message text stable and put variable data in [attributes](/learn/traces), otherwise every occurrence becomes its own issue:++```go+// One issue, one alert, with the order in scope+scope.SetTag("order_id", orderID)+traceway.CaptureMessage("payment provider unreachable")++// A new issue and a new alert for every order+traceway.CaptureMessage(fmt.Sprintf("payment provider unreachable for order %d", orderID))+```## Issue Lifecyclediff --git a/website/app/product/stack-traces/page.tsx b/website/app/product/stack-traces/page.tsxindex b3ecc593..30661290 100644--- a/website/app/product/stack-traces/page.tsx+++ b/website/app/product/stack-traces/page.tsx@@ -23,9 +23,9 @@ export default function StackTracesPage() {Find and fix issues <em>before your users notice.</em></h1><p className="hero-sub">- Every exception, grouped by a 10-step normalization pipeline and- SHA-256 hash. Thousands of duplicates collapse into one issue,- paired with the session replay or screen recording that caused it.+ Every exception, normalized and hashed so thousands of duplicates+ collapse into one issue, paired with the session replay or screen+ recording that caused it.</p><div className="hero-cta-row"><Link href="https://docs.tracewayapp.com" className="btn btn-accent">@@ -49,10 +49,10 @@ export default function StackTracesPage() {Every exception, <em>grouped and ranked</em></>}- description="Full stack traces, 10-step normalization, SHA-256 grouping. Thousands of duplicates collapse into one ranked issue so you fix what matters first."+ description="Full stack traces, stable grouping. Thousands of duplicates collapse into one ranked issue so you fix what matters first."bullets={["Full stack trace capture with file:line",- "Intelligent error grouping via SHA-256 hash",+ "Intelligent error grouping via a normalized SHA-256 hash","User impact analysis across sessions","Source map resolution for minified JS",]}@@ -64,17 +64,17 @@ export default function StackTracesPage() {<section className="wrap"><FeatureRowreverse- eyebrow="Normalization"+ eyebrow="Fingerprinting"title={<>Same bug, <em>same group</em>, every time</>}- description="Traceway normalizes stack traces before hashing, so the same logical error gets grouped together even when runtime values differ. Memory addresses, UUIDs, timestamps, numeric IDs, and ANSI codes are stripped before the hash."+ description="Traceway computes its own fingerprint for every error: the stack trace is normalized, then hashed. Memory addresses, UUIDs, IPs, numeric IDs, and dependency versions are stripped first, so runtime noise never splits a group. One root cause means one issue instead of thousands, and alerts key on the same hash, so a new-issue alert fires once per real problem and a regression alert means the same failure is genuinely back."bullets={[- "Stack trace normalization (10-step pipeline)",- "Cross-service deduplication",- "Full context preserved on every occurrence",+ "Error type kept, message text and the user data inside it dropped",+ "Resolved function names excluded, so source maps never reshuffle groups",+ "New-issue and regression alerts fire per group, not per occurrence",]}image={{ src: "/images/stack-trace.png", alt: "Error grouping interface" }}/>@@ -119,15 +119,19 @@ export default function StackTracesPage() {items={[{q: "How does error grouping work?",- a: "Traceway applies a 10-step normalization pipeline to every stack trace: extracting the error type, removing absolute file paths, replacing hex addresses, UUIDs, IPs, timestamps, and numeric IDs with placeholders, normalizing whitespace, and stripping ANSI codes. The result is hashed with SHA-256 so identical logical errors always group together, even if runtime values differ.",+ a: "Every stack trace runs through a normalization pipeline before hashing: the error type is kept while the message text is dropped, absolute paths collapse to file and line, and memory addresses, UUIDs, IPs, emails, numeric IDs, and dependency versions are replaced with placeholders. The result is hashed with SHA-256 into a 16-character fingerprint, so identical logical errors always land in the same issue even when runtime values differ.",+ },+ {+ q: "Why does grouping matter for alerts?",+ a: "Alert rules key on the group. A new-issue rule fires the first time a group is seen, not on every occurrence, and a regression rule fires only when an error you already resolved comes back. Stable grouping is what keeps alerts quiet during a flood of duplicates and loud the moment something genuinely new breaks.",},{q: "How does automatic issue ranking work?",a: "Traceway scores each issue based on how often it occurs, how recently it appeared, and how many users are affected. Issues are continuously re-ranked as new data comes in, so regressions and trending problems surface immediately, with no manual triage required.",},{- q: "How does error grouping handle different environments?",- a: "Traceway normalizes stack traces by removing runtime-specific values like memory addresses, file paths, UUIDs, and timestamps before hashing. This means the same bug produces the same group regardless of which server or environment it occurred on.",+ q: "How does grouping handle different environments?",+ a: "The normalization strips everything environment-specific: absolute file paths, server addresses, hostnames in URLs, and dependency version suffixes. The same bug produces the same group whether it fired on one server or fifty, in staging or in production.",},{q: "Can I track frontend and mobile errors alongside the backend?",