rudder-instrumentation-planning

name	rudder-instrumentation-planning
description	Designs event taxonomies and instrumentation strategies from business requirements. Use when designing event taxonomy from scratch or restructuring existing instrumentation strategy
allowed-tools	Bash(rudder-cli *), Read, Write, Edit

Instrumentation Planning

This skill guides you through designing an instrumentation strategy - the systematic approach to deciding what events and properties to track in your application.

Why Planning Matters

Poor instrumentation leads to:

• Data gaps - Can't answer business questions
• Data bloat - Too many events, high costs, noise
• Inconsistency - Same action tracked differently across teams
• Technical debt - Constant schema changes breaking dashboards

Good instrumentation provides:

• Complete funnel visibility - Every step from acquisition to retention
• Consistent naming - Clear conventions everyone follows
• Maintainable schema - Easy to extend, hard to break
• Actionable insights - Data that drives decisions

Choose Your Workflow

Different starting points require different approaches:

Your Situation	Recommended Skill
Building new feature, events not yet defined	rudder-design-first-instrumentation
Existing product needs instrumentation	rudder-code-first-instrumentation
Restructuring existing tracking	rudder-code-first-instrumentation
General planning guidance	Continue with this skill

Design-First vs Code-First

Design-First: Start from product requirements → define events → define properties → implement code. Best for new features where events are part of product definition.

Code-First: Start from existing code types → derive tracking plan → align with data governance. Best for existing products with domain types already defined.

This skill covers the general planning process. For workflow-specific guidance, see the specialized skills above.

The Planning Process

┌─────────────────────────────────────────────────────────────────────┐
│                     INSTRUMENTATION PLANNING                         │
└─────────────────────────────────────────────────────────────────────┘
         │
         ▼
┌─────────────────┐
│ 1. DISCOVERY    │ ← What questions do we need to answer?
└────────┬────────┘
         ▼
┌─────────────────┐
│ 2. TAXONOMY     │ ← What events and properties will answer them?
└────────┬────────┘
         ▼
┌─────────────────┐
│ 3. BUILD        │ ← Create the YAML definitions
└────────┬────────┘
         ▼
┌─────────────────┐
│ 4. ASSEMBLE     │ ← Group into tracking plans
└────────┬────────┘
         ▼
┌─────────────────┐
│ 5. INTEGRATE    │ ← Generate code, implement in apps
└─────────────────┘

Phase 1: Discovery

Questions to Ask Stakeholders

Business Questions:

• What KPIs do we track? (conversion rate, retention, revenue)
• What funnels do we analyze? (signup, checkout, onboarding)
• What experiments will we run? (A/B tests need specific events)
• What attribution do we need? (marketing channels, campaigns)

Product Questions:

• What are the key user journeys?
• What features do we want to measure adoption for?
• What errors/failures do we need to monitor?

Technical Questions:

• What platforms exist? (web, iOS, Android, server)
• What existing tracking is in place?
• What tools consume this data? (Amplitude, Mixpanel, warehouse)

Discovery Template

## Business Goals
- [ ] Primary KPIs: _______________
- [ ] Key funnels: _______________
- [ ] Attribution needs: _______________

## User Journeys to Track
1. _______________
2. _______________
3. _______________

## Platforms
- [ ] Web
- [ ] iOS
- [ ] Android
- [ ] Server

## Existing Tracking
- Current events: ___ events
- Issues with current: _______________

Phase 2: Taxonomy Design

Step 1: Define Event Categories

Group events by business domain:

Category	Purpose	Examples
user-lifecycle	Account actions	Signed Up, Logged In, Profile Updated
ecommerce	Purchase funnel	Product Viewed, Added to Cart, Order Completed
engagement	Feature usage	Feature Used, Content Viewed, Search Performed
errors	Failure tracking	Error Occurred, Checkout Failed

Step 2: Map User Journeys to Events

Example: E-Commerce Funnel

