> For the complete documentation index, see [llms.txt](https://docs.pharos.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pharos.ai/platform-overview/pharos-platform-architecture/logs/log-processing/log-fingerprinting.md).

# Log Fingerprinting

Understand the fingerprinting mechanism for different Salesforce technologies.

Fingerprinting is the process of extracting a stable, invariant signature from an error that remains consistent across occurrences. This signature enables Pharos to recognize that 500 logs are all manifestations of the same underlying problem and aggregate them into a single Issue.

## The Problem Fingerprinting Solves

{% hint style="success" %}
**The Power of Aggregation**

Fingerprinting is what transforms Pharos from a log collection system into an Issue management platform. Without it, you'd drown in thousands of individual error logs. With it, you focus on dozens of actionable problems.
{% endhint %}

Without fingerprinting, every error instance becomes a separate record requiring individual triage. A null pointer exception that affects 100 users generates 100 logs—100 things to review, prioritize, and resolve.

With fingerprinting, those 100 logs are recognized as instances of the same problem. Pharos groups them into one Issue with occurrence statistics, impact metrics, and a single resolution workflow. Instead of triaging 100 items, you triage one.

This aggregation transforms log noise into manageable problem sets. It's the difference between drowning in alerts and systematically addressing root causes.

## What Makes a Good Fingerprint

{% hint style="info" %}
**Balancing Act**

The art of fingerprinting is finding the sweet spot between too specific (fragmenting similar errors into many Issues) and too broad (lumping different errors into one confusing Issue).
{% endhint %}

A fingerprint must balance two competing goals:

**Stability:** The fingerprint should remain constant across error occurrences. If the fingerprint changes every time, logs won't aggregate properly, and Issues will fragment unnecessarily.

**Distinctiveness:** The fingerprint should differentiate between genuinely different problems. If the fingerprint is too broad, unrelated errors get lumped together, making Issues unintelligible.

Pharos fingerprinting algorithms are tuned for each Salesforce technology to achieve this balance. The same error pattern receives the same fingerprint regardless of when it occurs, which user triggers it, or what data is involved—but different error patterns receive different fingerprints.

## Fingerprint Tiers: Hash 1, 2, and 3

A fingerprint is stored on each log as a **hash** — and Pharos actually computes **three** fingerprints of decreasing precision, saved on the log as **Hash 1**, **Hash 2**, and **Hash 3** (`pharos__Hash_1__c`, `pharos__Hash_2__c`, `pharos__Hash_3__c`). Think of them as three progressively looser fingerprints of the same error: the first identifies the exact problem, the other two recognize close relatives.

| Tier       | Field               | Precision | Purpose                                                                                                                               |
| ---------- | ------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| **Hash 1** | `pharos__Hash_1__c` | Exact     | Groups identical errors — every log with the same Hash 1 rolls up into **one Issue**                                                  |
| **Hash 2** | `pharos__Hash_2__c` | Broader   | Recognizes near-identical errors (the same failure after a code refactor, or a new Flow version) — used to **relate** separate Issues |
| **Hash 3** | `pharos__Hash_3__c` | Broadest  | Loosest resemblance (currently Flow and Process Builder) — a fallback for **relating** Issues when Hash 2 doesn't match               |

**Hash 1 groups; Hash 2 and Hash 3 relate.** The exact fingerprint (Hash 1) decides whether an incoming log joins an existing Issue or starts a new one. The looser fingerprints don't group logs — they let Pharos automatically connect Issues that are variations of the same underlying problem, surfaced through the `pharos__Related_Issue__c` lookup (a Hash 2 match takes priority over a Hash 3 match).

{% hint style="info" %}
**Fingerprint and hash are the same thing.** "Fingerprint" is the concept — a stable signature of an error. "Hash" is how that signature is stored on the log (a SHA-256 value). The technology-specific sections below describe what goes *into* a fingerprint before it's hashed; those examples all describe the exact tier, **Hash 1**.
{% endhint %}

For how the broader tiers connect Issues to one another, see [Issue Relationships](https://docs.pharos.ai/platform-overview/pharos-platform-architecture/issue-tracker/issue-details/issue-relationships.md).

## Fingerprinting by Technology

Salesforce technologies expose error information differently, so the same fingerprinting machinery yields differently shaped signatures. Most logs go through the **standard stacktrace-driven strategy**—the fingerprint is computed from the parsed stack trace lines plus the error summary, whatever the log's category. A few producers pre-set their own fingerprint keys instead: **Bulk API** jobs and **async jobs**.

| Technology                              | Key Components                                                                              | Example Fingerprint                                    | Normalization Focus                                                 |
| --------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------ | ------------------------------------------------------------------- |
| **Apex**                                | Exception type, class, method, line number                                                  | `NullPointer_TriggerHandler_afterUpdate_156`           | Remove user IDs, record IDs, timestamps                             |
| **Async/Scheduled Apex**                | Pre-set keys: class name, extended status, job type                                         | `Queueable_OrderQueue_LimitException_TooManySoql`      | Broader grouping due to limited context (still categorized as Apex) |
| **Flow**                                | Flow name, version, element, error type                                                     | `LeadConversion_v5_CreateAccount_RequiredFieldMissing` | Remove variable values, record IDs                                  |
| **Callout/REST errors** (Apex category) | Standard Apex strategy: exception type, class, method, line                                 | `CalloutException_OrderSyncService_send_88`            | GUIDs, record IDs, digits stripped from the summary                 |
| **Bulk API**                            | Pre-set keys: object, operation, job type (plus API version and error codes when available) | Key structure: `object \| operation \| jobType`        | Error codes, not raw messages, participate in the keys              |
| **LWC**                                 | Component name, method, error type                                                          | `orderEntry_handleSave_TypeError_undefined`            | Focus on component/method vs. line numbers                          |
| **Aura**                                | Component name, method, error type                                                          | `orderEntryAura_handleSave_TypeError_undefined`        | Same approach as LWC—focus on component/method                      |

### Apex Fingerprinting

Apex errors are characterized by exception types, class names, method names, and line numbers. A fingerprint for an Apex error typically combines:

**Exception Type**\
The class of exception—`System.NullPointerException`, `System.DmlException`, `System.LimitException`, etc. This indicates the nature of the failure.

**Class and Method**\
Where in the code the exception occurred. A null pointer in `OpportunityTriggerHandler.afterUpdate` is different from a null pointer in `AccountService.processAccount`.

**Line Number**\
The specific line of code that threw the exception. Line 156 versus line 203 likely represents different code paths and therefore different problems.

**Example Fingerprint:**\
`NullPointerException_OpportunityTriggerHandler_afterUpdate_156`

This fingerprint would capture all occurrences of this specific null pointer exception at this location, regardless of which user triggered it or which Opportunity was involved.

**Variance Handling:**\
Pharos ignores user IDs, record IDs, and timestamps when computing Apex fingerprints. These values change with every occurrence but don't represent different problems. Similarly, dynamic portions of error messages (like "Attempt to de-reference a null object for Opportunity 006xxx") are normalized to focus on the invariant parts.

**Challenges:**\
Apex stack traces sometimes include anonymous blocks or dynamically invoked code where line numbers aren't stable. In these cases, Pharos falls back to class and method names without line numbers, accepting slightly broader aggregation to maintain grouping.

### Flow Fingerprinting

Flow errors are characterized by flow names, versions, and the specific element that failed. A fingerprint for a Flow error typically combines:

**Flow API Name**\
The internal name of the Flow. Two different Flows can have similar errors but represent distinct problems.

**Flow Version**\
Flow versioning can complicate fingerprinting. Version changes might introduce new bugs or fix old ones. Pharos can be configured to treat different Flow versions as the same Issue (grouping across versions) or separate Issues (isolating version-specific problems).

**Failed Element Name**\
The specific node in the Flow where the fault occurred—a Decision, Assignment, Record Create, Subflow, etc. Errors at different elements usually indicate different logical failures.

**Error Type**\
What kind of fault occurred—a null variable reference, a DML exception, a required input missing, etc.

**Example Fingerprint:**\
`LeadConversionFlow_v5_CreateAccountRecord_RequiredFieldMissing`

This fingerprint captures all instances where this Flow version fails at the "CreateAccountRecord" element due to a required field being missing.

**Variance Handling:**\
Similar to Apex, Pharos normalizes variable values and record IDs out of Flow fingerprints. The fact that `LeadId` was `00Q123` versus `00Q456` doesn't change the underlying problem—the fingerprint focuses on the Flow structure and error type.

**Challenges:**\
Flows can fail in different ways at the same element (missing field vs. invalid value vs. null reference). Pharos attempts to differentiate these scenarios to avoid overly broad aggregation, but sometimes ambiguous error messages make this difficult.

### Bulk API Fingerprinting

Bulk API is its own log category, and it is one of the two producers that **pre-set their fingerprint keys** rather than relying on the standard stacktrace-driven strategy. These errors occur during batch operations—Data Loader imports, integration bulk updates, and large-scale DML—and their keys are built from the job itself:

**Object**\
Which Salesforce object was being operated on—Account, Contact, Opportunity, etc. Bulk operations on different objects represent different processes.

**Operation**\
Insert, Update, Upsert, Delete. The same failure during Insert versus Update might represent different data quality issues.

**Job Type, API Version, and Error Codes**\
The job type always participates; the API version and the job's error codes are included when available.

**Fingerprint key structure:**\
`object | operation | jobType [| apiVersion [| errorCodes]]`

This groups all failures of the same bulk process—for example, every failing Account insert job of the same type—regardless of how many records are affected or when the batch ran.

**Variance Handling:**\
Error codes, not raw error messages, participate in the keys, so record-specific message content ("Duplicate value on Email: <john@example.com>") doesn't fragment grouping.

**Challenges:**\
Because the keys describe the job rather than individual record failures, one Issue can cover a batch whose records failed for several distinct data-quality reasons—drill into the linked record-level errors to see the breakdown.

### Callout and REST Error Fingerprinting

Callout and REST errors occur when Salesforce communicates with external systems via HTTP. These are **Apex-category logs**, fingerprinted by the standard stacktrace-driven strategy—the same one applied to any other Apex error. There is no separate endpoint- or status-code-based scheme: the integration payload (request/response) travels with each log as debugging context, but it is not a fingerprint input.

What the standard strategy yields for a callout failure:

**Exception Type**\
Typically `System.CalloutException`, or a parsing exception thrown while processing the response.

**Class, Method, and Line**\
The Apex code location that made or handled the callout. Distinct callout sites produce distinct fingerprints, even when they hit the same external system.

**Error Summary (Normalized)**\
The error summary participates in the hash with dynamic values—GUIDs, record IDs, digits—stripped, so request-specific content doesn't fragment grouping.

**Example Fingerprint:**\
`CalloutException_OrderSyncService_send_88`

This fingerprint groups all occurrences of the ERP order sync failing at this callout site, regardless of which orders were being synced.

**Variance Handling:**\
External system responses are notoriously inconsistent. The same failure might return slightly different error messages due to load balancers, retries, or backend service variations. Because the fingerprint keys on the calling code and a normalized summary rather than the response itself, grouping stays stable across that noise.

**Challenges:**\
Because the fingerprint identifies the callout site, the same external outage hitting several different callout sites creates several Issues—and one site failing for different external reasons can group into a single Issue. The integration payload preserved on each log carries the per-occurrence HTTP detail (endpoint, method, status code) for telling those occurrences apart.

### LWC and Client-Side Fingerprinting

Lightning Web Component errors are captured via the Triton logger when developers instrument their JavaScript code. These errors are characterized by component names, method names, and error types.

**Component Name**\
Which LWC component encountered the error—`orderEntry`, `contactSearch`, etc.

**Method or Handler**\
The JavaScript function where the error occurred—`handleSave`, `fetchData`, etc.

**Error Type**\
The JavaScript exception type—`TypeError`, `ReferenceError`, `RangeError`, etc.

**Example Fingerprint:**\
`LWC_orderEntry_handleSave_TypeError_undefinedProperty`

This fingerprint groups all instances where the `orderEntry` component's `handleSave` method encounters a `TypeError` accessing an undefined property.

**Variance Handling:**\
JavaScript errors often include stack traces with minified code references or dynamic line numbers due to bundling. Pharos focuses on component and method names rather than line numbers for LWC fingerprinting.

**Challenges:**\
Client-side errors depend heavily on instrumentation quality. If developers don't consistently use Triton logging in their LWC components, error coverage may be incomplete, leading to fragmented Issues.

Aura component errors (categorized separately as Aura, since Aura predates LWC as Salesforce's original component framework) follow the same fingerprinting approach—component name, method/handler, and error type—when instrumented via the Triton logger.

### Async and Scheduled Job Fingerprinting

Asynchronous job errors—queueables, batch jobs, scheduled Apex—are categorized as Apex, like any other Apex exception, but can be challenging to fingerprint because the error context is sometimes minimal.

**Job Type**\
Queueable, Batch, Scheduled. Different asynchronous patterns represent different execution contexts.

**Class Name**\
The Apex class being executed asynchronously.

**Error Type**\
The exception thrown, if available.

**Example Fingerprint:**\
`Async_Queueable_OrderProcessingQueue_LimitException_TooManySoql`

This fingerprint groups all instances where the `OrderProcessingQueue` queueable hits a SOQL limit exception.

**Variance Handling:**\
Async errors sometimes lack detailed stack traces because the job context is opaque. Pharos fingerprints based on the available data, which may result in broader grouping compared to synchronous Apex errors.

**Challenges:**\
Chain queueables and complex asynchronous workflows can produce errors at multiple stages. Pharos attempts to differentiate these stages, but if error messages are vague, aggregation may be imperfect.

## Fingerprint Stability and Evolution

Fingerprints are computed during log processing and stored immutably with the log. If Pharos improves its fingerprinting algorithm in a future release, existing logs retain their original fingerprints—only new logs receive updated fingerprints.

This stability ensures that historical Issues remain consistent. However, it also means that fingerprinting improvements don't retroactively fix old data. Pharos may offer migration tools for major fingerprinting changes, but generally, the principle is: once fingerprinted, always fingerprinted.

## Triton Logs

Triton has no API for setting a fingerprint. Pharos computes fingerprints for Triton logs during processing, the same way it does for every other log.

## Fingerprinting and Issue Management

Effective fingerprinting is the foundation of Issue-based observability. When fingerprints are stable and distinctive, Issues become accurate representations of problems. When fingerprints are unstable or too broad, Issues become noisy and difficult to triage.

Pharos continuously refines its fingerprinting algorithms based on observed error patterns. The goal is always the same: group related errors together, keep unrelated errors separate, and make Issues actionable for developers troubleshooting production problems.

## Summary

Fingerprinting extracts stable signatures from errors across Apex (including async/scheduled jobs and callout/REST errors), Flow, Bulk API, LWC, and Aura contexts. These signatures enable intelligent log aggregation into Issues, transforming thousands of logs into a manageable set of problems to address.

Each technology requires a tailored fingerprinting strategy because error data structures differ:

| What Pharos Fingerprints                          | What Pharos Ignores              |
| ------------------------------------------------- | -------------------------------- |
| Exception types and error codes                   | User IDs and usernames           |
| Class names and method names                      | Record IDs and field values      |
| Line numbers (when stable)                        | Timestamps and execution times   |
| Flow element names and versions                   | Variable values and runtime data |
| Bulk API job keys (object, operation, job type)   | Raw record-level error messages  |
| Async job keys (class, extended status, job type) | Per-run runtime detail           |

**The Fingerprinting Promise:**

* **Same error, same fingerprint:** Regardless of when it occurs, which user triggers it, or what data is involved
* **Different errors, different fingerprints:** Ensuring unrelated problems don't get lumped together
* **Immutable signatures:** Fingerprints remain stable for historical consistency
* **Technology-specific logic:** Each Salesforce technology gets appropriate fingerprinting

The result is a system where developers can focus on fixing problems rather than sifting through redundant logs.
