Event Origin Resolution

Purpose and Scope

This document describes the event origin resolution system, which determines the source code location where Sentry events and spans are created. The system uses backtrace analysis to identify the first application-level frame (excluding vendor code) and extracts file path, function name, and line number information. This data enriches Sentry events with precise code location metadata.

For information about span creation and management utilities, see Span Management Traits.

Sources: src/Traits/ResolvesEventOrigin.php1-51

---

Overview

The event origin resolution system provides a standardized way for Sentry features to determine where in the application code an event or span was triggered. Rather than using the immediate caller location (which might be deep in framework or vendor code), the system walks the call stack to find the first "in-app" frame—code that belongs to the application rather than dependencies.

This is particularly important for performance monitoring spans created by features like RedisFeature, where the actual span creation happens in listener code, but the meaningful location is where the application code triggered the Redis operation.

Sources: src/Traits/ResolvesEventOrigin.php11-33

---

System Architecture

Sources: src/Traits/ResolvesEventOrigin.php1-51

---

The ResolvesEventOrigin Trait

The ResolvesEventOrigin trait is a mixin that provides event origin detection capabilities to any class that needs to determine where an operation was initiated in application code.

Trait Implementation

Sources: src/Traits/ResolvesEventOrigin.php9-50

Method: resolveEventOrigin()

The primary method returns origin metadata as an associative array with three standardized keys:

Key	Type	Description
code.filepath	string	Full path to the source file
code.function	string	Name of the function or method
code.lineno	int	Line number in the source file

The method performs the following operations:

1. Retrieve BacktraceHelper: Obtains the helper instance from the container src/Traits/ResolvesEventOrigin.php46-49
2. Capture Backtrace: Calls debug_backtrace() with DEBUG_BACKTRACE_IGNORE_ARGS flag and limit of 20 frames src/Traits/ResolvesEventOrigin.php17
3. Find First App Frame: Delegates to BacktraceHelper::findFirstInAppFrameForBacktrace() to identify the first non-vendor frame src/Traits/ResolvesEventOrigin.php16-18
4. Handle View Compilation: If the frame is from a compiled view, resolves the original view file path src/Traits/ResolvesEventOrigin.php24-26
5. Return Metadata: Returns the structured array or null if no app frame found src/Traits/ResolvesEventOrigin.php28-32

Sources: src/Traits/ResolvesEventOrigin.php11-33

Method: resolveEventOriginAsString()

This convenience method formats the origin data as a single string in the format filepath:lineno. It delegates to resolveEventOrigin() and performs string concatenation.

Implementation:

• Returns null if no origin can be determined src/Traits/ResolvesEventOrigin.php39-41
• Formats as {filepath}:{lineno} for non-null origins src/Traits/ResolvesEventOrigin.php43
• Omits the function name from the string representation src/Traits/ResolvesEventOrigin.php43

Sources: src/Traits/ResolvesEventOrigin.php35-44

---

Backtrace Analysis

Frame Limit Optimization

The backtrace is limited to 20 frames as a performance optimization. This limit balances two concerns:

1. Performance: Capturing and analyzing full backtraces is expensive
2. Practicality: The meaningful application frame is typically within the first 20 frames

The comment in the code explains: "We limit the backtrace to 20 frames to prevent too much overhead and we'd reasonable expect the origin to be within the first 20 frames" src/Traits/ResolvesEventOrigin.php15-16

Sources: src/Traits/ResolvesEventOrigin.php15-18

Backtrace Analysis Flow

Sources: src/Traits/ResolvesEventOrigin.php11-33

---

BacktraceHelper Integration

The trait delegates the core backtrace analysis logic to the BacktraceHelper class, which is resolved from the dependency injection container.

Key BacktraceHelper Methods

Method	Purpose
findFirstInAppFrameForBacktrace(array $backtrace)	Locates the first frame that belongs to application code (not vendor dependencies)
getOriginalViewPathForFrameOfCompiledViewPath(Frame $frame)	For frames in compiled view files, resolves back to the original view template path

Container Resolution

The helper is obtained through the container, allowing for proper dependency injection and testing:

private function getBacktraceHelper(): BacktraceHelper
{
 return $this->container()->get(BacktraceHelper::class);
}

This assumes the trait is used in a class that provides a container() method.

Sources: src/Traits/ResolvesEventOrigin.php46-49

---

View Path Resolution

A special case handled by the system is compiled view files. Modern PHP frameworks compile view templates (Blade, Twig, etc.) into cached PHP files. When a backtrace frame points to a compiled view file, the original template path is more meaningful for developers.

Resolution Process

The logic implements a fallback pattern:

This ensures that if view path resolution fails, the compiled file path is used instead.

Sources: src/Traits/ResolvesEventOrigin.php24-26

---

Output Format

Array Format

The structured array format follows Sentry's code context conventions with code. prefixed keys:

String Format

The string format provides a compact representation suitable for logging or simple display:

/app/src/Services/PaymentService.php:142

Note that the function name is omitted from the string representation.

Sources: src/Traits/ResolvesEventOrigin.php28-32 src/Traits/ResolvesEventOrigin.php43

---

Usage in Features

Integration Points

Based on the high-level architecture diagrams, the ResolvesEventOrigin trait is used in:

• RedisFeature: To determine where Redis commands originate in application code
• Other monitoring features that create spans and need to attribute them to application code locations

Example Usage Pattern

The feature listener receives the event in its own code context, but uses resolveEventOrigin() to walk back through the call stack to find where the application actually triggered the Redis operation.

Sources: src/Traits/ResolvesEventOrigin.php1-51

---

Performance Considerations

Backtrace Capture Cost

Capturing backtraces has a performance cost, which is why the system implements several optimizations:

1. Frame Limit: Only 20 frames are captured src/Traits/ResolvesEventOrigin.php17
2. Ignore Arguments: DEBUG_BACKTRACE_IGNORE_ARGS flag is used to skip argument serialization src/Traits/ResolvesEventOrigin.php17
3. Lazy Resolution: Origin is only resolved when needed, not automatically for every event

Trade-offs

Aspect	Benefit	Cost
20 frame limit	Reduced memory and CPU usage	May miss origin if call stack is deeper
Ignore arguments	Faster capture, less memory	Cannot inspect call arguments in backtrace
View path resolution	Better developer experience	Additional filesystem operations

Sources: src/Traits/ResolvesEventOrigin.php15-18

---

Error Handling

The system gracefully handles edge cases where origin cannot be determined:

Null Return Cases

Both methods return null when:

• No application frame is found in the backtrace (all frames are from vendor code) src/Traits/ResolvesEventOrigin.php20-22
• The backtrace is empty or malformed
• All frames are beyond the 20 frame limit

Fallback Behavior

When features use this trait, they should handle null returns appropriately:

• Omit origin metadata from spans/events
• Use a default or placeholder value
• Log a warning for investigation

Sources: src/Traits/ResolvesEventOrigin.php20-22 src/Traits/ResolvesEventOrigin.php39-41