Errors, occurrences and issues

An occurrence is one captured event. An issue groups occurrences with matching fingerprints so you can investigate a recurring failure without treating every retry as a different problem.

#Capture an exception or message

Laravel-reportable exceptions are captured automatically after installation and consent. For a caught exception, use Laravel's report($exception) or the SDK directly. Here is a complete manual capture example:

use ZXN\NativeWatch\Core\Laravel\NativeWatch;

try {
    throw new RuntimeException('Inventory sync verification');
} catch (RuntimeException $exception) {
    $eventId = NativeWatch::captureException($exception);
}

The returned ID identifies a captured event. A non-null value does not mean the server has stored it. Delivery normally follows the response; see delivery results when you need to check transport acceptance.

For a condition that is useful to record without an exception:

use ZXN\NativeWatch\Core\Laravel\NativeWatch;
use ZXN\NativeWatch\Core\Level;

NativeWatch::captureMessage('Inventory sync was deferred', Level::Warning);

Keep messages stable and avoid customer data. A changing identifier is usually better left out than embedded in every message.

#Read an issue

Begin with the occurrence's timestamp, release and environment. Confirm that it belongs to the build and runtime you are investigating. Then read the throw site and application stack frames, followed by the breadcrumbs and context.

The SDK normalizes application paths, maps compiled Blade files back to their templates where possible, and includes limited PHP source excerpts by default. Source capture is controlled by source_code_lines in the published SDK configuration. Set it to 0 when source should remain on the device.

Native instruction addresses need matching iOS symbols. A PHP source excerpt and a symbolicated native frame are different types of evidence. Likely commits use exact PHP source locations from a published build manifest.

#Understand grouping and status

For exceptions with frames, default grouping uses the exception type and the throw-site and application-frame file/function identities. It does not include the line number or exception message in that fingerprint. A line moving between builds therefore need not create a new issue.

Without frames, exception grouping uses the type and message with numeric sequences normalized. Plain messages group by severity and a similarly normalized message. For example, changing an order number in an otherwise identical message need not split the issue. Grouping is scoped to the project.

Resolving an issue records your assessment that it is fixed. A later matching occurrence reopens a resolved issue. Ignoring an issue is a triage state; it does not disable SDK collection or stop those occurrences consuming event quota.

#Record useful breadcrumbs

Breadcrumbs describe what happened before the captured error:

use ZXN\NativeWatch\Core\Laravel\NativeWatch;

NativeWatch::addBreadcrumb('sync', 'Started inventory sync');

The default limit is 30. Laravel logs can also become breadcrumbs. Persistent mobile requests and asynchronous queue jobs reset their scope so one request's context does not leak into the next; add context where the operation actually runs.

#Investigate missing or unexpected events

An exception that Laravel deliberately does not report will not reach its reporting hook. A log message alone is a breadcrumb, while a throwable under the log context's exception key can be captured as an exception. The same throwable is deduplicated within the client process.

Check consent, sampling, custom beforeSend filtering and outbox results before assuming capture failed. Inspect privacy settings before expanding context to diagnose a problem.