Create Tracking Plans using Rudder CLI Alpha

This guide shows you how to define and create Tracking Plans in your Data Catalog using Rudder CLI.

Prerequisites

Before creating a Tracking Plan, ensure you have:

1. Rudder CLI tool installed and authenticated
2. Events and properties defined in your Data Catalog project
3. Optional custom types created for validation

Define Tracking Plans

Using your preferred text editor, create a YAML file in your Data Catalog project and add the below content:

Basic structure

You can define Tracking Plans in YAML files with the kind: tp specification.

version: rudder/0.1
kind: tp
metadata:
  name: mytrackingplan
spec:
  id: mytrackingplan
  display_name: "Product Tracking Plan"
  description: "Contains all the events and properties for the Product Tracking Plan."
  rules:
    - type: event_rule
      id: product_viewed_rule
      event:
        $ref: "#/events/myeventgroup/product_viewed"
      allow_unplanned: false
      properties:
        - $ref: "#/properties/mypropertygroup/product_sku"
          required: true

Each Tracking Plan definition requires:

• A unique identifier (id)
• A display name (display_name)
• A description (description)
• Rules (rules) that reference events and their properties

See Data Catalog YAML Reference for the detailed YAML spec containing Tracking Plan definitions.

Event rules

Event rules define which events to track and their associated properties. Each rule requires:

• A unique rule identifier (id)
• A reference to the event (event.$ref)
• Property references with validation requirements
• Optional allow_unplanned flag to control unplanned event tracking

rules:
  - type: event_rule
    id: product_viewed_rule
    event:
      $ref: "#/events/myeventgroup/product_viewed"
    allow_unplanned: false
    properties:
      - $ref: "#/properties/mypropertygroup/product_sku"
        required: true
      - $ref: "#/properties/mypropertygroup/category"
        required: false

Example Tracking Plans

The following examples show how to define Tracking Plans for different use cases:

version: rudder/0.1
kind: tp
metadata:
  name: ecommerce_tracking
spec:
  id: ecommerce_tracking
  display_name: "Ecommerce Tracking"
  description: "Tracking Plan for ecommerce events"
  rules:
    - type: event_rule
      id: product_viewed_rule
      event:
        $ref: "#/events/ecommerce/product_viewed"
      properties:
        - $ref: "#/properties/product/sku"
          required: true
        - $ref: "#/properties/product/name"
          required: true
        - $ref: "#/properties/product/price"
          required: true
        - $ref: "#/properties/product/category"
          required: false

version: rudder/0.1
kind: tp
metadata:
  name: user_auth_tracking
spec:
  id: user_auth_tracking
  display_name: "User Authentication Tracking"
  description: "Tracking Plan for user authentication events"
  rules:
    - type: event_rule
      id: user_registered_rule
      event:
        $ref: "#/events/auth/user_registered"
      properties:
        - $ref: "#/properties/user/email"
          required: true
        - $ref: "#/properties/user/signup_method"
          required: true
        - $ref: "#/properties/user/referral_source"
          required: false

Validate and deploy Tracking Plans

Before deploying your Tracking Plans to the workspace, validate them to ensure they follow the correct structure and meet your requirements.

Validate Tracking Plans

Run the following command to validate your Tracking Plan definitions:

rudder-cli tp validate -l ~/tutorial-catalog

The command checks your Tracking Plan definitions for:

• Required fields and correct structure
• Valid event and property references
• Unique identifiers across your catalog
• Proper YAML syntax

If validation succeeds, the command returns no output. If it finds any issues, it displays specific error messages to help you fix them.

Deploy Tracking Plans

After validating your Tracking Plans, deploy them to your RudderStack workspace:

1. Review the changes before deploying:

rudder-cli tp apply -l ~/tutorial-catalog --dry-run

2. Deploy the validated Tracking Plans:

rudder-cli tp apply -l ~/tutorial-catalog

The above command:

• Creates new Tracking Plans in your workspace
• Updates existing plans if you’ve modified them
• Reports the status of each operation
• Requires confirmation before making changes (unless you use --confirm=false)

See the End-to-end Walkthrough for steps on validating and deploying Tracking Plans along with other Data Catalog resources.

Best practices

Follow these best practices when defining Tracking Plans:

• Organization

  • Group related events
  • Use clear rule IDs
  • Maintain consistent naming

• Properties

  • Mark critical properties as required
  • Document property purposes
  • Use appropriate validation

• Validation

  • Test all rules
  • Verify references
  • Check property constraints

Next steps

• Update your Tracking Plan with new events, properties, and validation rules
• Set up GitHub Actions for automated Tracking Plan management

Questions? Contact us by email or on Slack