Rudder Design First Instrumentation

Design-First Instrumentation

This skill guides instrumentation planning for new features where events are defined during product definition, before implementation begins.

When to Use This Skill

The Design-First Workflow

┌─────────────────────────────────────────────────────────────────────┐
│                    DESIGN-FIRST INSTRUMENTATION                      │
└─────────────────────────────────────────────────────────────────────┘
         │
         ▼
┌─────────────────┐
│ 1. REQUIREMENTS │ ← What questions must the data answer?
└────────┬────────┘
         ▼
┌─────────────────┐
│ 2. EVENT DESIGN │ ← Define events (names only, no properties yet)
└────────┬────────┘
         ▼
┌─────────────────┐
│ 3. HUMAN        │ ← PM/Eng review: Are these the right events?
│    CHECKPOINT   │
└────────┬────────┘
         ▼
┌─────────────────┐
│ 4. PROPERTY     │ ← Define properties for approved events
│    DESIGN       │
└────────┬────────┘
         ▼
┌─────────────────┐
│ 5. BUILD YAML   │ ← Create tracking plan definitions
└────────┬────────┘
         ▼
┌─────────────────┐
│ 6. IMPLEMENT    │ ← Code the feature with instrumentation
└─────────────────┘

Phase 1: Requirements Gathering

Start with the questions the data must answer:

Questions Template

## Feature: [Feature Name]

### Business Questions
- [ ] What is the conversion rate through this feature?
- [ ] Where do users drop off?
- [ ] How long does it take users to complete the flow?
- [ ] What variations do users prefer?

### Success Metrics
- Primary: _______________
- Secondary: _______________

### Funnel Stages
1. Entry point: _______________
2. Key action: _______________
3. Completion: _______________

### Stakeholders
- PM: _______________
- Engineering: _______________
- Data/Analytics: _______________

Phase 2: Event Design (Names Only)

Define events as user stories or behavioral descriptions first — no properties yet.

Event Description Format

Use clear, behavioral language:

## Events for [Feature Name]

### Event: Feature Opened
- **When:** User opens the feature for the first time in a session
- **Why track:** Measures feature discovery and initial engagement
- **Funnel position:** Entry

### Event: Configuration Started
- **When:** User begins configuring the feature
- **Why track:** Measures intent to use feature
- **Funnel position:** Middle

### Event: Configuration Completed
- **When:** User successfully completes configuration
- **Why track:** Measures successful adoption
- **Funnel position:** Completion

### Event: Configuration Failed
- **When:** User encounters an error during configuration
- **Why track:** Identifies friction points
- **Funnel position:** Error state

Naming Convention

Phase 3: Human Checkpoint

Critical: Before defining properties, get alignment on events.

Review Checklist

• [ ] Do these events answer all the business questions?
• [ ] Is the funnel complete (entry → middle → completion)?
• [ ] Are error states captured?
• [ ] Are there redundant events that can be consolidated?
• [ ] Do event names follow conventions?

Approval Gate

## Event Review Sign-Off

Feature: _______________
Date: _______________

Approved Events:
- [ ] Event 1: _______________
- [ ] Event 2: _______________
- [ ] Event 3: _______________

Rejected/Deferred:
- [ ] _______________

Approved by:
- PM: _______________
- Engineering: _______________

Phase 4: Property Design

After events are approved, define properties for each.

Property Design Process

For each event, ask:

1. What context is needed to answer the business questions? 2. What attributes describe this action? 3. What will we group/filter by in dashboards?

Property Template

## Event: Audience Created

### Required Properties
| Property | Type | Description | Example |
|----------|------|-------------|---------|
| audience_id | string | Unique identifier | "aud_123" |
| audience_name | string | User-provided name | "High Value Users" |
| condition_count | integer | Number of conditions | 3 |

### Optional Properties
| Property | Type | Description | Example |
|----------|------|-------------|---------|
| template_used | string | If created from template | "ecommerce-buyers" |
| creation_method | string | How it was created | "wizard" \| "manual" |

