> 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/categorization.md).

# Categorization

Learn how Pharos categorizes and organizes raw log data.

Categorization is the process of determining **which technology produced the log**—Apex, Flow, Bulk API, and Pharos's other built-in categories—and organizing the log accordingly. Severity is a separate dimension carried by the log level, not by Category. This classification drives everything from how the error is displayed to what enrichment is applied to how it's aggregated into Issues.

{% hint style="info" %}
**Foundation of Structured Observability:** Categorization enables Pharos to present hundreds of different error types in ways that make sense to developers troubleshooting specific problems.
{% endhint %}

## Why Categorization Matters

Raw error data arrives in different formats depending on its source. An Apex exception email looks nothing like a Flow failure notification, which looks nothing like a Bulk API job result. Categorization brings order to this heterogeneity by identifying the error type and applying appropriate handling logic.

Once categorized, a log benefits from category-specific handling:

| Capability         | How Category Drives It                                                                                                                                                               |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Display**        | Flow logs show visual diagrams, Apex logs show stack traces, Bulk API logs show batch summaries, and logs carrying integration payloads (any category) show request/response viewers |
| **Enrichment**     | Flow logs need variable values, Apex logs need class metadata, Bulk API logs need success/failure counts                                                                             |
| **Fingerprinting** | A stacktrace-driven fingerprint extracts stable error signatures; a few producers (Bulk API, async jobs) pre-set their own keys                                                      |
| **Filtering**      | Developers can focus on specific error types: "Show me all Flow errors from the past week"                                                                                           |

## The Category Field

Every log record has a `Category` field that identifies its type. This field is populated during the parsing stage of the processing pipeline and remains **immutable** throughout the log's lifetime.

| Category            | Scope                                                                                                  | Characteristics                                                                                                                                                                                    | Common Sources                                                                                         |
| ------------------- | ------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| **Apex**            | Unhandled exceptions in Apex code, including asynchronous execution and external callout/REST failures | Stack traces with class names and line numbers; async jobs (queueables, batch, scheduled) may have sparser context; callout errors carry request/response payloads with status codes and endpoints | Triggers, classes, batch jobs, queueables, schedulables, future methods, HTTP callouts, SOAP/REST APIs |
| **Flow**            | Declarative automation failures                                                                        | Flow interview IDs and element names                                                                                                                                                               | Screen Flows, Record-Triggered Flows, Autolaunched Flows                                               |
| **Process Builder** | Declarative automation failures on legacy Process Builder processes                                    | Process instance and node identifiers                                                                                                                                                              | Process Builder processes                                                                              |
| **Bulk API**        | Bulk and batch data operation failures                                                                 | Job IDs, batch IDs, job statistics, success/failure counts                                                                                                                                         | Data Loader, Bulk API jobs, programmatic bulk operations                                               |

{% hint style="info" %}
**The Full Category List:** Pharos's built-in categories also include Email-to-Case, Web-to-Case, Web-to-Lead, Pharos Error, Mulesoft, OmniStudio, LWC, Aura, and Snapshot, covering additional log sources beyond the four highlighted above.
{% endhint %}

### Category Is Not Severity

{% hint style="warning" %}
**Category answers "what produced this log?"—not "how bad is it?"** Severity lives in the log level. The former **Error**, **Warning**, **Debug**, and **Event** categories were severities in disguise (Event was additionally technology-agnostic) and have been removed from the Category picklist as of Pharos 2.0. The *Integration* category was likewise removed earlier: external callout failures are Apex-category logs that carry an integration payload.
{% endhint %}

Historical logs keep whatever Category they were saved with, along with their icons and record types. Because the Category value set is unrestricted, legacy producers and API writers that still pass one of the removed strings continue to save without error—the value is simply no longer offered as a first-class category. To filter, route, or alert on severity, use the **Log Level** field (for example, `Log Level = "ERROR"`) rather than Category.

## How Categorization Works

Pharos employs a series of pattern-matching rules to classify errors. The categorization logic examines the raw error data—email subject lines, message body content, stack traces, and metadata—and applies a decision tree to determine the appropriate category.