User Journey                    Events
───────────                    ──────
Browse products         →      Product Viewed
Add to cart            →      Product Added to Cart
Start checkout         →      Checkout Started
Complete purchase      →      Order Completed

Example: SaaS Onboarding

User Journey                    Events
───────────                    ──────
Create account         →      Signed Up
Verify email           →      Email Verified
Complete profile       →      Profile Completed
Use first feature      →      Feature Used (first_time: true)
Invite teammate        →      Team Member Invited

Step 3: Identify Properties

For each event, list required context:

Product Viewed

• Required: product_id, product_name, product_price, product_category
• Optional: page_url, referrer_url, session_id
• Context: How did they find it? What were they looking at?

Order Completed

• Required: order_id, order_total, products, customer_email
• Optional: discount_code, shipping_method, payment_method
• Context: What did they buy? How much? What discounts?

Step 4: Identify Shared Patterns

Look for properties used across multiple events:

Shared across all events:
- session_id
- user_id (if logged in)
- timestamp (automatic)

Shared across e-commerce events:
- product object (id, name, price, category)

Shared across Order Completed:
- address object (street, city, state, zip)

These become Custom Types.

Phase 3: Build the Data Catalog

Order of Creation

1. Custom Types    ← Reusable validation patterns
2. Properties      ← The vocabulary
3. Categories      ← Organization
4. Events          ← The actions (reference properties)

Real-World Example: E-Commerce Store

Custom Types:

# 1. ProductType - used by multiple events
version: "rudder/v1"
kind: "custom-type"
metadata:
  name: "custom-types"
spec:
  name: "ProductType"
  type: "object"
  description: "Consolidated product information"
  config:
    properties:
      - property: "urn:rudder:property/product_id"
        required: true
      - property: "urn:rudder:property/product_name"
        required: true
      - property: "urn:rudder:property/product_price"
        required: true
      - property: "urn:rudder:property/product_category"
        required: true
---
# 2. AddressType - used for shipping and billing
version: "rudder/v1"
kind: "custom-type"
metadata:
  name: "custom-types"
spec:
  name: "AddressType"
  type: "object"
  description: "US mailing address"
  config:
    properties:
      - property: "urn:rudder:property/street"
        required: true
      - property: "urn:rudder:property/city"
        required: true
      - property: "urn:rudder:property/state"
        required: true
      - property: "urn:rudder:property/zipcode"
        required: true

Properties:

# Product properties
version: "rudder/v1"
kind: "property"
metadata:
  name: "properties"
spec:
  name: "product_id"
  type: "string"
  description: "Unique product identifier"
  config:
    minLength: 1
    maxLength: 128
---
version: "rudder/v1"
kind: "property"
metadata:
  name: "properties"
spec:
  name: "product_category"
  type: "string"
  description: "Product category"
  config:
    enum:
      - "Footwear"
      - "Clothing"
      - "Accessories"
      - "Electronics"
---
# Address properties with validation
version: "rudder/v1"
kind: "property"
metadata:
  name: "properties"
spec:
  name: "zipcode"
  type: "string"
  description: "US ZIP code"
  config:
    pattern: "^[0-9]{5}(-[0-9]{4})?$"

Events:

# The e-commerce funnel
version: "rudder/v1"
kind: "event"
metadata:
  name: "events"
spec:
  name: "Product Viewed"
  description: "User viewed a product detail page"
  category: "urn:rudder:category/ecommerce"
  rules:
    - property: "urn:rudder:property/product"
      required: true
      customType: "urn:rudder:custom-type/product-type"
    - property: "urn:rudder:property/page_url"
    - property: "urn:rudder:property/referrer_url"
---
version: "rudder/v1"
kind: "event"
metadata:
  name: "events"
spec:
  name: "Product Added to Cart"
  description: "User added a product to their cart"
  category: "urn:rudder:category/ecommerce"
  rules:
    - property: "urn:rudder:property/product"
      required: true
      customType: "urn:rudder:custom-type/product-type"
    - property: "urn:rudder:property/quantity"
      required: true
    - property: "urn:rudder:property/cart_total"