### Context (Auto-included)
- workspace_id (from session context)
- user_id (from identify)

Identify Shared Patterns

Look for properties used across multiple events — these become custom types:

## Shared Patterns Identified

### AudienceType (used by: Created, Updated, Deleted)
- audience_id
- audience_name
- audience_type

### ConditionType (used by: Created, Updated)
- condition_id
- condition_type
- condition_operator

Phase 5: Build YAML Definitions

Convert approved designs to tracking plan YAML.

Order of Creation

1. Custom Types    ← Reusable patterns identified in Phase 4
2. Properties      ← Individual property definitions
3. Categories      ← Organize events by feature/domain
4. Events          ← Reference properties and custom types
5. Tracking Plan   ← Bundle events for the source

Example: Custom Type

version: "rudder/v1"
kind: "custom-type"
metadata:
  name: "custom-types"
spec:
  name: "AudienceType"
  type: "object"
  description: "Core audience information"
  config:
    properties:
      - property: "urn:rudder:property/audience_id"
        required: true
      - property: "urn:rudder:property/audience_name"
        required: true
      - property: "urn:rudder:property/audience_type"
        required: true

Example: Event

version: "rudder/v1"
kind: "event"
metadata:
  name: "events"
spec:
  name: "Audience Created"
  description: "User successfully created a new audience"
  category: "urn:rudder:category/audiences"
  rules:
    - property: "urn:rudder:property/audience"
      required: true
      customType: "urn:rudder:custom-type/audience-type"
    - property: "urn:rudder:property/condition_count"
      required: true
    - property: "urn:rudder:property/template_used"
    - property: "urn:rudder:property/creation_method"

Validate and Apply

# Validate definitions
rudder-cli validate -l ./

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

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

Phase 6: Implementation

With tracking plan applied, implement the feature with instrumentation.

Implementation Checklist

• [ ] Tracking plan applied to workspace
• [ ] Events documented for developers
• [ ] Instrumentation added at correct points in code
• [ ] Context middleware configured (workspace_id)
• [ ] Tested in dev environment
• [ ] Verified events reach destination

Code Pattern

// Feature implementation with instrumentation
async function createAudience(config: AudienceConfig): Promise<Audience> {
  const audience = await audienceService.create(config);

  // Instrumentation
  analytics.track('Audience Created', {
    audience_id: audience.id,
    audience_name: audience.name,
    audience_type: audience.type,
    condition_count: config.conditions.length,
    template_used: config.templateId || null,
    creation_method: config.method,
  });

  return audience;
}

Collaboration Patterns

PM-Led Event Design

PM writes event descriptions (Phase 2)
    ↓
Engineering reviews for feasibility
    ↓
Joint checkpoint (Phase 3)
    ↓
Engineering leads property design (Phase 4)
    ↓
PM validates properties answer questions
    ↓
Engineering implements

Engineering-Led with PM Input

Engineering drafts events based on feature spec
    ↓
PM reviews for analytics completeness
    ↓
Joint refinement
    ↓
Engineering completes properties + implementation

Real-World Examples

For complete end-to-end examples including RudderStack Audiences and Transformations features, see references/real-world-examples.md.

---

Common Mistakes

Checklist

Before implementation:

• [ ] Business questions documented
• [ ] Events designed with behavioral descriptions
• [ ] Human checkpoint completed (events approved)
• [ ] Properties designed for each event
• [ ] Shared patterns extracted as custom types
• [ ] YAML definitions created
• [ ] rudder-cli validate passes
• [ ] Tracking plan applied to dev workspace
• [ ] Implementation plan includes instrumentation points

Real-World Design-First Instrumentation Examples

These examples demonstrate the full design-first workflow applied to RudderStack features.

Example 1: RudderStack Audiences Feature

Phase 1: Requirements

## Feature: Audiences (Data Graph)

### Business Questions
- How many customers are creating audiences?
- What's the completion rate of audience creation?
- Which condition types are most used?
- Where do users drop off in the audience builder?

### Success Metrics
- Primary: Audience creation completion rate
- Secondary: Average conditions per audience