### Pattern Matching Rules

| Category     | Pattern Indicators                                                                                                                                                                                                                                                                                                                 | Enrichment Triggered                                                                                                                                           |
| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Apex**     | <p>• Email subject: "Apex exception" or "Apex script unhandled exception"<br>• Stack trace with class names and line numbers<br>• Callout class in stack trace, <code>System.CalloutException</code>, HTTP status codes or endpoint URLs<br>• AsyncApexJob with stack trace, or minimal context from a queueable/scheduled job</p> | Class metadata lookup, method signature extraction, stack trace parsing (best-effort for async jobs), request/response payload preservation for callout errors |
| **Flow**     | <p>• Email subject: "Flow Unhandled Fault" or "Interview failed"<br>• Flow Interview ID in message body<br>• Failed element name or "FlowVariable" reference</p>                                                                                                                                                                   | Flow version lookup, element metadata extraction, variable value capture                                                                                       |
| **Bulk API** | • BulkApiResultEvent query source, AsyncApexJob type "BatchApex", or Data Loader references                                                                                                                                                                                                                                        | Job statistics and success/failure counts, record-level error linkage                                                                                          |

A custom email parser that cannot classify a message assigns the **Pharos Error** category.

### Category-Specific Details

The pattern matching rules above drive the categorization process automatically. Once a category is assigned, Pharos applies specialized handling:

**Apex Errors**\
Stack traces are parsed to extract class names, method signatures, and line numbers. Class metadata is queried to provide context about the code structure. For these errors the stacktrace-driven fingerprint effectively keys on exception type, class, and line, grouping identical errors across occurrences. Asynchronous Apex (queueables, batch jobs, scheduled jobs) is categorized the same way, though the available context is sometimes sparser, resulting in slightly broader aggregation.

**Flow Errors**\
Flow Interview IDs are used to retrieve the flow version, element configurations, and variable values. The failed element is identified and highlighted in the visual flow diagram. For these errors the same fingerprinting machinery effectively keys on the flow name, failed element, and error type.

**Callout and REST Errors**\
External system failures are Apex-category logs that carry an integration payload—the request and response of the failed interaction. HTTP details are preserved when available, including status codes, headers, and body content, and latency measurements help identify timeout scenarios. The payload drives presentation and enrichment, not categorization or fingerprinting, which follow the standard Apex handling.

**Bulk API Errors**\
Bulk and batch data operations (Data Loader, Bulk API jobs) are categorized as Bulk API. Job statistics (total records, successful, failed) are retrieved from `AsyncApexJob` or bulk API result objects, record-level errors are linked when available, and fingerprint keys are pre-set from the job's object, operation, and job type.

## Category-Driven Behavior

Once a log is categorized, Pharos applies category-specific logic throughout the system. The category field acts as a control switch, determining how the log is presented, enriched, and queried.

### Visual Presentation

The Pharos UI renders logs differently based on category:

* **Flow logs:** Interactive flow diagrams with failed elements highlighted
* **Apex logs:** Color-coded stack traces with code context and line numbers
* **Bulk API logs:** Batch summaries with drill-down into record-level failures
* **Logs with integration payloads (any category):** Request/response viewers with HTTP details and latency metrics

Category drives most of this presentation logic—Pharos knows to invoke the Flow debugger for Flow logs and the stack trace visualizer for Apex logs because of the assigned category. The request/response viewer is the exception: it activates whenever a log carries an integration payload, regardless of category.

### Enrichment Strategy

Different categories require different enrichment. Pharos selects the appropriate enrichment queries based on category, ensuring that each log type receives the contextual data most relevant to its troubleshooting needs:

| Category                       | Enrichment Focus                                                    |
| ------------------------------ | ------------------------------------------------------------------- |
| Apex                           | Class metadata, method signatures, governor limits at failure point |
| Flow                           | Variable values, element configurations, flow version history       |
| Bulk API                       | Job statistics and success/failure breakdowns                       |
| Logs with integration payloads | Request/response data, latency metrics, endpoint configuration      |

