Custom Events

The custom events API allows you to send application-specific events with optional data and attributes. These events can represent user actions, business metrics, or any significant occurrence in your application.

Critical Custom Event Behavior:

• Events are sent asynchronously (non-blocking)
• Events are transmitted to all configured endpoints
• Events matching internal SDK event names are dropped with a warning
• Events sent before init() may be queued or dropped
• Invalid event data may cause the event to be dropped
• Future and past timestamps are allowed

Capabilities

Send Custom Event

Sends a custom event with optional data and attributes.

/**
 * Sends a custom event
 * @param name - Event name (cannot be an internal event name)
 * @param opts - Additional event details (optional)
 * @throws No errors thrown; invalid events may be dropped with warning
 */
function sendEvent(name: string, opts?: EventOptions): void;

interface EventOptions {
  /** Human readable title for the event (short sentence summary) */
  title?: string;
  /** Event timestamp (defaults to current time) */
  timestamp?: number | Date;
  /** Event body/data */
  data?: AttributeValueType | AnyValue;
  /** Event attributes */
  attributes?: Record<string, AttributeValueType | AnyValue>;
  /** Log severity level */
  severity?: LOG_SEVERITY_TEXT;
}

type LOG_SEVERITY_TEXT =
  | "UNSPECIFIED"
  | "TRACE"
  | "DEBUG"
  | "INFO"
  | "WARN"
  | "ERROR"
  | "FATAL";

Usage Examples:

import { sendEvent } from "@dash0/sdk-web";

// Simple event
sendEvent("user_action");

// Event with data
sendEvent("button_clicked", {
  data: "submit_form",
});

// Event with attributes and severity
sendEvent("purchase_completed", {
  title: "User completed purchase",
  data: { orderId: "order-123", amount: 99.99 },
  attributes: {
    "order.id": "order-123",
    "order.amount": 99.99,
    "order.currency": "USD",
  },
  severity: "INFO",
});

// Event with custom timestamp
sendEvent("scheduled_task", {
  timestamp: new Date("2024-01-15T10:00:00Z"),
  data: "backup_completed",
});

For IIFE (script tag) usage:

dash0("sendEvent", "user_action");
dash0("sendEvent", "purchase_completed", {
  data: { orderId: "order-123" },
  severity: "INFO",
});

Critical Behavior:

• Events are sent asynchronously (non-blocking)
• If SDK is not initialized, events may be queued or dropped
• If event name is an internal SDK event name, event is dropped and warning is logged
• Events are transmitted to all configured endpoints
• Invalid event data may cause the event to be dropped
• Future timestamps are allowed (for scheduled events)
• Past timestamps are allowed (for retroactive event logging)
• Very large event payloads may be truncated or cause transmission issues
• Events are queued in memory if transmission is slow

Event Restrictions

Important: The event name cannot be any of the internal event names used by the SDK:

• browser.page_view
• browser.navigation_timing
• browser.web_vital
• browser.error

If you attempt to use an internal event name, the SDK will log a warning and drop the event.

Critical Behavior:

• Internal event name check is case-sensitive
• Using an internal event name does not throw an error; event is silently dropped
• Warning is logged at the current log level (default: warn)
• Event name validation occurs before transmission
• Partial matches (e.g., browser.page_view_custom) are allowed
• Event names starting with browser. are not automatically blocked; only exact matches are blocked

Event Attributes

The event title is transmitted via the dash0.web.event.title attribute. The event name is transmitted via the event.name attribute.

Critical Behavior:

• event.name is always included (set to the provided name)
• dash0.web.event.title is only included if title is provided
• Additional attributes from opts.attributes are merged with these standard attributes
• Attribute names follow OpenTelemetry semantic conventions when possible
• Reserved attribute names may be overwritten by SDK
• Attribute conflicts between opts.attributes and standard attributes are resolved in favor of standard attributes

Common Use Cases

User Actions

Track user interactions and behaviors:

import { sendEvent } from "@dash0/sdk-web";

// Button clicks
sendEvent("checkout_button_clicked", {
  title: "User clicked checkout button",
  attributes: {
    "button.id": "checkout-btn",
    "page.url": window.location.href,
  },
  severity: "INFO",
});

