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:

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:

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

Good:

• Product Viewed
• Order Completed
• Feature Used

Bad:

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

Properties

Good:

• product_id
• order_total
• customer_email

Bad:

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

Categories

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