Track custom events

When you installed and integrated the SDK for user monitoring, you added three methods to your app to begin tracking user activity:

  • trackSignup to track user account creation
  • trackLogin to track user logins
  • identify to track user sessions

Beyond those three, you can use the track SDK method to define and record custom events in your app.

Define your custom event

Define a custom event in your application.

Sqreen.event("my.event").track();

The SDK supports optional parameters, such as properties. Later, when you use your custom event in a Security Automation Playbook, you can use these parameters to group events and apply conditions and detections.

Sqreen.event("my.event")
    .property("foo", "bar")
    .track();

Because the SDK uses a builder pattern, tracking an event implies chained method calls terminated by a mandatory call to the track() method.

Sqreen.event(String eventName)
    // [optional] properties, one call per property.
    .property(String propertyKey, String propertyValue)
    // [optional] user identification key, one call per key.
    .authKey(String authKey, String authValue)
    // [optional] event timestamp
    .timestamp(Date timestamp)
    // [required] terminal call to 'track', event is ignored otherwise.
    .track();
  • eventName is the identifier of the event you wish to track. It is a string.
  • propertyKey and propertyValue enable you to define custom event properties. They are strings. Out of the box, the microagent collects several properties based on the HTTP request:

    • client IP address
    • user agent
    • path requested
    • request HTTP verb
    • HTTP parameters

  • authKey and authValue define the user account that performed the event. This must be the same object provided to the Sqreen.user().identify(), Sqreen.user().authTrack(), and Sqreen.user().signupTrack() methods. Refer to "Consistently identify users" section of the SDK documentation for details.

  • timestamp (optional) is a date object that sets the event's timestamp. By default, this object uses the current server time.

Use your custom event

  1. If you want to associate your custom event with a user account, you can either pass it to every track call, or rely on the identify method to set the custom event in the context of the current HTTP request.

  2. Navigate to your Sqreen Dashboard > Events explorer to check that Sqreen is recording your custom event as expected. Depending on the traffic to your application and the custom event's frequency of occurrence, you may want to wait a few hours or days to collect enough data to be useful.

Track events from the past

As you begin using your new custom event(s), it may be useful to import past events into Sqreen. This allows you start working with an existing dataset so you can examine output.

If your custom event includes the optional timestamp parameter, that parameter overrides the current server time.

Date eventDate = new Date("2018-03-15T14:42:00+01:00");
Sqreen.event("my.event")
    .property("foo", "bar")
    .timestamp(eventDate)
    .track();

Next steps