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: Php<?php sqreen\track(event.name); ?> Of course, this is a basic version and our SDK supports additional optional parameters, such as properties: Php<?php sqreen\track(event.name, ['properties' => ['foo' => 'bar']]); ?> 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¶ Php<?php 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 who 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 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 Sqreen.track is provided with a user_identifiers value, 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. 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. The options object accepts an optional parameter timestamp, expecting a date object. Setting this parameter will override the current server time. Php<?php $event_date = new DateTime('2018-03-15T14:42:00+01:00'); sqreen\track(event.name, [ 'properties' => ['foo' => 'bar'], 'timestamp' => $event_date ]); ?> 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.