> 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-presentations/apex-logs.md).

# Apex Logs

Understand Apex-specific log presentations including the stack trace visualizer and supporting class information.

Apex logs in Pharos provide specialized presentations that transform stack traces and exception details into visual formats designed for rapid comprehension and troubleshooting. Rather than parsing raw text stack traces, developers can view the complete exception path with contextual code snippets and highlighted class and method information.

## Understanding Apex Log Presentations

Apex log presentations turn raw text stack traces into a visual format that emphasizes the relationships between code units and provides surrounding code context for each frame.

{% hint style="success" %}
**Visual Troubleshooting**

Instead of manually parsing text stack traces, Pharos presents the exception path visually with code context at each frame. This transforms hours of investigation into minutes of focused debugging.
{% endhint %}

When Apex code throws an exception, Salesforce generates a stack trace showing the path from the point where the error occurred back through each calling method to the original entry point. In raw form, this appears as a text list of class names, method names, and line numbers that developers must mentally reconstruct into an execution flow.

Pharos transforms this linear text into a visual presentation that emphasizes the relationships between code units and provides surrounding code context for each frame in the stack trace.

## Stack Trace Visualizer

The **Stack Trace Visualizer** is the central feature of Apex log presentation, presenting exception information in a structured, hierarchical format that makes the error path immediately clear.

### Visual Exception Path

When viewing an Apex log that contains an exception, the stack trace appears as a vertically arranged sequence of frames, each representing a point in the execution path. The visualization flows from top to bottom:

| Frame Level                | What It Shows                                    | Why It Matters                                                   |
| -------------------------- | ------------------------------------------------ | ---------------------------------------------------------------- |
| **Exception Origin** (Top) | Where the exception was actually thrown          | Immediate failure point—root location of error                   |
| **Calling Chain** (Middle) | Each method that called the next in the stack    | Shows execution flow: Method A → Method B → Method C (exception) |
| **Entry Point** (Bottom)   | Original Apex entry: trigger, API, scheduled job | Complete context about what initiated the failed transaction     |

### Class and Method Highlighting

Each frame in the stack trace visualizer prominently displays critical code identifiers:

| Element              | What's Shown                                     | Purpose                                               |
| -------------------- | ------------------------------------------------ | ----------------------------------------------------- |
| **Class Name**       | Apex class containing the method                 | Easy stack scanning to identify involved classes      |
| **Method Signature** | Full method name with return type and parameters | Disambiguates overloaded methods                      |
| **Line Number**      | Exact line within the class                      | Pinpoints where exception was thrown or call was made |

This highlighting enables developers to quickly scan a multi-frame stack trace and:

* Identify familiar classes and methods
* Recognize custom versus standard code
* Pinpoint exact locations requiring investigation

### Code Context Display

One of the most powerful aspects of the Stack Trace Visualizer is the display of **surrounding code lines** for each frame in the stack. Rather than seeing only the line number, developers see actual code.

{% hint style="info" %}
**Context is King:** The cause of an exception is often visible in the preceding lines—a variable that wasn't initialized, a null check that was missing, or a method call with invalid parameters.
{% endhint %}

**What's Displayed:**

* **Context Lines:** 3-5 lines before and after the specific line, providing full understanding of what the code is doing
* **Highlighted Execution Line:** Specific line referenced in the stack frame is visually highlighted
* **Syntax Highlighting:** Apex keywords, strings, comments color-coded for readability
* **Indentation Preservation:** Original indentation maintained so nested structures are visually apparent

**Example:** If a `NullPointerException` occurs at line 47, the visualizer shows lines 43-51 with line 47 highlighted. This reveals:

* What happened in the lines leading up to the error
* The actual statement that failed
* What would have happened next if the error hadn't occurred

### Exception Details

At the top of the stack trace visualization, the exception details are prominently displayed:

| Detail                | What's Shown                                                     | Value                                    |
| --------------------- | ---------------------------------------------------------------- | ---------------------------------------- |
| **Exception Type**    | Class of exception thrown (NullPointer, DML, Query, Limit, etc.) | Quick understanding of failure nature    |
| **Exception Message** | Detailed error text from Salesforce or application code          | Complete failure description             |
| **Cause Chain**       | Underlying exceptions if wrapped                                 | Reveals root issue vs. surface exception |

