Tracking Plans

Tracking plans let you proactively monitor and act on non-compliant event data coming into your RudderStack sources based on predefined plans. This can help you prevent or de-risk situations where any missing or improperly configured event data can break your downstream destinations.

Features

• Set rules for track and non-track events (identify, page, screen, and group) that you want to send to downstream destinations. You can use these rules to:
  • Define which events should pass through, including events with and without properties.
  • Specify whether a property or attribute is required and assign the data type required to pass that event.
• Use the Event Audit API to evaluate your inbound events and metadata and compare them with your tracking plans.
• With a robust versioning system, you can iteratively improve your tracking plans and have better control of your data.
• Create and manage your tracking plans in the RudderStack dashboard or programmatically using the Tracking plan API.

Create tracking plan

RudderStack provides you with the following options to create tracking plans:

From data catalog

You can create a tracking plan from scratch using the events and properties defined in the Data Catalog section:

1. Log in to the RudderStack dashboard and go to Collect > Tracking Plans option in the left sidebar.
2. Click Create tracking plan.

3. Select From data catalog on the next screen.

4. Enter a unique name and description for your tracking plan.
5. Choose the required events from the displayed list of events (populated from Data Catalog) and click Continue.

6. In the Map properties to events section, add properties (populated from Data Catalog) to map to each event by clicking the Add properties button.

7. Further, click Add button corresponding to the property you want to add. To mark the property as required, toggle on the Required option.

In addition, you can:

• Add more events to the tracking plan by clicking Add events button.
• Remove the current event by clicking the meatballs menu next to the event and selecting Remove event from tracking plan.
• Choose whether to capture the user traits in the properties, traits, or context.traits object by selecting the appropriate option from the Identity Applied dropdown (applicable for identify, group, page, and screen events).
• Choose whether to allow the unplanned properties in the event by toggling the Allow unplanned properties option.

8. Select the source(s) you want to connect to the tracking plan and click Continue.

You can connect multiple sources to a tracking plan. However, you can connect a source to only one tracking plan at a given point.

9. Configure the settings for different event types for each connected source.

10. Finally, click Create Tracking Plan.
11. (Optional) Use RudderTyper for autocomplete and linting.

Pull from source

You can create a tracking plan from an existing event data source. This option leverages the Event Audit API and Tracking plan API to import the events and properties tracked by the event data source and generates an initial plan.

Before you proceed, make sure the Event Audit API setting is turned on in your RudderStack dashboard.

Go to Settings > Workspace and click the Data Management tab. Scroll down to the Data governance section and turn on the Event Audit API toggle.

See Enable Event Audit API section for more information.

1. Log in to the RudderStack dashboard and go to Collect > Tracking Plans option in the left sidebar.
2. Click Create tracking plan.

3. Select Pull from source on the next screen.

4. Select the event stream source from which you want to import the tracked events and properties and click Continue.
5. Enter a unique name and description for your tracking plan and click Continue.
6. In the Map properties to events section, RudderStack displays the list of tracked events and associated properties for the selected event stream source. You can choose to add more properties (from Data Catalog) by clicking the Add properties button.

   

7. Click Add button corresponding to the property you want to add. To mark the property as required, toggle on the Required option.

In addition, you can:

• Delete any existing property by clicking the delete icon next to it.
• Add more events to the tracking plan by clicking the Add events button.
• Remove the current event by clicking the meatballs menu next to the event and selecting Remove event from tracking plan.
• Capture the user traits in the properties, traits, or context.traits object by selecting the appropriate option from the Identity Applied dropdown (applicable for identify, group, page, and screen events).
• Allow the unplanned properties in the event by toggling on the Allow unplanned properties option.

8. Select the source(s) you want to connect to the tracking plan and click Continue.

You can connect multiple sources to a tracking plan. However, you can connect a source to only one tracking plan at a given point.

9. Configure the settings for different event types for each connected source.

10. Finally, click Create Tracking Plan.
11. (Optional) Use RudderTyper for autocomplete and linting.

Tracking Plan API

You can also use the Tracking Plan API to create and manage your tracking plans programmatically.

View and edit tracking plans

To see all the tracking plans associated with your workspace, go to Collect > Tracking Plans. In this view, you get all the tracking plan-related details like name, description, last modified, connected sources, etc.

