:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
use std::borrow::Cow;
use std::sync::OnceLock;
use crate::frames::Frame;
use crate::types::{Exception, ExceptionList, Stacktrace};
use regex::Regex;
use serde::{Deserialize, Serialize};
use sha2::{Digest, Sha512};
use uuid::Uuid;
// We put a vec of these on the event as a record of what actually went into a fingerprint.
// This data is user-facing/used in the frontend, so make changes with caution
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "snake_case", tag = "type")]
pub enum FingerprintRecordPart {
Frame {
raw_id: String,
pieces: Vec<String>,
},
Exception {
id: Option<String>,
pieces: Vec<String>,
},
Custom {
rule_id: Uuid,
},
Manual,
}
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Fingerprint {
pub value: String,
pub record: Vec<FingerprintRecordPart>,
}
#[derive(Debug, Clone, Default)]
pub struct FingerprintBuilder {
pub record: Vec<FingerprintRecordPart>,
pub hasher: Sha512,
}
impl FingerprintBuilder {
pub fn update(&mut self, data: impl AsRef<[u8]>) {
self.hasher.update(data);
}
pub fn add_part(&mut self, part: impl Into<FingerprintRecordPart>) {
self.record.push(part.into());
}
pub fn finalize(self) -> Fingerprint {
let result = self.hasher.finalize();
let content = format!("{result:x}");
Fingerprint {
value: content,
record: self.record,
}
}
}
impl Fingerprint {
pub fn from_exception_list(exception_list: &ExceptionList) -> Fingerprint {
FingerprintVersion::V1
.strategy()
.from_exception_list(exception_list)
}
}
// Versions of the automatic fingerprint algorithm. The grouping stage computes every
// registered version for each event, keeps the newest version already used by an existing issue,
// and falls back to the newest version for new issues. Adding a version = one variant + one arm
// in `strategy()` + appending to `all()`.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum FingerprintVersion {
// Legacy-order twins of V1/V2: the same strategies computed over the pre-flip wire order
// of SDKs whose ordering the pipeline normalizes (see `normalization::legacy_wire_order`).
// They exist so issues keyed before wire-order normalization stay addressable; being
// non-newest, they can never create issues — they only match existing ones. Delete them
// once legacy-keyed traffic decays (watch `$exception_fingerprint_version`).
V1Legacy,
V2Legacy,
// The historical algorithm — bit-for-bit (guarded by tests/fingerprint_golden.rs).
V1,
// Normalizing strategy: hashes all frames of every chain entry, drops unresolved
// line/column, and normalizes volatile path and message tokens. Selected by an offline
// research loop: pairwise F1 0.40 vs 0.26 for V1 on a held-out LLM-labeled pair dataset.
V2,
}
impl FingerprintVersion {
// All registered versions, ascending. Order is meaningful: selection keeps the newest
// already-used fingerprint, and new issues are created under the last (newest) entry.
pub fn all() -> &'static [FingerprintVersion] {
// Each legacy twin sits immediately below its canonical version, so the
// newest-first selection walk prefers V2, then V2's legacy order, then
// V1, then V1's — an event matching both a V2-era legacy row and an
// older V1 row stays on the newer issue. The last entry (the new-issue
// fallback) must never be a legacy version.
&[
FingerprintVersion::V1Legacy,
FingerprintVersion::V1,
FingerprintVersion::V2Legacy,
FingerprintVersion::V2,
]
}
pub fn as_str(&self) -> &'static str {
match self {
FingerprintVersion::V1Legacy => "v1_legacy",
FingerprintVersion::V2Legacy => "v2_legacy",
FingerprintVersion::V1 => "v1",
FingerprintVersion::V2 => "v2",
}
}
// Legacy versions hash the reconstructed pre-flip order instead of the canonical list;
// the grouping stage supplies the right list per version.
pub fn is_legacy(&self) -> bool {
matches!(
self,
FingerprintVersion::V1Legacy | FingerprintVersion::V2Legacy
)
}
pub fn compute(&self, exception_list: &ExceptionList) -> Fingerprint {
self.strategy().from_exception_list(exception_list)
}
pub fn compute_for_lib(
&self,
exception_list: &ExceptionList,
lib: Option<&str>,
) -> Fingerprint {
if *self != Self::V2
|| lib != Some("posthog-elixir")
|| !exception_list.iter().any(|exception| {
exception.exception_type.contains("#PID<")
|| exception
.exception_type
.contains("dropped from queue after ")
})
{
return self.compute(exception_list);
}
self.strategy()
.fingerprint_with_type_normalization(exception_list, true)
}
pub fn strategy(&self) -> FingerprintStrategy {
match self {
FingerprintVersion::V1 | FingerprintVersion::V1Legacy => FingerprintStrategy::default(),
FingerprintVersion::V2 | FingerprintVersion::V2Legacy => FingerprintStrategy {
frame_selection: FrameSelection::AllFrames,
// `Last` scores better offline (holdout F1 0.55 vs 0.40) but SDKs disagree on
// chain order — current SDKs put the root cause last, the legacy python SDK put
// it first — so keying on one end regroups differently per SDK version. Stays
// `All` until ordering is normalized across SDKs.
chain_selection: ChainSelection::All,
unresolved_include_line: false,
unresolved_include_column: false,
normalize: Normalization {
strip_query_strings: true,
strip_hashed_chunks: true,
basename_only: true,
},
message_normalize: MessageNormalization {
mask_quoted: true,
mask_hex_ids: true,
mask_numbers: true,
truncate: Some(200),
},
},
}
}
}
// Which frames of a resolved stack feed the fingerprint.
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub enum FrameSelection {
// V1 behavior: in-app frames, restricted to resolved ones when any frame resolved; when no
// frame is in-app, only the first frame.
#[default]
InAppResolvedElseAll,
// Every frame — stable when the in_app flag flips between captures of the same stack.
AllFrames,
}
// Which exceptions of a chained list feed the hash. Wrapper exceptions (retry shims, error
// boundaries) vary while the underlying exception is stable; `Last` keys on the final chain
// entry only. (SDKs disagree on chain order — python sends root-cause-first, most others
// outermost-first — so `Last` means "root cause" for JS-style chains and "outermost wrapper"
// for python; both empirically group better than hashing the whole chain.)
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub enum ChainSelection {
#[default]
All,
Last,
}
// String normalization applied to frame source/module before hashing: removes bytes that vary
// per deploy/device/build but not per bug. The all-off default (V1) is a byte-identity.
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct Normalization {
// "app.js?v=abc123" -> "app.js"
pub strip_query_strings: bool,
// "chunk-PGUQKT6S.js" -> "chunk-*.js" — masks content-hashed build artifact names
pub strip_hashed_chunks: bool,
// "/var/mobile/.../<device-uuid>/bundle.js" -> "bundle.js"
pub basename_only: bool,
}
static HASHED_CHUNK_TOKEN: OnceLock<Regex> = OnceLock::new();
static ELIXIR_PID: OnceLock<Regex> = OnceLock::new();
static ELIXIR_QUEUE_WAIT: OnceLock<Regex> = OnceLock::new();
impl Normalization {
fn is_noop(&self) -> bool {
!(self.strip_query_strings || self.strip_hashed_chunks || self.basename_only)
}
fn apply_source<'a>(&self, value: &'a str) -> Cow<'a, str> {
if self.is_noop() {
return Cow::Borrowed(value);
}
let mut out = value.to_string();
if self.strip_query_strings {
if let Some(idx) = out.find('?') {
out.truncate(idx);
}
}
if self.basename_only {
if let Some(idx) = out.rfind(['/', '\\']) {
out.drain(..=idx);
}
}
if self.strip_hashed_chunks {
// Build hashes are long alphanumeric runs. Most bundler hash alphabets include
// digits, but esbuild's can land on an all-letter token (chunk-SURMLCAQ.js), so a
// digit-only test misses those and mints a fresh fingerprint every time the hash
// happens to roll all-letter. All-uppercase is the second signal: real identifiers
// that end up in a path (words, camelCase names) are essentially never all-uppercase,
// so treat "has a digit" OR "every letter is uppercase" as a build hash. (The regex
// crate has no lookahead, so both checks live in the replacer.)
let re = HASHED_CHUNK_TOKEN
.get_or_init(|| Regex::new(r"[A-Za-z0-9]{8,}").expect("valid regex"));
out = re
.replace_all(&out, |caps: ®ex::Captures| {
let token = &caps[0];
let looks_like_hash = token.chars().any(|c| c.is_ascii_digit())
|| token.chars().all(|c| c.is_ascii_uppercase());
if looks_like_hash {
"*".to_string()
} else {
token.to_string()
}
})
.into_owned();
}
Cow::Owned(out)
}
fn apply_module<'a>(&self, value: &'a str) -> Cow<'a, str> {
// Module names are logical identifiers, not build artifact paths. Keep dotted package
// context and avoid chunk-hash masking so names like `sqlalchemy2.orm` don't collapse
// into `*.orm`.
if self.is_noop() || !self.strip_query_strings {
return Cow::Borrowed(value);
}
let Some(idx) = value.find('?') else {
return Cow::Borrowed(value);
};
Cow::Owned(value[..idx].to_string())
}
}
// Masks dynamic tokens in the exception message before hashing, so interpolated values
// (ids, counts, durations) don't fork issues. The all-off default (V1) is a byte-identity.
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct MessageNormalization {
// '...' and "..." contents -> '*' (user input, entity names)
pub mask_quoted: bool,
// 0x…, UUIDs, and bare hex runs >= 16 chars -> '*' (addresses, ids, hashes)
pub mask_hex_ids: bool,
// digit runs (incl. decimals) -> '#' (counts, ports, durations, errnos)
pub mask_numbers: bool,
// keep only the first N chars (huge payloads embedded in messages)
pub truncate: Option<usize>,
}
static QUOTED_TOKEN: OnceLock<Regex> = OnceLock::new();
static HEX_ID_TOKEN: OnceLock<Regex> = OnceLock::new();
static NUMBER_TOKEN: OnceLock<Regex> = OnceLock::new();
impl MessageNormalization {
fn is_noop(&self) -> bool {
!(self.mask_quoted || self.mask_hex_ids || self.mask_numbers) && self.truncate.is_none()
}
fn apply<'a>(&self, value: &'a str) -> Cow<'a, str> {
if self.is_noop() {
return Cow::Borrowed(value);
}
let mut out = value.to_string();
if self.mask_quoted {
let re =
QUOTED_TOKEN.get_or_init(|| Regex::new(r#"'[^']*'|"[^"]*""#).expect("valid regex"));
out = re.replace_all(&out, "'*'").into_owned();
}
if self.mask_hex_ids {
// UUIDs before bare numbers: they contain both hyphens and digits.
let re = HEX_ID_TOKEN.get_or_init(|| {
Regex::new(
r"0x[0-9a-fA-F]+|[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}|[0-9a-fA-F]{16,}",
)
.expect("valid regex")
});
out = re.replace_all(&out, "*").into_owned();
}
if self.mask_numbers {
let re = NUMBER_TOKEN.get_or_init(|| Regex::new(r"\d+(\.\d+)?").expect("valid regex"));
out = re.replace_all(&out, "#").into_owned();
}
if let Some(n) = self.truncate {
if let Some((idx, _)) = out.char_indices().nth(n) {
out.truncate(idx);
}
}
Cow::Owned(out)
}
}
// A parameterized automatic fingerprint algorithm. `FingerprintStrategy::default()` IS the V1
// production algorithm — every knob's default reproduces the historical behavior bit-for-bit
// (guarded by tests/fingerprint_golden.rs). Named versions live in `FingerprintVersion`.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct FingerprintStrategy {
pub frame_selection: FrameSelection,
pub chain_selection: ChainSelection,
// Unresolved frames hash line/column in V1 (no symbol to key on); library-version and
// inline-script line drift forks issues, so V2 drops the positional pieces.
pub unresolved_include_line: bool,
pub unresolved_include_column: bool,
pub normalize: Normalization,
pub message_normalize: MessageNormalization,
}
impl Default for FingerprintStrategy {
fn default() -> Self {
Self {
frame_selection: FrameSelection::default(),
chain_selection: ChainSelection::default(),
unresolved_include_line: true,
unresolved_include_column: true,
normalize: Normalization::default(),
message_normalize: MessageNormalization::default(),
}
}
}
impl FingerprintStrategy {
pub fn from_exception_list(&self, exception_list: &ExceptionList) -> Fingerprint {
self.fingerprint_with_type_normalization(exception_list, false)
}
fn fingerprint_with_type_normalization(
&self,
exception_list: &ExceptionList,
normalize_elixir_type: bool,
) -> Fingerprint {
let mut fingerprint = FingerprintBuilder::default();
let selected: Vec<&Exception> = match self.chain_selection {
ChainSelection::All => exception_list.iter().collect(),
ChainSelection::Last => exception_list.iter().last().into_iter().collect(),
};
let normalizers = normalize_elixir_type.then(|| {
(
ELIXIR_PID.get_or_init(|| {
Regex::new(r"#PID<\d+\.\d+\.\d+>").expect("valid Elixir PID regex")
}),
ELIXIR_QUEUE_WAIT.get_or_init(|| {
Regex::new(r"dropped from queue after \d+ms")
.expect("valid Elixir queue wait regex")
}),
)
});
for exc in selected {
let normalized_type = normalizers
.filter(|_| {
exc.exception_type.contains("#PID<")
|| exc.exception_type.contains("dropped from queue after ")
})
.map(|(pid, queue_wait)| {
let without_pid = pid.replace_all(&exc.exception_type, "#PID<*>");
queue_wait
.replace_all(&without_pid, "dropped from queue after *ms")
.into_owned()
});
self.include_exception(
exc,
normalized_type.as_deref().unwrap_or(&exc.exception_type),
&mut fingerprint,
);
}
fingerprint.finalize()
}
fn include_exception(
&self,
exc: &Exception,
exception_type: &str,
fp: &mut FingerprintBuilder,
) {
self.update_exception(exc, exception_type, fp);
let Some(Stacktrace::Resolved { frames }) = &exc.stack else {
return;
};
for frame in self.select_frames(frames) {
self.update_frame(frame, fp)
}
}
fn update_exception(&self, exc: &Exception, exception_type: &str, fp: &mut FingerprintBuilder) {
let mut pieces = vec![];
fp.update(exception_type.as_bytes());
pieces.push("Exception Type".to_string());
if !matches!(exc.stack, Some(Stacktrace::Resolved { frames: _ })) {
fp.update(
self.message_normalize
.apply(&exc.exception_message)
.as_bytes(),
);
pieces.push("Exception Message".to_string());
};
fp.add_part(FingerprintRecordPart::Exception {
id: exc.exception_id.clone(),
pieces,
});
}
fn select_frames<'a>(&self, frames: &'a [Frame]) -> Vec<&'a Frame> {
match self.frame_selection {
FrameSelection::AllFrames => frames.iter().collect(),
FrameSelection::InAppResolvedElseAll => {
let has_no_resolved = !frames.iter().any(|f| f.resolved);
let has_no_in_app = !frames.iter().any(|f| f.in_app);
if has_no_in_app {
// TODO: we should try to be smarter about handling the case when
// there are no in-app frames
return frames.first().into_iter().collect();
}
frames
.iter()
.filter(|f| (has_no_resolved || f.resolved) && f.in_app)
.collect()
}
}
}
fn update_frame(&self, frame: &Frame, fp: &mut FingerprintBuilder) {
let get_part = |s: &common_types::error_tracking::FrameId, p: Vec<&str>| {
FingerprintRecordPart::Frame {
raw_id: s.to_string(),
pieces: p.into_iter().map(String::from).collect(),
}
};
let mut included_pieces = Vec::new();
// Include source and module in the fingerprint either way
if let Some(source) = &frame.source {
fp.update(self.normalize.apply_source(source).as_bytes());
included_pieces.push("Source file name");
}
if let Some(module) = &frame.module {
fp.update(self.normalize.apply_module(module).as_bytes());
included_pieces.push("Module name");
}
// If we've resolved this frame, include function name, and then return
if let Some(resolved) = &frame.resolved_name {
fp.update(resolved.as_bytes());
included_pieces.push("Resolved function name");
fp.add_part(get_part(&frame.frame_id, included_pieces));
return;
}
// Otherwise, get more granular
fp.update(frame.mangled_name.as_bytes());
included_pieces.push("Mangled function name");
if self.unresolved_include_line {
if let Some(line) = frame.line {
fp.update(line.to_string().as_bytes());
included_pieces.push("Line number");
}
}
if self.unresolved_include_column {
if let Some(column) = frame.column {
fp.update(column.to_string().as_bytes());
included_pieces.push("Column number");
}
}
fp.update(frame.lang.as_bytes());
included_pieces.push("Language");
fp.add_part(get_part(&frame.frame_id, included_pieces));
}
}
#[cfg(test)]
mod test {
use crate::{
frames::Frame,
types::{Exception, Stacktrace},
};
use common_types::error_tracking::FrameId;
use super::*;
fn frame(
mangled: &str,
source: Option<&str>,
resolved_name: Option<&str>,
resolved: bool,
in_app: bool,
line: Option<u32>,
) -> Frame {
Frame {
frame_id: FrameId::new(String::new(), 1, 0),
mangled_name: mangled.to_string(),
line,
column: line.map(|l| l + 1),
source: source.map(String::from),
in_app,
resolved_name: resolved_name.map(String::from),
resolved,
resolve_failure: None,
lang: "javascript".to_string(),
junk_drawer: None,
code_variables: None,
context: None,
synthetic: false,
suspicious: false,
module: None,
}
}
fn exception(exc_type: &str, message: &str, stack: Option<Stacktrace>) -> Exception {
Exception {
exception_id: None,
exception_type: exc_type.to_string(),
exception_message: message.to_string(),
mechanism: Default::default(),
module: Default::default(),
thread_id: None,
stack,
}
}
fn resolved_stack(frames: Vec<Frame>) -> Option<Stacktrace> {
Some(Stacktrace::Resolved { frames })
}
fn value(version: FingerprintVersion, exceptions: Vec<Exception>) -> String {
version
.strategy()
.from_exception_list(&exceptions.into())
.value
}
#[test]
fn v2_normalizes_volatile_elixir_types() {
let event = |exc_type: &str, function: &str| -> ExceptionList {
vec![exception(
exc_type,
"details",
resolved_stack(vec![frame(
function,
Some("worker.ex"),
Some(function),
true,
true,
None,
)]),
)]
.into()
};
let fingerprint = |version: FingerprintVersion, lib: &str, list: &ExceptionList| {
version.compute_for_lib(list, Some(lib)).value
};
let same_failure = [
(
"** (exit) worker #PID<0.1.0> called #PID<0.2.0>",
"** (exit) worker #PID<0.3.0> called #PID<0.4.0>",
),
(
"Postgrex.Protocol (#PID<0.1.0>) disconnected",
"Postgrex.Protocol (#PID<0.3.0>) disconnected",
),
(
"** (DBConnection.ConnectionError) [Example.Repo] request dropped from queue after 12ms",
"** (DBConnection.ConnectionError) [Example.Repo] request dropped from queue after 78ms",
),
(
"[message: test job failed, reason: dropped from queue after 12ms]",
"[message: test job failed, reason: dropped from queue after 78ms]",
),
];
for (first_type, second_type) in same_failure {
let first = event(first_type, "run");
let second = event(second_type, "run");
assert_eq!(
fingerprint(FingerprintVersion::V2, "posthog-elixir", &first),
fingerprint(FingerprintVersion::V2, "posthog-elixir", &second),
);
for version in [FingerprintVersion::V1, FingerprintVersion::V2Legacy] {
assert_ne!(
fingerprint(version, "posthog-elixir", &first),
fingerprint(version, "posthog-elixir", &second),
);
}
assert_ne!(
fingerprint(FingerprintVersion::V2, "posthog-python", &first),
fingerprint(FingerprintVersion::V2, "posthog-python", &second),
);
assert_eq!(first[0].exception_type, first_type);
}
let protocol = event("Postgrex.Protocol (#PID<0.1.0>) disconnected", "run");
let other_failure = event("Postgrex.Protocol (#PID<0.2.0>) failed to connect", "run");
let other_frame = event("Postgrex.Protocol (#PID<0.2.0>) disconnected", "retry");
let wait = event(
"** (DBConnection.ConnectionError) [Example.Repo] request dropped from queue after 12ms",
"run",
);
let other_pool = event(
"** (DBConnection.ConnectionError) [Other.Repo] request dropped from queue after 78ms",
"run",
);
for (first, second) in [
(&protocol, &other_failure),
(&protocol, &other_frame),
(&wait, &other_pool),
] {
assert_ne!(
fingerprint(FingerprintVersion::V2, "posthog-elixir", first),
fingerprint(FingerprintVersion::V2, "posthog-elixir", second),
);
}
let handshake = event("Postgrex.Protocol handshake exceeded 12ms", "run");
let other_handshake = event("Postgrex.Protocol handshake exceeded 78ms", "run");
assert_ne!(
fingerprint(FingerprintVersion::V2, "posthog-elixir", &handshake),
fingerprint(FingerprintVersion::V2, "posthog-elixir", &other_handshake),
);
let wrapped = |pid: &str| -> ExceptionList {
vec![
exception("Wrapper", "details", None),
event(
&format!("Postgrex.Protocol (#PID<{pid}>) disconnected"),
"run",
)[0]
.clone(),
]
.into()
};
assert_eq!(
fingerprint(FingerprintVersion::V2, "posthog-elixir", &wrapped("0.1.0")),
fingerprint(FingerprintVersion::V2, "posthog-elixir", &wrapped("0.2.0")),
);
}
// ---- V1 invariants (preserved from the original implementation) ----
#[test]
fn v1_ignores_unresolved_frames_when_some_resolved() {
let resolved = vec![
frame(
"foo",
Some("http://example.com/foo.js"),
Some("bar"),
true,
true,
Some(10),
),
frame(
"bar",
Some("http://example.com/bar.js"),
Some("baz"),
true,
true,
Some(20),
),
];
let mut with_unresolved = resolved.clone();
with_unresolved.push(frame("xyz", None, None, false, true, Some(30)));
let a = value(
FingerprintVersion::V1,
vec![exception("TypeError", "boom", resolved_stack(resolved))],
);
let b = value(
FingerprintVersion::V1,
vec![exception(
"TypeError",
"boom",
resolved_stack(with_unresolved),
)],
);
assert_eq!(a, b);
}
#[test]
fn v1_uses_unresolved_frames_when_none_resolved() {
let frames = vec![
frame(
"foo",
Some("http://example.com/foo.js"),
None,
false,
true,
Some(10),
),
frame("xyz", None, None, false, true, Some(30)),
];
let no_stack = value(
FingerprintVersion::V1,
vec![exception("TypeError", "boom", None)],
);
let with_stack = value(
FingerprintVersion::V1,
vec![exception("TypeError", "boom", resolved_stack(frames))],
);
assert_ne!(no_stack, with_stack);
}
#[test]
fn v1_ignores_non_in_app_frames() {
let app_frame = frame(
"foo",
Some("http://example.com/foo.js"),
Some("bar"),
false,
true,
Some(10),
);
let vendor_frame = frame(
"bar",
Some("http://example.com/bar.js"),
Some("baz"),
false,
false,
Some(20),
);
let a = value(
FingerprintVersion::V1,
vec![exception(
"TypeError",
"boom",
resolved_stack(vec![app_frame.clone()]),
)],
);
let b = value(
FingerprintVersion::V1,
vec![exception(
"TypeError",
"boom",
resolved_stack(vec![app_frame, vendor_frame]),
)],
);
assert_eq!(a, b);
}
// ---- V1 vs V2 direction tests: one per differing knob ----
#[test]
fn v2_hashes_every_chain_entry() {
// Chain selection is `All` until SDK chain ordering is normalized, so wrapper
// variance still splits — but masked dynamic tokens in the wrapper do not.
let chain = |wrapper_msg: &str| {
vec![
exception("WrapperError", wrapper_msg, None),
exception("RootError", "root cause", None),
]
};
assert_ne!(
value(FingerprintVersion::V2, chain("wrapped: attempt A")),
value(FingerprintVersion::V2, chain("wrapped: attempt B")),
);
assert_eq!(
value(FingerprintVersion::V2, chain("wrapped: attempt 12")),
value(FingerprintVersion::V2, chain("wrapped: attempt 47")),
);
}
#[test]
fn v2_is_stable_when_in_app_flag_flips() {
let stack = |in_app: bool| {
resolved_stack(vec![
frame("connect", Some("connection.py"), None, false, true, None),
frame("retry", Some("retry.py"), None, false, in_app, None),
])
};
assert_ne!(
value(
FingerprintVersion::V1,
vec![exception("Error", "boom", stack(true))]
),
value(
FingerprintVersion::V1,
vec![exception("Error", "boom", stack(false))]
),
);
assert_eq!(
value(
FingerprintVersion::V2,
vec![exception("Error", "boom", stack(true))]
),
value(
FingerprintVersion::V2,
vec![exception("Error", "boom", stack(false))]
),
);
}
#[test]
fn v2_ignores_unresolved_line_drift() {
let at_line = |line: u32| {
resolved_stack(vec![frame(
"connect",
Some("connection.py"),
None,
false,
true,
Some(line),
)])
};
assert_ne!(
value(
FingerprintVersion::V1,
vec![exception("Error", "boom", at_line(378))]
),
value(
FingerprintVersion::V1,
vec![exception("Error", "boom", at_line(698))]
),
);
assert_eq!(
value(
FingerprintVersion::V2,
vec![exception("Error", "boom", at_line(378))]
),
value(
FingerprintVersion::V2,
vec![exception("Error", "boom", at_line(698))]
),
);
}
#[test]
fn v2_normalizes_volatile_source_paths() {
let cases = [
(
"http://x.com/app.js?v=abc123",
"http://x.com/app.js?v=def456",
),
("chunk-PGUQKT6S.js", "chunk-Z9XW4B2Q.js"),
// esbuild's hash alphabet can roll an all-letter token with no digits at all.
("/static/chunk-SURMLCAQ.js", "/static/chunk-DJSITZHL.js"),
(
"/data/app/8CC63366-D88D/bundle.js",
"/data/app/A4CD3A3C-8BE6/bundle.js",
),
];
for (source_a, source_b) in cases {
let with_source = |source: &str| {
vec![exception(
"Error",
"boom",
resolved_stack(vec![frame(
"foo",
Some(source),
Some("foo"),
true,
true,
Some(1),
)]),
)]
};
assert_ne!(
value(FingerprintVersion::V1, with_source(source_a)),
value(FingerprintVersion::V1, with_source(source_b)),
"V1 should split {source_a} vs {source_b}"
);
assert_eq!(
value(FingerprintVersion::V2, with_source(source_a)),
value(FingerprintVersion::V2, with_source(source_b)),
"V2 should merge {source_a} vs {source_b}"
);
}
}
#[test]
fn v2_does_not_mask_dotted_module_names_as_chunks() {
let with_module = |module: &str| {
let mut frame = frame("execute", None, Some("execute"), true, true, Some(1));
frame.module = Some(module.to_string());
vec![exception("Error", "boom", resolved_stack(vec![frame]))]
};
assert_ne!(
value(FingerprintVersion::V2, with_module("sqlalchemy2.orm")),
value(FingerprintVersion::V2, with_module("customlib2.orm")),
);
}
#[test]
fn v2_masks_dynamic_message_tokens() {
let cases = [
(
"timeout after 30s (attempt 2)",
"timeout after 45.5s (attempt 7)",
),
("cannot read 'userName'", "cannot read 'accountId'"),
(
"session 8cc63366-d88d-41d6-9c39-5c0824fcc036 expired",
"session a4cd3a3c-8be6-4f3f-93af-7e94d24e78bb expired",
),
];
for (msg_a, msg_b) in cases {
assert_ne!(
value(
FingerprintVersion::V1,
vec![exception("Error", msg_a, None)]
),
value(
FingerprintVersion::V1,
vec![exception("Error", msg_b, None)]
),
"V1 should split {msg_a:?} vs {msg_b:?}"
);
assert_eq!(
value(
FingerprintVersion::V2,
vec![exception("Error", msg_a, None)]
),
value(
FingerprintVersion::V2,
vec![exception("Error", msg_b, None)]
),
"V2 should merge {msg_a:?} vs {msg_b:?}"
);
}
}
#[test]
fn versions_match_the_research_implementation() {
// Cross-validation against the offline research harness (notebooks/ research project +
// the fingerprint_sweep bin) that selected V2: both values below were produced by that
// implementation for this exact fixture. If this test breaks, the algorithm diverged
// from the evaluated one — don't update the constants without re-running the research
// evaluation.
let fixture = vec![Exception {
exception_id: None,
exception_type: "TypeError".to_string(),
exception_message: "Cannot read property 'foo' of undefined".to_string(),
mechanism: Default::default(),
module: Default::default(),
thread_id: None,
stack: resolved_stack(vec![
{
let mut first = frame(
"foo",
Some("http://example.com/alpha/foo.js"),
Some("bar"),
true,
true,
Some(10),
);
first.column = Some(5);
first
},
{
let mut second = frame(
"bar",
Some("http://example.com/bar.js"),
Some("baz"),
true,
true,
Some(20),
);
second.column = Some(15);
second.module = Some("app.module".to_string());
second
},
]),
}];
assert_eq!(
value(FingerprintVersion::V1, fixture.clone()),
"d03a8ead4f42a8a315039e016979d6ded265ca61ebe08c5114b17626dc285f133e6a62b80d8122ff6b34198223f75bc4a682968b3608f97e9b341da4a1cc3dec"
);
assert_eq!(
value(FingerprintVersion::V2, fixture),
"444724bab3c0330331620497546290eff34b8cfe5363dcf938fc92ab80baff082a3616472e02ffadcb657cd7bdb211fbd9e1dcb04f2aae33e77c5c54e4835820"
);
}
#[test]
fn normalizations_are_identity_when_disabled() {
let path = "chunk-PGUQKT6S.js?v=1";
assert!(
matches!(Normalization::default().apply_source(path), Cow::Borrowed(s) if s == path)
);
let msg = "timeout after 30s for 'user' at 0xdeadbeef";
assert!(matches!(MessageNormalization::default().apply(msg), Cow::Borrowed(s) if s == msg));
}
}