### Fingerprinting Logic

Fingerprinting is stacktrace-driven and category-agnostic: the fingerprint is computed from the parsed stack trace lines plus the error summary, with dynamic values (GUIDs, record Ids, digits) stripped before hashing. Callout and REST errors are fingerprinted by this standard strategy like any other Apex error. A few producers pre-set their own fingerprint keys instead:

```
Standard (stacktrace-driven): sorted stack trace lines + error summary
Bulk API (pre-set keys):      object | operation | jobType [| apiVersion [| errorCodes]]
Async jobs (pre-set keys):    className + extendedStatus + jobType
```

### Search and Filtering

Developers often want to focus on specific error types. Category-based filtering makes this straightforward:

* "Show me all Flow errors from the past week"
* "Show me integration failures affecting the ERP sync" (Category = "Apex" with Functional Area = "Integration")
* "List Bulk API errors by impacted object type"

The category field is indexed for fast queries, enabling efficient list views, reports, and dashboards filtered by error type.

## Multi-Category Scenarios

Some errors span multiple categories. For example, an Apex trigger might call a Flow, and the Flow fails. Pharos assigns a **primary category** based on where the error originated:

* If the Flow failed due to an unhandled fault → **Flow log** (even if invoked by Apex)
* If the Apex trigger threw an exception while calling the Flow → **Apex log**

The stack trace in the log details shows the execution transition, providing full context regardless of the assigned category.

{% hint style="info" %}
**Cross-Category Context:** Pharos preserves the full execution path in the log details, so you can trace errors through their entire journey even when they cross category boundaries.
{% endhint %}

## Categorization and Issue Aggregation

Categorization directly impacts Issue grouping. Logs with **different categories are never aggregated into the same Issue**, even if they have similar error messages:

* A null pointer in Apex ≠ A null variable in Flow
* A Bulk API load failure ≠ an unhandled Apex exception

This category-based separation ensures that Issues remain focused and actionable. When you open an Issue, you know immediately what type of problem it represents and can apply the appropriate debugging techniques.

One transition note on removed categories (Integration, Error, Warning, Debug, and Event): because fingerprints never included the category, retiring a category does not regroup existing Issues. A legacy producer still logging a removed category and an upgraded producer logging the same error under its technology category (for example, Apex) produce the **same fingerprint**, yet form separate Issues while their categories differ—converging into a single Issue once the legacy producer is upgraded.

## Recategorization

Categories are assigned during the parsing stage and are **immutable**. If a log is miscategorized (rare, but possible in edge cases), it cannot be reclassified after creation. However, Pharos continuously improves its categorization logic based on observed patterns, reducing miscategorization rates over time.

{% hint style="warning" %}
**Immutability Trade-off:** While category immutability ensures data integrity, it means that miscategorized logs remain in their assigned category. Pharos prioritizes categorization accuracy to minimize this edge case.
{% endhint %}

## Summary

Categorization transforms the chaos of raw error data into organized, type-specific logs. By identifying whether an error is Apex, Flow, Bulk API, or one of Pharos's other built-in categories, Pharos can apply the right presentation and enrichment logic.

**Key Takeaways:**

* **Technology, not severity:** Category identifies what produced the log; severity is carried by the log level
* **Automatic Classification:** Pattern-matching rules assign categories during parsing with no manual intervention
* **Immutable Assignment:** Categories cannot be changed after creation, ensuring data integrity
* **Behavior Driver:** Category determines visual presentation, enrichment strategy, and filtering capabilities; request/response views activate on integration payload presence, regardless of category
* **Aggregation Boundary:** Logs with different categories never merge into the same Issue
* **Foundation of Observability:** Effective categorization enables Pharos to present hundreds of error types in contextually appropriate ways

This classification happens during the parsing stage and drives nearly every aspect of how Pharos handles the log throughout its lifecycle—from UI rendering to Issue aggregation to troubleshooting workflows.