Further, you can click a tracking plan to view and edit the following details:

• Overview: Displays the list of events and properties associated with the tracking plan. You can edit these by clicking the Edit button.
• Sources: Displays the source(s) connected to the tracking plan. You can view the source details, edit source settings, and disconnect the source from tracking plan by clicking the meatballs menu next to the source.
• Settings: Lets you edit the name of the tracking plan or delete the tracking plan (only if not connected to any source).

Source-specific settings

You can visit the source connected to the tracking plan to see the following view in the Tracking Plans tab:

• Unlink Tracking Plan: Lets you unlink the tracking plan from your source. Alternatively, you can use the Tracking plan API to delete the source-tracking plan connection.
• Previously linked tracking plans: Lets you view the previously linked tracking plans for a source (in the last 30 days).
• Tracking plan settings: Lets you edit the tracking plan settings for each event type for the connected source. Once done, click Save Settings for the changes to take effect. The settings are explained below:
  • Drop events with unplanned event names: When toggled on, RudderStack drops all events that do not match the predefined event names in the tracking plan (only applicable for track events).
  • Drop events with unplanned event properties: When turned on, RudderStack drops all events that contain properties not matching the list of predefined properties for the specific event.
  • Drop events with other violations: When toggled on, RudderStack drops all events with violations that include Type Mismatch, Required Fields Missing, and others outlined in the Violation types section.
  • Propagate errors: When turned on, RudderStack captures the validation errors in the event’s context object and sends them downstream (user transformations, destinations), depending on your use-case. If toggled off, RudderStack drops the event containing the validation errors. It is recommended to keep this setting toggled on as it helps you assess the performance of your tracking plans.

Event structure for tracking plans

By default, RudderStack applies the tracking plan validation on events and captures them in the properties object.

If you want to instrument your events to capture the relevant information in the traits or context.traits object, make sure you select the relevant option from the Identity Applied dropdown as shown, while creating or updating the tracking plan.

This dropdown is only available for the identify, page, screen and group events:

If you’re using the Tracking Plan API, you can also see the example request in the Create Tracking Plan API for the event formatting structure.

Observability

RudderStack gives you complete visibility into the events passing through a tracking plan and details on the tracking plan violations, that is, events that do not comply with the tracking plan rules.

To see these metrics, click the Events tab of the source connected to your tracking plan.

Events ingested

This section shows the tracking plan currently linked to your source and the following details:

• Total events: Captures all events that pass through the source.
• Events validated: Number of events validated by the tracking plan.
• Events with violations: Number of events that do not comply with the tracking plan rules.
• Events dropped: Number of events dropped due to tracking plan violations.

You can see these metrics for all tracking plans connected to that source and filter them by version and time period (past one day, seven days, or 30 days).

Event flow

This section gives a graphical overview of all the events ingested per day over the specified period and the number of events with violations.

Event details

Click the Events tab to see all the event-related metrics like:

• Event name
• Count: Number of events validated by the tracking plan according to filter set in Events ingested.
• Last seen: Number of days since the last observed violation.

Click the Violations tab to see the following metrics:

• Event name
• Event type: Type of event (identify, track, group, page, or screen).

Tracking plans do not validate alias events. If you send any alias events, they are shown in this view and returned as is without validation.

• Events validated: Number of events validated by the tracking plan according to filter set in Events ingested.
• Events with violations: Number of events that did not comply with the tracking plan rules.
• Events dropped: Number of events that were not allowed to flow through.
• Last occurred: Date and time of the last observed violation.

You can also click on an event to view the violation type and individual metrics.

Click the View option for more details, like the violation description and sample payload for the violation.

Violation types

FAQ

Which RudderStack Cloud plans support the tracking plans feature?

The tracking plans feature is supported in the RudderStack Cloud Growth and Enterprise plans.

Although you can create unlimited tracking plans, you can have only five source-tracking plan connections in the RudderStack Cloud Growth plan.

To remove this restriction, upgrade to the Enterprise plan.

Which calls are supported by the tracking plans?

The tracking plans support identify, track, page, screen, and group events.

Note that the alias call is not supported.

Does RudderStack propagate the context related to any tracking plan violations?

RudderStack propagates any context related to the tracking plan violations to your destinations. You can use this context in your transformations for filtering or modifying the events before they reach the destination.

Questions? Contact us by email or on Slack