Terminal
Terminal/Skill
Lays out an event taxonomy and instrumentation strategy from business goals, covering naming, properties and tracking plans.
By RudderStack
Works with
npx skills add rudderlabs/rudder-agent-skills --skill rudder-instrumentation-planningThis skill guides you through designing an instrumentation strategy - the systematic approach to deciding what events and properties to track in your application.
Poor instrumentation leads to:
Good instrumentation provides:
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: 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.
┌─────────────────────────────────────────────────────────────────────┐
│ 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
└─────────────────┘
Business Questions:
Product Questions:
Technical Questions:
## 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: _______________
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 |
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
For each event, list required context:
Product Viewed
Order Completed
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.
1. Custom Types ← Reusable validation patterns
2. Properties ← The vocabulary
3. Categories ← Organization
4. Events ← The actions (reference properties)
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
| 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 ViewedOrder CompletedFeature UsedBad:
productView (camelCase)PRODUCT_VIEWED (screaming snake)Click Product (wrong verb)| Pattern | Example | When to Use |
|---|---|---|
| snake_case | product_id | Always |
| Descriptive | customer_email | Include context |
| Specific | shipping_address | Not just "address" |
Good:
product_idorder_totalcustomer_emailBad:
productId (camelCase)id (too generic)total (ambiguous)| Pattern | Example |
|---|---|
| kebab-case | ecommerce |
| Lowercase | user-lifecycle |
See references/event-patterns.md for standard event taxonomy patterns (e-commerce funnel, user lifecycle, feature engagement, error tracking) and anti-patterns to avoid.
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"
# Validate all definitions
rudder-cli validate -l ./
# Preview changes
rudder-cli apply --dry-run -l ./
# Apply to workspace
rudder-cli apply -l ./
# Initialize RudderTyper
rudder-cli typer init
# Generate SDK
rudder-cli typer generate
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
)
)
When planning instrumentation that involves authentication or sensitive data:
.env to .gitignore - protect local development credentialsBefore finalizing your instrumentation plan:
rudder-cli validate -l ./references/event-patterns.md - Standard event taxonomy patterns and anti-patternsreferences/session-lifecycle-patterns.md - When to use identify, group, and track calls