New Relic custom events aren’t just for tracking errors; they’re a powerful way to ingest discrete business actions, giving you direct insight into user journeys and system behaviors that traditional metrics miss.
Let’s see this in action. Imagine a simple e-commerce checkout process. We want to track when a user adds an item to their cart, when they initiate checkout, and when their order is successfully placed.
Here’s how you’d send a "product added to cart" event using the New Relic Node.js agent:
const newrelic = require('newrelic');
// ... inside your application logic when a product is added to cart ...
const productDetails = {
productId: 'SKU12345',
productName: 'Super Widget',
price: 29.99,
quantity: 1,
userId: 'user-abc-789'
};
newrelic.recordCustomEvent('ProductAddedToCart', productDetails);
And for a successful order:
// ... inside your application logic when an order is successfully placed ...
const orderDetails = {
orderId: 'ORD987654',
totalAmount: 59.98,
currency: 'USD',
userId: 'user-abc-789',
items: ['SKU12345', 'SKU67890']
};
newrelic.recordCustomEvent('OrderPlaced', orderDetails);
When these events are ingested, they appear in New Relic as distinct data points. You can query them using NRQL (New Relic Query Language) just like any other event type. For instance, to see how many times a product was added to a cart in the last hour:
SELECT count(*) FROM ProductAddedToCart SINCE 1 hour ago
Or to find the total value of orders placed by a specific user:
SELECT sum(totalAmount) FROM OrderPlaced WHERE userId = 'user-abc-789' SINCE 24 hours ago
The real power comes from correlating these business events with performance data. You can see, for example, if a spike in ProductAddedToCart events is preceded by increased latency in your product catalog service, or if a drop in OrderPlaced events coincides with a surge in SystemErrors.
The core of custom event ingestion is the recordCustomEvent API call. It takes two primary arguments: the event name (a string, e.g., 'ProductAddedToCart') and an optional object containing event attributes (key-value pairs). These attributes are what make your events rich with context. They can be simple strings, numbers, booleans, or even arrays. New Relic automatically indexes most common attribute types, making them searchable and aggregatable.
When you send attributes, New Relic stores them as discrete fields associated with that event. This means you can filter, group, and aggregate based on any of these attributes. For example, if you sent a statusCode attribute with an ApiRequest event, you could easily query:
SELECT count(*) FROM ApiRequest WHERE statusCode = 500 SINCE 1 hour ago
Beyond the basic recordCustomEvent, the agent offers more advanced capabilities. For instance, you can attach custom attributes to all events of a certain type automatically using newrelic.addCustomAttribute. This is useful for adding consistent identifiers like environment: 'production' or region: 'us-east-1' to every event originating from a specific service.
The recordMetric API is often confused with custom events, but it serves a different purpose. recordMetric is for time-series numerical data (like request duration or queue size), which are aggregated over time. Custom events, on the other hand, are discrete, individual occurrences. You can, however, send custom event attributes that are numerical and then aggregate them using NRQL, effectively creating custom metrics from your events. For example, you could send the price of an item in a ProductAddedToCart event and then query SELECT average(price) FROM ProductAddedToCart.
The key is understanding what constitutes an "event" in your business. Is it a user action? A system state change? A transaction completion? Any discrete, meaningful occurrence that you want to track, analyze, and potentially correlate with system performance is a candidate for a custom event. The attributes you choose to send with these events are critical; they are the dimensions by which you’ll slice and dice your data. Aim for attributes that represent unique identifiers, categorical data, or quantitative measurements relevant to the event itself.
While most standard attribute types are automatically indexed for querying, very high-cardinality string attributes (e.g., unique user IDs in every single event without aggregation) can impact index size and query performance. For such cases, consider if the attribute truly needs to be individually searchable or if it’s primarily for filtering or context. If it’s the latter, you might explore alternative strategies like custom attributes on the agent or pre-aggregating data before sending it.
Once your custom events are flowing, the next logical step is to visualize them. Creating custom dashboards with charts based on your ProductAddedToCart and OrderPlaced events, alongside your application’s performance metrics, will give you a holistic view of your business operations and their underlying technical health.