// Form submissions
sendEvent("form_submitted", {
  title: "Contact form submitted",
  attributes: {
    "form.id": "contact-form",
    "form.fields": 5,
  },
});

// Navigation events
sendEvent("tab_switched", {
  attributes: {
    "tab.from": "overview",
    "tab.to": "details",
  },
});

Business Metrics

Track business-critical events:

// Purchase events
sendEvent("purchase", {
  title: "Purchase completed",
  data: {
    orderId: "ORD-12345",
    amount: 149.99,
    currency: "USD",
  },
  attributes: {
    "transaction.id": "TXN-67890",
    "payment.method": "credit_card",
    "cart.items": 3,
  },
  severity: "INFO",
});

// Subscription events
sendEvent("subscription_upgraded", {
  title: "User upgraded subscription",
  attributes: {
    "subscription.from": "basic",
    "subscription.to": "premium",
    "subscription.price": 29.99,
  },
});

// Feature usage
sendEvent("feature_used", {
  attributes: {
    "feature.name": "advanced_search",
    "feature.category": "search",
  },
});

Application State Changes

Track significant application state changes:

// Mode changes
sendEvent("dark_mode_enabled", {
  attributes: {
    "theme.previous": "light",
    "theme.current": "dark",
  },
});

// Settings changes
sendEvent("settings_updated", {
  data: {
    notifications: true,
    autoSave: false,
  },
  attributes: {
    "settings.category": "preferences",
  },
});

Custom Workflows

Track multi-step workflows:

// Workflow start
sendEvent("onboarding_started", {
  title: "User started onboarding",
  attributes: {
    "workflow.id": "onboarding-2024",
    "workflow.step": 1,
  },
});

// Workflow progress
sendEvent("onboarding_step_completed", {
  attributes: {
    "workflow.id": "onboarding-2024",
    "workflow.step": 2,
    "workflow.total_steps": 5,
  },
});

// Workflow completion
sendEvent("onboarding_completed", {
  title: "User completed onboarding",
  attributes: {
    "workflow.id": "onboarding-2024",
    "workflow.duration_seconds": 180,
  },
});

Error and Warning Events

Use custom events for application-specific errors and warnings:

// Application warnings
sendEvent("quota_warning", {
  title: "User approaching storage quota",
  attributes: {
    "quota.used_bytes": 950000000,
    "quota.total_bytes": 1000000000,
    "quota.percentage": 95,
  },
  severity: "WARN",
});

// Validation errors
sendEvent("validation_error", {
  title: "Form validation failed",
  data: {
    field: "email",
    error: "Invalid email format",
  },
  attributes: {
    "form.id": "registration",
  },
  severity: "ERROR",
});

Performance Markers

Track custom performance markers:

// Custom timing events
const startTime = Date.now();

// ... perform operation ...

sendEvent("operation_completed", {
  title: "Data processing completed",
  attributes: {
    "operation.name": "process_large_dataset",
    "operation.duration_ms": Date.now() - startTime,
    "operation.records": 10000,
  },
});

Timestamps

The timestamp parameter accepts either:

• A number (Unix timestamp in milliseconds)
• A Date object

If not provided, the current time is used.

// Using Date object
sendEvent("scheduled_event", {
  timestamp: new Date(),
});

// Using Unix timestamp
sendEvent("scheduled_event", {
  timestamp: Date.now(),
});

// Using specific date
sendEvent("scheduled_event", {
  timestamp: new Date("2024-01-15T10:00:00Z"),
});

Critical Behavior:

• Timestamps are stored as milliseconds since epoch
• Future timestamps are allowed (for scheduled events)
• Past timestamps are allowed (for retroactive event logging)
• Invalid timestamps may be ignored or cause errors
• Timestamp precision is limited to milliseconds
• NaN timestamp values may be ignored or cause errors
• Very old or very future timestamps may be filtered by endpoints
• Clock changes may affect timestamp accuracy

Severity Levels

Events can have different severity levels to indicate their importance:

