Events

Custom events play a vital role in understanding the behavior and performance of your application. They offer a flexible mechanism for tracking significant occurrences that are not captured by default metrics or logs. By strategically instrumenting custom events, you can gain valuable insights into user interactions, system events, and application workflows.

Instrument

Access the events instrument via the events namespace:

inspector.instruments.events

Configuration

Configure the events instrument using the main Inspector configuration options:

const inspector = new Inspector({
  instruments: {
    events: {
      disabled: false,
    },
  },
});

Available configuration options:

• disabled: boolean: Disables the instrument. When disabled, the instrument cannot be activated, and no data will be recorded (default false).

Tracking Events

To record a custom event, utilize the push method of the events instrument. The name of the event is mandatory, while attributes are optional.

inspector.instruments.events.push({
  attributes: {
    userId: '123',
  },
  name: 'event_name',
});

Querying Events

While you can easily view recorded events in the Application, sometimes you may need to perform more specific queries. In such cases, utilize the query() function, which is consistent across all instruments.

inspector.instruments.events.query({
  endTime: Date.now(),
  startTime: Date.now() - 60000,
});

This example demonstrates querying events within a specific time range, from the current time minus one minute to the current time. Adjust the startTime and endTime parameters as needed to tailor your query to your requirements.

Best Practices

When defining custom events, consider the following best practices:

1. Event Names: Choose descriptive and standardized names for events that reflect their purpose and context within your application. Consistency in naming conventions simplifies analysis and ensures clarity across your monitoring setup.

2. Event attributes: Include relevant attributes with each event to provide additional context and facilitate detailed analysis. Common attributes may include user IDs, error codes, or any other pertinent information that enhances understanding of the event.

3. Granularity: Strike a balance between granularity and overhead when instrumenting custom events. Aim to capture meaningful events without overwhelming your monitoring system with excessive data points. Focus on events that are actionable and align with your monitoring objectives.

4. Event volume: Be mindful of the volume of custom events generated by your application. Excessive event creation can strain system resources and impede performance. Prioritize essential events that contribute to your understanding of application behavior.

Traces

Interested in Trace Span Events? Span Events are events linked directly to a specific trace within your application, providing detailed insights into the flow of execution. Unlike Custom Events, which are independent occurrences, Span Events are tied to a specific trace context. For further details, please refer to the Traces page.