## Supporting Apex Class Information

Beyond the stack trace itself, Apex log presentations include metadata about the classes and methods involved in the execution. This context helps distinguish between custom code errors, managed package issues, and architectural problems.

| Metadata Type           | What's Included                                      | Troubleshooting Value                                   |
| ----------------------- | ---------------------------------------------------- | ------------------------------------------------------- |
| **Class Namespace**     | Managed package, unmanaged package, or custom code   | Distinguish errors in custom vs. third-party code       |
| **Class Type**          | Trigger handler, service, utility, controller, batch | Architectural context and patterns                      |
| **API Version**         | Salesforce API version class was compiled against    | Identify version mismatches causing unexpected behavior |
| **Method Visibility**   | Public, private, protected, or global                | Understand access patterns and intended call contexts   |
| **Method Parameters**   | Parameter types the method accepts                   | Identify incorrect parameter values                     |
| **Static vs. Instance** | Static method or instance method                     | Clarify execution context and object lifecycle issues   |

## Apex Exception Categories

Pharos categorizes Apex exceptions to provide quick context about the type of problem encountered:

| Category                          | Exception Types                               | What It Indicates                                           | Context Provided                                   |
| --------------------------------- | --------------------------------------------- | ----------------------------------------------------------- | -------------------------------------------------- |
| **Database Exceptions**           | DMLException, QueryException, LockedException | DML operations, SOQL queries, or database state issues      | Save failures, malformed queries, record locking   |
| **Null Reference Exceptions**     | NullPointerException                          | Code attempted to access properties/methods on null objects | Shows what was expected to have a value but didn't |
| **Limit Exceptions**              | LimitException (CPU, Heap, SOQL, DML)         | Governor limit violations                                   | Which specific limit was exceeded and by how much  |
| **Type Exceptions**               | TypeException                                 | Data types didn't match expectations                        | Incompatible type casts                            |
| **Custom Application Exceptions** | User-defined exception classes                | Business rule violations                                    | Business-meaningful error messages                 |

## Trigger Context Information

When an Apex log originates from trigger execution, additional trigger-specific information is included. This context is critical because trigger behavior varies significantly based on the event type and batch size.

| Trigger Attribute | What's Captured                                              | Why It Matters                                                                         |
| ----------------- | ------------------------------------------------------------ | -------------------------------------------------------------------------------------- |
| **Trigger Event** | Before Insert, After Update, etc.                            | Trigger behavior varies significantly by event type                                    |
| **Object Type**   | SObject associated with trigger (Account, Opportunity, etc.) | Identifies which object's data was being processed                                     |
| **Record Count**  | Number of records in the trigger batch                       | Bulk operations behave differently than single-record; identifies bulk-specific issues |
| **Trigger Order** | Which trigger in the sequence encountered the error          | Critical when multiple triggers exist on the same object                               |

## Error Location vs. Root Cause

The Stack Trace Visualizer helps distinguish between **where** an error occurred and **why** it occurred. By visualizing the complete stack, developers can trace back from the symptom to the root cause.

**Tracing the Error Path:**

* **Immediate Error Location (Top Frame):** Shows the line where the exception was thrown
  * Example: Utility method trying to process a null value
* **Call Site (Middle Frames):** Shows where that method was called from
  * Example: Null parameter was passed to the utility method
* **Origin of Bad Data (Lower Frames):** Shows where the problem originated
  * Example: Missing initialization in a service method three frames down the stack

{% hint style="warning" %}
**Symptom vs. Root Cause:** A null pointer exception in a utility method (symptom) might actually be caused by missing initialization in a service method three frames down the stack (root cause). The full stack trace reveals both.
{% endhint %}

## Async Apex Context

For asynchronous Apex execution (Queueable, Future methods, Batch jobs), the log includes async-specific information. This context is important because async code often fails due to state differences from when it was enqueued—records that existed when the job was queued might be deleted by the time it executes.

