Track custom events

This guide will guide you into tracking custom events using the Sqreen SDK and eventually automate security scenarios. Visit the security automation section to learn more.

Events are stored locally in a queue until the next heartbeat. Every minute, events tracked are flushed to our servers. When your app exits, events are flushed.

To complete this guide, you should have installed our library in your application. Follow the installation steps described here.

Tracking events

The track SDK method is used to record your custom events.

Recording an event is as simple as naming it:

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

Of course, this is a basic version and our SDK supports additional optional attributes, such as properties:

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

Later on, when creating playbooks using this event, you'll be able to use those dimensions to group events and apply conditions and detections.

Default dimensions

Out of the box, Sqreen library collects some dimensions based on the HTTP request:

  • Client IP.
  • User agent.
  • Path requested.
  • Request HTTP verb.
  • HTTP parameters.

By default all of these dimensions are scrubbed from sensitive data. See PII scrubbing

Track method definition

Since we use a builder pattern in our SDK, tracking an event implies chained method calls terminated by a mandatory call to 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 a string. This is the name of the event you're tracking.
  • propertyKey and propertyValue are strings. Those enable to define custom event properties.
  • authKey and authValue: Define use account who performed the event. This should be the same object provided to Sqreen.user().identify(), Sqreen.user().authTrack() or Sqreen.user().signupTrack() method when used.
  • timestamp: a Date object if you want to manually set the event’s timestamp. By default, the current server time will be used. This parameter is optional.

User tracking

When the event tracked must be associated with a user account, you can decide to either pass it to every track call or rely on the identify method to set it in the context of the current HTTP request.

When track is provided with user identifiers, the identify value will be overridden for the context of this event.

Block users

Implementing identify method is required to block users.

Monitor events

Congrats! You've setup the Sqreen SDK successfully and tracked your first custom events.

Now, go to your dashboard and visit the Event Explorer in order to validate that events are properly recorded by Sqreen.

Next, depending on your traffic and the frequency of the tracked event, you may want to wait few hours or days in order to collect enough events to craft a security automation playbook leveraging your custom event.

event explorer

Create a security automation playbook

Once you're ready to automate security responses based on a custom event activity, go to your dashboard and visit the Automation Plugins section to start building an automation plugin.

Track events from the past

When getting started on Sqreen, it can be handy to import past events in order to start with an existing dataset and automate scenarios right away.

When tracking event, using the optional timestamp parameter will enable to override 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();

Error handling

Things can some time go wrong, for various reasons. This section features the most frequent issues when using our SDK.

Events recording

In case the Sqreen agent doesn't manage to flush events collected in the past minute to our servers, it'll keep retrying. After sometimes, the events will be dropped to prevent Sqreen memory overhead to grow and impact your application's performance.