• UNSPECIFIED - No severity specified
• TRACE - Fine-grained debugging information
• DEBUG - Debug information
• INFO - Informational messages (default for most events)
• WARN - Warning messages
• ERROR - Error messages
• FATAL - Fatal error messages

sendEvent("system_check", { severity: "INFO" });
sendEvent("deprecated_api_used", { severity: "WARN" });
sendEvent("critical_failure", { severity: "ERROR" });

Critical Behavior:

• Severity is case-sensitive
• Invalid severity values may be ignored or default to UNSPECIFIED
• Severity affects how events are displayed and filtered in Dash0
• Severity does not affect event transmission (all events are sent)
• Severity is included as an attribute in the event
• Severity does not affect event queuing or dropping

Edge Cases and Error Conditions

Event Name Validation

• Internal Event Names: Using internal event names (browser.page_view, etc.) causes event to be dropped
• Empty Names: Empty event names may be ignored or cause errors
• Very Long Names: Very long event names may be truncated or cause transmission issues
• Special Characters: Special characters in event names are preserved
• Unicode Characters: Unicode characters in event names are preserved
• Case Sensitivity: Event name validation is case-sensitive
• Partial Matches: Partial matches to internal event names are allowed

Event Data

• Invalid Types: Invalid data types may be ignored or converted
• Circular References: Objects with circular references may cause errors
• Very Large Data: Very large data payloads may be truncated or cause transmission issues
• Null/Undefined: Null or undefined data may be ignored or converted
• Nested Structures: Very deeply nested structures may cause serialization issues
• Array Limits: Very large arrays may cause transmission issues
• Object Limits: Very large objects may cause transmission issues

Timestamps

• Invalid Dates: Invalid Date objects may cause errors or be ignored
• NaN Timestamps: NaN timestamp values may be ignored or cause errors
• Extreme Timestamps: Very old or very future timestamps are allowed but may be filtered
• Clock Skew: System clock changes may affect timestamp accuracy
• Timezone Issues: Timezone changes may affect timestamp accuracy
• Precision Loss: Timestamp precision is limited to milliseconds

Initialization

• Before Init: If sendEvent() is called before init(), events may be queued or dropped
• After Init: Events sent after initialization are transmitted immediately
• Multiple Init: If init() is called multiple times, events are sent to all configured endpoints
• Init Failure: If initialization fails, queued events may be lost

Network and Transmission

• Offline Mode: Events are queued when offline and transmitted when online
• Network Failures: Network failures do not throw errors; events may be queued or dropped
• Transmission Delays: Events are sent asynchronously; transmission delays are not reported
• Rate Limiting: Endpoints may rate limit events; SDK may retry or drop events
• Multiple Endpoints: Events are sent to all configured endpoints
• Partial Failures: If one endpoint fails, events are still sent to other endpoints
• Transmission Timeouts: Transmission timeouts may cause events to be dropped

Performance

• High Frequency: Sending many events quickly may impact performance
• Large Payloads: Large event data may impact transmission performance
• Event Queuing: If transmission is slow, events may be queued in memory
• Memory Usage: Queued events may increase memory usage if transmission is slow
• CPU Usage: Event serialization may increase CPU usage

Multiple Endpoints

• All Endpoints: Events are sent to all configured endpoints
• Partial Failures: If one endpoint fails, events are still sent to other endpoints
• Endpoint Errors: Endpoint errors do not affect other endpoints
• Endpoint Ordering: Endpoints are processed in order; order may affect performance
• Very Many Endpoints: Very many endpoints may impact performance

Severity Edge Cases

• Invalid Severity: Invalid severity values may be ignored or default to UNSPECIFIED
• Case Sensitivity: Severity is case-sensitive; "info" is not the same as "INFO"
• Null/Undefined: Null or undefined severity may default to UNSPECIFIED
• Non-String Values: Non-string severity values may be ignored or cause errors

Attribute Edge Cases

• Reserved Attributes: Reserved attribute names may be overwritten by SDK
• Attribute Conflicts: Attribute conflicts between opts.attributes and standard attributes are resolved in favor of standard attributes
• Invalid Attributes: Invalid attribute values may be ignored or converted
• Very Many Attributes: Very many attributes may impact transmission performance