Track custom events

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

  • TrackSignup() to track user account creation
  • TrackAuth() to track user logins
  • Identify() and ForUser() to track user sessions

Beyond those events, you can use the Track() SDK method to define and record custom events in your app. You can use these custom events to automate your app's response to threats in a Security Automation Playbook.

Refer to Go SDK package in Github for further details.

Define your custom event

Define a custom event in the sqreen.yaml file in your application.

sqreen := sdk.FromContext(ctx)
sqreen.TrackEvent("my.event")

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.

props := sdk.EventPropertyMap{"key": "value"}
sqreen := sdk.FromContext(ctx)
sqreen.TrackEvent("my.event").WithProperties(props)

TrackEvent: This is the identifier of the event you wish to track. It is a string.

func (ctx *HTTPRequestRecord) TrackEvent(event string) *HTTPRequestEvent

WithProperties: (optional) An object with arbitrary parameters to record custom event dimensions. 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

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

  • WithUserIdentifiers(): (optional) An object that represents a user's information. The identifier must be the same as the ForUser(). Refer to "Consistently identify users" section of the SDK documentation for details. If your custom event includes WithUserIdentifiers(), then the custom event parameter overrides the Identify value for the context of the event.

func (e *HTTPRequestEvent) WithProperties(p EventPropertyMap) *HTTPRequestEvent
func (e *HTTPRequestEvent) WithTimestamp(t time.Time) *HTTPRequestEvent
func (e *HTTPRequestEvent) WithUserIdentifiers(id EventUserIdentifiersMap) *HTTPRequestEvent

Use your custom event

  1. If you want to associate your custom event with a user account, you can either pass it to every TrackEvent() call using WithUserIdentifiers(), or rely on the ForUser() 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.

  3. When Sqreen has recorded a reasonable amount of events, navigate to the Sqreen Dashboard > Playbooks to start building an automation playbook. Refer to Security Automation Playbooks documentation for more details.

Next steps