Analytics

This guide steps you through instrumenting your code with Sentry's 3rd-party analytics infrastructure.

Big Query

BigQuery is a Google data warehouse that a lot of our data calls home. This includes all our analytics data and some (not all) production data that might be of interest when joins are necessary for answering richer more complex questions. From sentry/getsentry, our data goes through reload, our ETL for BigQuery.

Amplitude

Amplitude is a product analytics tool that we use to track user behavior. We use Amplitude to track events such as when a user views a page, clicks a button, or performs a search.

Backend Analytics

Step 1: Create your Analytics Events!

Conventionally, the analytics events are stored in a file named analytics within the folder of the code it tracks. i.e.: sentry/integrations/analytics.py for the Integration analytic events and sentry/api/analytics.py for the API analytic events.

The Event classes look like this:

from __future__ import absolute_import, print_function

from sentry import analytics

class ExampleTutorialCreatedEvent(analytics.Event):
  type = 'example_tutorial.created'

   attributes = (
      analytics.Attribute('id'),
      analytics.Attribute('user_id'),
  )

class ExampleTutorialDeletedEvent(analytics.Event):
  type = 'example_tutorial.deleted'

   attributes = (
      analytics.Attribute('id'),
      analytics.Attribute('user_id'),
  )

analytics.register(ExampleTutorialCreatedEvent)
analytics.register(ExampleTutorialDeletedEvent)

Your event classes will inherit from analytics.Event as shown above. All events have a type and attributes.

• type: Describes what the Event is, and this name should be unique across all analytics event classes.

• attributes: Parameters what you would like to track, for example the user_id of the user performing the action. All attributes must be an Attribute object as shown above. Note that you cannot create an attribute named 'type'.

Finally, register your event classes so that the analytics event_manager will pick them up.

If you are creating the analytics.py file for the first time:

If you are creating a new analytics file for the first time, you will need to add an import to the package's __init__.py.

If the Event classes are defined in a file named: sentry/examples/analytics, then the class below would be defined at sentry/examples/__init__.py:

from __future__ import absolute_import

from .analytics import *  # NOQA

Here, you have your usual absolute_import but in addition you will import every class in your analytics.py add # NOQA to avoid linter complaints.

Step 2: Add it to the code you want to track

You'll be adding code in some user-facing area like an API endpoint.

from sentry import analytics

class ExampleEndpoint(Endpoint):

  def post(self, request):
    example = Example.objects.create(...)
    analytics.record(
        'example_tutorial.created',
        id=example.id,
        user_id=request.user.id,
    )
    return Response(serialize(example, request.user))

Do whatever you would normally with the endpoint, then use the analytics.record method to gather the information you want. Note that it takes input of the form:

analytics.record(
	'event_type_as_string',
	<attribute_name_0>=<value>,
		....
	<attribute_name_n>=<value>,
)

Run the tests that touch the endpoint to ensure everything is Gucci.

Step 3: Add it to ETL

To also send the analytics event in Amplitude, add the event to this file: https://github.com/getsentry/etl/blob/master/etl/operators/analytics_events_schema.py

'my_backend_event.sent': { // Needs to match the `type` field in the class you created in step 1
    'name': 'My Backend Event', // The event name in Amplitude
    'uid_field': 'target_user_id' // Optional. Field name that represents the user id of the event.
},

Note that in the future this will change so that by default, all events will go to Amplitude.

Route Based Frontend Analytics

All in-app page loads will generate analytics events by default (both Reload and Amplitude). All analytics related to page load should be handled within the route based analytics system instead of manually instruming front-end events. The default names are based on the parameterized path and are prefixed with Page View. Here is an example event name:

Page View: :OrgId :ProjectId Releases

Any field that has a : at the front is a parameterized field. The value of the field will be the value of the parameter. For example, the :OrgId field will be the value of the orgId parameter (really the slug).

Customization

Route based analytics can be customized to have different event names and parameters. For functional components, the following hooks can be used:

• useDisableRouteAnalytics: Disables route based analytics for the component.
• useRouteAnalyticsEventNames: Customizes the event name. First argument is the Reload eventKey and second argument is the Amplitude eventName.
• useRouteAnalyticsParams: Customizes the parameters.

Example:

export default function SpanDetailsContentWrapper(props: Props) {
  const {location, project,} = props;

  // customize the route analytics event we send
  useRouteAnalyticsEventNames(
    'performance_views.span_summary.view',
    'Performance Views: Span Summary page viewed'
  );
  useRouteAnalyticsParams({
    project_platforms: project ? getSelectedProjectPlatforms(location, [project]) : '',
  });

The main purpose of customizing the event names is to create more readable event names that won't change if the underlying route changes.

For class based components, the following functions can be used:

• setDisableRouteAnalytics: Disables route based analytics for the component.
• setEventNames: Customizes the event name. First argument is the Reload eventKey and second argument is the Amplitude eventName.
• setRouteAnalyticsParams: Customizes the parameters.

You will need to import both withRouteAnalytics and WithRouteAnalyticsProps. WithRouteAnalyticsProps needs to be added to the Props of the class. The functions can then accessed through the Props. withRouteAnalytics is called while exporting the class.

Example:

class Monitors extends AsyncView<Props, State> {
  componentDidMount() {
    this.props.setEventNames('monitors.page_viewed', 'Monitors: Page Viewed');
  }

For Frontend events

All front end events should come from a function generated by makeAnalyticsFunction which will type events to just the ones passed in as a generic. In Sentry, you can use the trackAdvancedAnalyticsEvent and in Getsentry there is trackGetsentryAnalytics (but it is possible to make a custom one like trackIntegrationAnalytics). These functions always send events to reload and can be configured to send events to Amplitude as well. These tie into the hook analytics:track-event-v2.

Step 1: Add the Typescript Definition

First, add the Typescript definiition of the event to an analytics event file inside the analytics directory like issueAnalyticsEvents.tsx. There are two parts of this:

1. Define the event parameters that get exported

export type ExampleTutorialEventParameters = {
  "example_tutorial.created": {
    source: string;
  };
  "example_tutorial.viewed": {
    source: string;
  };
};

2. Define the Reload to Amplitude name mapping. If the value is null, then the event will not be sent to Amplitude. This is usually only done for very high volumne events.

export const exampleTutorialEventMap: Record<
  keyof ExampleTutorialEventParameters,
  string | null
> = {
  "example_tutorial.created": "Example Tutorial Created",
  "example_tutorial.viewed": null, // don't send to Amplitude
};

Step 2: Add the Event in Code

Now, you can use the event in code using a function generated by makeAnalyticsFunction (primarily trackAdvancedAnalyticsEvent in Sentry). The function takes the following arguments:

• eventKey: This describes the key used in Sentry's own analytics system (Reload). It will map to an Amplitude name as determined in step 1.

• analyticsParams: This object will hold all the information you're interested in tracking. Generally, you always pass in an Organization object into it unless the event is not tied to a specific organization. In getsentry, you should pass the Subscription as well. Certain fields like the role and plan will be pulled out of those entities and added to the event payloads.

• options: This field allows passing the following optional fields:

  • mapValuesFn: An arbitrary function to map the parameters to new parameters
  • startSession: If true, starts an analytics session. This session can be used to construct funnels. The start of the funnel should have startSession set to true.
  • time: Optional unix timestamp.

Typing and Mapping

All events should be typed which specifies what the payload should be. We also define a mapping from the Reload event name to the Amplitude event name.

Naming Convention

Our current naming convention for Reload events is descriptor.action e.g. what we have above with example_tutorial.created and example_tutorial.deleted . You want these to be specific enough to capture the action of interest but not too specific that you have a million distinctly named events with information that could be captured in the data object. For example, if you can create your example tutorial from multiple places, fight the urge to have the source as part of your descriptor i.e. example_tutorial_onboarding.created and example_tutorial_settings.created. Your future self running analytics will thank you. Amplitude event names should be similar to the Reload event name except you should capitalize the words and use spaces instead of underscores.

getsentry

import React from "react";

import trackGetsentryAnalytics from "getsentry/utils/trackGetsentryAnalytics";

class ExampleComponent extends React.Component {
  componentDidMount() {
    trackGetsentryAnalytics("example_tutorial.created", {
      organization,
      subscription,
      source: "wakanda",
    });
  }

  render() {
    return <h1> HI! </h1>;
  }
}

sentry

All you'll actually need is to import analytics from utils and call it wherever you need. Keep in mind the effect of React lifecycles on your data. In this case, we only want to send one event when the component mounts so we place it in componentDidMount .

import React from "react";

import trackAdvancedAnalyticsEvent from "sentry/utils/analytics/trackAdvancedAnalyticsEvent";

class ExampleComponent extends React.Component {
  componentDidMount() {
    trackAdvancedAnalyticsEvent("example_tutorial.deleted", {
      organization,
      source: "wakanda",
    });
  }
  render() {
    return <h1> HI! </h1>;
  }
}

Legacy Frontend Events

Add the events to Reload

We have a repo called https://github.com/getsentry/reload. The https://github.com/getsentry/reload/blob/master/reload_app/events.py is a legacy list that specifies an optional schema for events. Newer front-end analytics events don't need to be added to this reload Schema (anything going through trackAnalyticsEventV2). file holds a list of all accepted events.

Here's an example of what that schema looks like:

'example_tutorial.created': {
	'org_id': int,
	'source': str,
	'plan': str,
},

'example_tutorial.deleted': {
	'org_id': int,
	'source': str,
},

Deploy your changes in Reload through freight.

Metrics

Track aggregrate stats with Metrics. For example, this can be used to track aggregate response codes for an endpoint.

Import the metrics library and use the metrics.inc function. The key needs to be unique.

from sentry.utils import metrics

metrics.incr(
    "codeowners.create.http_response", # needs to be unique
    sample_rate=1.0,
    tags={"status": status},
)

If you don't put a sample rate, you get 1 in 10 events. If the service is expected to have low traffic, we can start with a sample rate of 1.