---
version: "rudder/v1"
kind: "event"
metadata:
  name: "events"
spec:
  name: "Order Completed"
  description: "Customer completed a purchase"
  category: "urn:rudder:category/ecommerce"
  rules:
    - property: "urn:rudder:property/order_id"
      required: true
    - property: "urn:rudder:property/order_total"
      required: true
    - property: "urn:rudder:property/customer_email"
      required: true
    - property: "urn:rudder:property/shipping_address"
      required: true
      customType: "urn:rudder:custom-type/address-type"
    - property: "urn:rudder:property/billing_address"
      required: true
      customType: "urn:rudder:custom-type/address-type"
    - property: "urn:rudder:property/products"
      required: true

Naming Conventions

Events

Pattern	Example	When to Use
Object Action	Product Viewed	Standard user actions
Past Tense	Order Completed	Completed actions
Title Case	Product Added to Cart	Always

Good:

• Product Viewed
• Order Completed
• Feature Used

Bad:

• productView (camelCase)
• PRODUCT_VIEWED (screaming snake)
• Click Product (wrong verb)

Properties

Pattern	Example	When to Use
snake_case	product_id	Always
Descriptive	customer_email	Include context
Specific	shipping_address	Not just "address"

Good:

• product_id
• order_total
• customer_email

Bad:

• productId (camelCase)
• id (too generic)
• total (ambiguous)

Categories

Pattern	Example
kebab-case	ecommerce
Lowercase	user-lifecycle

Common Event Patterns

See references/event-patterns.md for standard event taxonomy patterns (e-commerce funnel, user lifecycle, feature engagement, error tracking) and anti-patterns to avoid.

Phase 4: Assemble Tracking Plans

Group events by source/application:

# Web App - full funnel
spec:
  name: "Web App Tracking Plan"
  events:
    - event: "urn:rudder:event/product-viewed"
    - event: "urn:rudder:event/product-added-to-cart"
    - event: "urn:rudder:event/checkout-started"
    - event: "urn:rudder:event/order-completed"

# Mobile App - simplified
spec:
  name: "Mobile App Tracking Plan"
  events:
    - event: "urn:rudder:event/product-viewed"
    - event: "urn:rudder:event/order-completed"

Phase 5: Integrate

Validate and Apply

# Validate all definitions
rudder-cli validate -l ./

# Preview changes
rudder-cli apply --dry-run -l ./

# Apply to workspace
rudder-cli apply -l ./

Generate Type-Safe Code

# Initialize RudderTyper
rudder-cli typer init

# Generate SDK
rudder-cli typer generate

Implement in Applications

Use generated code for type-safe tracking:

// Type-safe, IDE autocomplete, compile-time validation
analytics.productViewed(
    product = ProductType(
        productId = "shoes-001",
        productName = "Running Shoes",
        productPrice = 89.99,
        productCategory = ProductCategory.FOOTWEAR
    )
)

Credential Security

When planning instrumentation that involves authentication or sensitive data:

• Never track passwords or tokens - exclude sensitive fields from event properties
• Hash or anonymize PII - user emails, phone numbers should be hashed if tracked
• Use RudderStack's PII masking - configure masking rules for sensitive properties
• Store workspace tokens securely - use environment variables, never commit to git
• Add .env to .gitignore - protect local development credentials

Checklist

Before finalizing your instrumentation plan:

• All business questions can be answered with planned events
• Naming conventions are documented and consistent
• Custom types created for repeated property groups
• Required vs optional clearly defined for each property
• Categories organize events logically
• Tracking plans exist for each source/platform
• Validation passes: rudder-cli validate -l ./

References

• references/event-patterns.md - Standard event taxonomy patterns and anti-patterns
• references/session-lifecycle-patterns.md - When to use identify, group, and track calls