Track custom events

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

The Sqreen SDK stores events locally in a queue until the next heartbeat. Every minute, it flushes tracked events to our servers. When your app exits, it flushes any remaining tracked events.

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

Tracking events

Use the track SDK method to record your custom events.

Recording an event by naming it:

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

Our SDK supports optional attributes, such as properties:

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

When creating playbooks using this event, you are able to use these properties to group events and apply conditions and detections.

Default properties

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

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

By default, the Sqreen SDK scrubs sensitive data from these properties. 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 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 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 the account that performed the event. This should be the same object provided to the Sqreen.user().identify(), Sqreen.user().authTrack() or Sqreen.user().signupTrack() methods.
  • timestamp is a Date object. Use this if you want to manually set the event's timestamp. By default, Sqreen uses the current server time. This parameter is optional.

User tracking

If you want to associate the event tracked 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.

Providing track with user identifiers overrides the identify value for the context of this event.

Block users

To block users you must implement the identify method.

Monitor events

Congratulations! You've set up the Sqreen SDK and tracked your first custom events.

Now, go to your dashboard and visit the Event Explorer to check the events are properly recorded by Sqreen.

Next, depending on your traffic and the frequency of the tracked events, you may want to wait a few hours or days to collect enough events to craft a playbook.

event explorer

Create a security automation playbook

Once you are ready to automate a scenario, go to your dashboard and visit the Playbooks section to start building an automation playbook.

Track events from the past

When getting started with Sqreen, it can be useful to import past events. This lets you start with an existing dataset and automate scenarios right away.

When tracking an event, using the optional timestamp 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();

Error handling

Things can sometimes go wrong. This section features the most frequent issues when using our SDK.

Events recording

If the Sqreen agent does not manage to flush events collected in the past minute to our servers, it keeps retrying. After some time, it drops the events to prevent Sqreen memory overhead growing and impacting your application's performance.