Custom Event Tracking

Laritor can track custom events from your Laravel application so you can mark important business or technical moments in production and see exactly where they happened.

Custom events are useful when you want visibility into application-specific actions that Laravel and Laritor do not automatically capture for you.

Examples include:

• A checkout step starting or finishing
• A tenant sync job beginning an expensive phase
• A cache warmup command switching to a fallback path
• A scheduled import reaching an external API rate limit
• A payment retry being triggered

---

Getting started

1. Update the Laritor client package

First, update your Laritor client ingest package to the latest version:

composer require binarybuilds/laritor-client

2. Send a custom event from your code

Use Laritor::addCustomEvent() anywhere in your application where you want to mark an important event:

use BinaryBuilds\LaritorClient\Laritor;

Laritor::addCustomEvent('event-name', [
    'meta_key' => 'meta_value',
]);

The first argument is the event name. The second argument is an array of metadata that Laritor stores alongside the event.

Use event names that are stable and easy to filter, such as:

• checkout.started
• checkout.payment_authorized
• inventory.sync.completed
• cache.warmup.fallback_used
• billing.retry_scheduled

---

Where custom events appear in Laritor

After your application starts sending custom events, Laritor surfaces them in two main places.

Timeline view

Laritor shows custom events directly on the timeline view for:

• Requests
• Jobs
• Scheduled tasks
• Commands

This lets you see exactly where the event occurred, in the correct order, alongside everything else Laritor captured for that execution, including its attached metadata.

This is useful when you need to answer questions like:

• Did this event happen before or after a slow query?
• Was the fallback path triggered before the outbound API call failed?
• Which phase of a job caused the runtime spike?

Custom Events page

Laritor also adds a Custom Events menu item in the main navigation.

From there, you can:

• View all custom events in your application
• See total occurrences for each event during a selected timeframe
• Click an event to drill into its details

On the event details view, Laritor shows:

• A graph of event occurrences across the selected timeframe
• A table of all occurrences
• The trigger context for each occurrence, such as request, job, command, or scheduled task
• The metadata attached to each event

This makes it easy to measure how often important application behaviors happen and where they are happening.

---

Example usage

Example: Marking checkout milestones

use BinaryBuilds\LaritorClient\Laritor;

Laritor::addCustomEvent('checkout.started', [
    'cart_id' => $cart->id,
    'user_id' => $user->id,
    'items_count' => $cart->items()->count(),
]);

Laritor::addCustomEvent('checkout.payment_authorized', [
    'cart_id' => $cart->id,
    'payment_provider' => 'stripe',
    'amount' => $cart->total(),
]);

Why this helps:

• You can see where checkout latency increases between milestones
• You can correlate payment authorization with slow queries or outbound requests
• You can measure how often customers begin checkout versus reach payment authorization

Example: Tracking expensive job phases

use BinaryBuilds\LaritorClient\Laritor;

Laritor::addCustomEvent('tenant-sync.started', [
    'tenant_id' => $tenant->id,
]);

Laritor::addCustomEvent('tenant-sync.remote-fetch.completed', [
    'tenant_id' => $tenant->id,
    'records_received' => $recordsCount,
]);

Laritor::addCustomEvent('tenant-sync.persist.completed', [
    'tenant_id' => $tenant->id,
    'records_written' => $writtenCount,
]);

Why this helps:

• You can identify whether the job is slow during fetching, transformation, or persistence
• You can compare event frequency and timing across tenants
• You can inspect the exact job timeline instead of guessing where time was spent

Example: Tracking fallback paths in commands or scheduled tasks

use BinaryBuilds\LaritorClient\Laritor;

Laritor::addCustomEvent('reports.cache-miss-fallback', [
    'report' => 'monthly-revenue',
    'environment' => app()->environment(),
]);

Why this helps:

• You can detect when expensive fallback logic runs in production
• You can see whether fallback execution lines up with slower command or task durations
• You can quantify how often the fallback path is being used over time

---

Best practices

• Use consistent event names so trends remain easy to analyze over time.
• Attach metadata that helps with debugging, such as IDs, counts, sources, modes, or provider names.
• Avoid attaching sensitive secrets or unnecessary large payloads.
• Place events around important transitions, not every line of code.
• Use timeline context to understand order of operations before optimizing.

---

Summary

Custom events let you instrument the moments that matter most in your application and then analyze them inside Laritor with the same depth as built-in telemetry.

Use them to understand behavior, debug production issues faster, and improve the performance of your Laravel application based on real execution context instead of guesswork.