Skip to main content

Custom Events

Generates: Logs

Learn how to track custom business events, user actions, and application milestones in your application.

Setup​

Ensure the Pulse SDK is properly initialized. See Quick Start for setup instructions.

What are Custom Events?​

Custom events are used to track specific moments or actions in your application. Unlike spans which measure duration, events represent discrete occurrences - like a user clicking a button, completing a purchase, or reaching a milestone.

Events can include attributes to provide context about what happened, making them powerful for understanding user behavior and application usage patterns.

Basic Usage​

Simple Events​

Track events without additional context:

import { Pulse } from '@horizoneng/pulse-react-native';

// User actions
Pulse.trackEvent('app_opened');
Pulse.trackEvent('user_logout');
Pulse.trackEvent('settings_changed');

Events with Attributes​

Add context to your events with attributes:

// User signup
Pulse.trackEvent('user_signup', {
  plan: 'pro',
  source: 'mobile',
  referralCode: 'FRIEND2024'
});

// Product interaction
Pulse.trackEvent('product_viewed', {
  productId: 'SKU-12345',
  category: 'electronics',
  price: 299.99,
  inStock: true
});

// Feature usage
Pulse.trackEvent('search_performed', {
  query: 'react native',
  resultsCount: 42,
  filterApplied: true
});

Supported attribute types: string, number, boolean, and arrays of these types.

Event Correlation with Spans​

When you track an event during an active span, it's automatically correlated with that span. This helps you understand which events occurred during specific operations:

const checkoutSpan = Pulse.startSpan('checkout_process', {
  attributes: { userId: '12345' }
});

// Events tracked during checkout
Pulse.trackEvent('payment_method_selected', {
  method: 'credit_card'
});

Pulse.trackEvent('shipping_address_entered', {
  country: 'US',
  state: 'CA'
});

checkoutSpan.end();

Events tracked while a span is active automatically include span_id and trace_id, allowing you to see the complete picture of what happened during an operation.

Sample Telemetry​

Events generate log records with the following structure:

Type: Log Record (Event)
Body: Event name (defined by you)
pulse.type: custom_event

Example: Simple Event​

{
  "body": "user_signup",
  "timestamp": "2025-11-27T13:34:35.947Z",
  "attributes": {
    "pulse.type": "custom_event",
    "plan": "pro",
    "source": "mobile",
    "platform": "react-native",
    "session.id": "dce09977c69b0a5c15aa5fd01f817514"
  },
  "span_id": "",
  "trace_flags": 0,
  "trace_id": ""
}

Example: Event with Active Span Correlation​

{
  "body": "payment_method_selected",
  "timestamp": "2025-11-27T13:34:37.563Z",
  "attributes": {
    "pulse.type": "custom_event",
    "method": "credit_card",
    "platform": "react-native",
    "session.id": "dce09977c69b0a5c15aa5fd01f817514"
  },
  "span_id": "d0a52cbd9e7613f5",
  "trace_flags": 1,
  "trace_id": "df4b745571b43b2c8eaec13cc8484394"
}

Note: Events tracked during an active span automatically include span_id and trace_id for correlation. All events also include global attributes (service, device, OS, network, etc.) in the resources object. See Global Attributes for details.

Best Practices​

Use Descriptive Event Names​

Choose clear, specific names that indicate what happened:

// ✅ Good
Pulse.trackEvent('checkout_initiated');
Pulse.trackEvent('password_reset_requested');
Pulse.trackEvent('video_playback_started');

// ❌ Avoid
Pulse.trackEvent('button_clicked');
Pulse.trackEvent('user_action');
Pulse.trackEvent('event');

Include Relevant Context​

Add attributes that help you understand and analyze the event:

Pulse.trackEvent('search_performed', {
  query: 'react native',
  resultsCount: 42,
  filterApplied: true,
  searchType: 'autocomplete',
  latencyMs: 150
});

Maintain Naming Consistency​

Use a consistent naming convention across your events:

// Use snake_case consistently
Pulse.trackEvent('user_login');
Pulse.trackEvent('order_placed');
Pulse.trackEvent('subscription_upgraded');

Protect User Privacy​

Never include sensitive or personally identifiable information:

// ❌ Don't do this
Pulse.trackEvent('user_login', {
  email: 'user@example.com',
  password: 'secret123',
  creditCard: '1234-5678-9012-3456'
});

// ✅ Use identifiers instead
Pulse.trackEvent('user_login', {
  userId: 'user_abc123',
  loginMethod: 'email',
  success: true
});

Track Events Within Operations​

When tracking events related to a specific operation, do it within a span:

const paymentSpan = Pulse.startSpan('process_payment');

Pulse.trackEvent('payment_initiated', { amount: 99.99 });
// ... payment processing ...
Pulse.trackEvent('payment_completed', { transactionId: 'TX-123' });

paymentSpan.end();

This creates a correlation between the events and the operation, giving you better insights.