Track custom events

This guide will help you track 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

You can use the track SDK method to record your custom events.

To track a custom event, you need to name it:

const Sqreen = require('sqreen');
Sqreen.track(event.name)

Our SDK supports additional optional parameters, such as properties:

const Sqreen = require('sqreen');
Sqreen.track(event.name, {properties: {foo: 'bar'}})

When creating automation playbooks using this event, you can use those 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 all of these properties are scrubbed of sensitive data. See PII scrubbing

Track method definition

const Sqreen = require('sqreen');
Sqreen.track(event_name, [options])

• event_name is a string. This is the name of the event you're tracking.
• options enables you to provide additional parameters. This is an object with the following fields:
  • properties: an object with arbitrary parameters to record custom event dimensions. This parameter is optional. You can provide up to 16 properties per event.
  • user_identifiers: user account which performed the event. This should be the same object provided to Sqreen.identify, Sqreen.auth_track or Sqreen.signup_track method when used. This parameter is optional.
  • 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.
  • collect_body: a boolean. If true, the value in req.body will be collected and linked to the event. The track method does not collect the requests HTTP body by default.
  • request: a request object, Sqreen should automatically populate this field with the current request. When it cannot find it, this needs to be added manually

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 is overridden for the context of this event.

Block users

To block users you must implement the identify method.

Track events from the past

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

When tracking an event, using the optional timestamp parameter overrides the current server time.

const Sqreen = require('sqreen');

const event_date = new Date(2018, 3, 15, 14, 42, 0)
Sqreen.track(event.name, {
    properties: {foo: 'bar'},
    timestamp: event_date
})

Integration with Express

Sqreen provides middleware to simplify the integration with Express. Here is an example:

const Sqreen = require('sqreen');

// Register the Sqreen Express middleware in the app
app.use(Sqreen.middleware)

app.get('/path/:parameter', (req, res, next) => {
    req.sqreen.track('foobar', {
        properties: {
            prop1: 'value1',
            prop2: 'value2'
        }
    });
    // rest of the code goes here
});

Monitor events

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

Now, go to your dashboard and visit the Event Explorer to validate 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.

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.

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, the events are dropped to prevent Sqreen memory overhead growing and impacting your application's performance.