| Async Attribute     | What's Captured                                  | Troubleshooting Value                             |
| ------------------- | ------------------------------------------------ | ------------------------------------------------- |
| **Job ID**          | Unique identifier for the asynchronous job       | Track specific job execution in Salesforce        |
| **Enqueue Context** | What code enqueued or scheduled the job          | Connects async execution back to originating code |
| **Async Type**      | Queueable, Future, Batch execute(), or Scheduled | Identifies execution pattern and lifecycle        |

## Integration with Broader Log Details

While the Stack Trace Visualizer focuses on the exception path, it's embedded within the broader log detail view that provides complete transaction context:

* **Governor Limit Usage:** CPU time, SOQL queries, DML statements, heap size consumed—identifies if exception was related to approaching/exceeding limits
* **Execution Timeline:** When the exception occurred within the transaction—immediate or after significant processing
* **Related Records:** Salesforce record IDs involved—enables reproduction with the specific data that triggered the error
* **User Context:** Which user was executing—permission and sharing rule differences can cause user-specific errors

## Comparing Multiple Occurrences

When the same exception occurs multiple times (grouped into an Issue), developers can view stack traces from different occurrences side-by-side:

| Pattern                    | What It Reveals                                | Implication                                                                              |
| -------------------------- | ---------------------------------------------- | ---------------------------------------------------------------------------------------- |
| **Consistent Stack Paths** | Every occurrence has identical stack trace     | Issue is systematic and reproducible                                                     |
| **Varying Stack Paths**    | Different calling chains to same failure point | Error can be triggered from multiple code paths; may require fixes in multiple locations |
| **Code Changes**           | Different line numbers over time               | Code changes altered execution paths                                                     |

## Special Execution Contexts

Certain execution contexts—managed package code and test runs—include additional presentation details beyond the standard stack trace.

### Managed Package Exceptions

When exceptions occur within managed package code (AppExchange packages), the stack trace visualization handles this specially:

* **Namespace Identification:** Managed package classes clearly marked with namespace prefix
* **Obfuscated Code:** Code context may not be available for obfuscated package internals (indicated)
* **Support Escalation:** Visualization includes information useful for escalating to package vendor support

### Test Execution Context

For exceptions during test execution, additional test-specific information is included:

* **Test Class and Method:** Which test method was running when the exception occurred
* **Assertion Failures:** Expected vs. actual values clearly displayed for assertion failures
* **Test Data Context:** Information about test data created and used during the test run

This helps distinguish between failures in application code versus failures in test code itself.

## Downloading and Sharing

The Apex log detail page allows downloading the complete log in multiple formats for collaboration and external analysis:

| Format               | Contents                             | Use Case                               |
| -------------------- | ------------------------------------ | -------------------------------------- |
| **Formatted Text**   | Human-readable with visual structure | Sharing with colleagues, documentation |
| **Raw Debug Log**    | Original Salesforce debug log file   | Analysis in external tools             |
| **Stack Trace Only** | Just exception and stack trace       | Quick sharing with support teams       |

## Summary

Apex log presentations in Pharos center on the Stack Trace Visualizer, which transforms linear text stack traces into visual hierarchies that show the complete execution path from entry point to exception origin.

**Key Features:**

* **Visual Exception Path:** Hierarchical view showing origin → calling chain → entry point
* **Code Context Display:** 3-5 lines before/after each frame with syntax highlighting
* **Class & Method Metadata:** Namespace, visibility, parameters, API version for each code unit
* **Exception Categorization:** Database, null reference, limit, type, or custom exceptions
* **Execution Context:** Trigger events, async jobs, test runs, managed packages
* **Multi-Occurrence Comparison:** Side-by-side stack traces reveal patterns and variations
* **Export Options:** Formatted text, raw debug log, or stack trace only

**The Result:** Developers can immediately see not just where an error occurred, but the calling chain that led to it and the code context around each step in that chain. This visual approach dramatically reduces the time required to understand complex exceptions and identify the root cause of failures in Apex code.