### Funnel Stages
1. Entry: User opens Audiences section
2. Start: User begins creating an audience
3. Configure: User adds conditions
4. Complete: User saves the audience

Phase 2: Event Design

## Events for Audiences

### Event: Audiences Section Viewed
- **When:** User navigates to Audiences in the web app
- **Why track:** Measures feature discovery
- **Funnel position:** Entry

### Event: Audience Creation Started
- **When:** User clicks "Create Audience" or starts from template
- **Why track:** Measures intent
- **Funnel position:** Start

### Event: Audience Condition Added
- **When:** User adds a condition to the audience builder
- **Why track:** Measures engagement depth
- **Funnel position:** Configure

### Event: Audience Created
- **When:** User successfully saves the audience
- **Why track:** Measures completion
- **Funnel position:** Complete

### Event: Audience Creation Failed
- **When:** Save fails due to validation or API error
- **Why track:** Identifies friction
- **Funnel position:** Error

Phase 4: Properties with Domain Types

The RudderStack codebase has existing types. Align properties with them:

// Existing code types
enum ConditionGroupType {
  AND = 'and',
  OR = 'or',
  AUDIENCE = 'audience',  // Audience within audience
}

enum AudienceStatus {
  DRAFT = 'draft',
  ACTIVE = 'active',
  ARCHIVED = 'archived',
}

Properties should match these exact values:

# Property using code's enum values
version: "rudder/v1"
kind: "property"
metadata:
  name: "properties"
spec:
  name: "condition_group_type"
  type: "string"
  description: "Type of condition group in audience builder"
  config:
    enum:
      - "and"       # Match code exactly
      - "or"
      - "audience"

Phase 5: Complete YAML

# events/audiences.yaml
version: "rudder/v1"
kind: "event"
metadata:
  name: "events"
spec:
  name: "Audience Created"
  description: "User successfully created a new audience"
  category: "urn:rudder:category/audiences"
  rules:
    - property: "urn:rudder:property/audience_id"
      required: true
    - property: "urn:rudder:property/audience_name"
      required: true
    - property: "urn:rudder:property/condition_count"
      required: true
    - property: "urn:rudder:property/condition_group_type"
      required: true
    - property: "urn:rudder:property/template_id"
    - property: "urn:rudder:property/creation_method"
---
version: "rudder/v1"
kind: "event"
metadata:
  name: "events"
spec:
  name: "Audience Creation Failed"
  description: "Audience creation failed due to error"
  category: "urn:rudder:category/audiences"
  rules:
    - property: "urn:rudder:property/error_code"
      required: true
    - property: "urn:rudder:property/error_message"
      required: true
    - property: "urn:rudder:property/audience_name"
    - property: "urn:rudder:property/condition_count"

---

Example 2: Transformations Feature

Event Design for Transformations

## Events for Transformations

### Event: Transformation Created
- **When:** User creates a new transformation
- **Why track:** Measures feature adoption
- **Properties needed:** transformation_id, language, template_type

### Event: Transformation Tested
- **When:** User runs test on transformation
- **Why track:** Measures iteration behavior
- **Properties needed:** transformation_id, test_result, execution_time_ms

### Event: Transformation Published
- **When:** User publishes transformation to production
- **Why track:** Measures completion of workflow
- **Properties needed:** transformation_id, version, connected_destination_count

Aligning with Code Types

// From the codebase
type TransformationLanguage = 'javascript' | 'python';

interface TransformationTestResult {
  success: boolean;
  output?: object;
  error?: string;
  executionTimeMs: number;
}

Properties should use these exact shapes:

version: "rudder/v1"
kind: "property"
metadata:
  name: "properties"
spec:
  name: "transformation_language"
  type: "string"
  description: "Programming language of the transformation"
  config:
    enum:
      - "javascript"
      - "python"
---
version: "rudder/v1"
kind: "property"
metadata:
  name: "properties"
spec:
  name: "test_result"
  type: "string"
  description: "Result of transformation test"
  config:
    enum:
      - "success"
      - "failure"
      - "timeout"