recordCustomEvent (Android SDK API)

Syntax

NewRelic.recordCustomEvent(string $eventType, [string $eventName,] map<string, object> $eventAttributes)

Records a custom New Relic mobile monitoring event.

Requirements

Agent version 5.12.0 or higher.

Description

Creates and records a custom event, for use in NRQL. The event includes a list of attributes, specified as a map. Unlike using setAttribute, adding attributes to a custom event adds them only to that event; they are not session attributes.

Important considerations and best practices include:

  • You should limit the total number of event types to approximately five. eventType is meant to be used for high-level categories. For example, you might create an event type Gestures.
  • Do not use eventType to name your custom events. Create an attribute to name an event or use the optional name parameter. You can create many custom events; it is only event types that you should limit.
  • Using the optional name parameter has the same effect as adding a name key in the attributes dictionary. name is a keyword used for displaying your events in the New Relic UI. To create a useful name, you might combine several attributes (see examples).

Important

As of New Relic Android agent version 5.12.0, the recordEvent method is deprecated and replaced with recordCustomEvent. The recordEvent method will continue to work for an unspecified period of time, but if your app contains recordEvent methods, New Relic recommends you replace them.

Updating these methods will affect any NRQL queries and that use the deprecated event types. Be sure to adjust your NRQL queries and dashboards as needed.

For more on other Android APIs, see Send custom attributes and events.

Parameters

Parameter

Description

$eventType

string

Required. The type of event. Do not use $eventType to name your custom events. Instead, use a custom attribute or the optional name.

$eventName

string

Optional. Use this parameter to name the event. (Using this parameter is equivalent to creating a name parameter.)

$eventAttributes

map<string, object>

Optional. A map that includes a list of attributes that further designate subcategories to the $eventType. You can create attributes for any event descriptors you think will be useful. To name your custom events, create a name attribute or use the eventName parameter.

Note: Not all object types are supported. See setAttribute for details on supported types.

Important

When setting the key for your custom attributes, be aware that there are default attributes that cannot be overridden.

Return values

Returns true if the event is recorded successfully, or false if not.

Examples

Basic custom event

Map attributes = new HashMap();
attributes.put("attributeName1", "value1");
attributes.put("attributeName1", 2);
boolean eventRecorded = NewRelic.recordCustomEvent("eventType", attributes);

Custom event with several attributes

Notice how the eventType parameter is used for a high-level category, Car.

Map attributes = new HashMap();
attributes.put("make", "Ford");
attributes.put("model", "ModelT");
attributes.put("color", "Black");
attributes.put("VIN", "123XYZ");
attributes.put("maxSpeed", 12);


NewRelic.recordCustomEvent("Car", attributes);

Custom event using 'name' parameter

Map attributes = new HashMap();
attributes.put("make", "Ford");
attributes.put("model", "ModelT");


NewRelic.recordCustomEvent("Car", "Ford Model T", attributes);