rudder-tracking-plans

Name: rudder-tracking-plans
Author: rudderlabs

18stars0forks

How to install rudder-tracking-plans?

rudderlabs/rudder-agent-skills/rudder-tracking-plans

$npx -y skills add rudderlabs/rudder-agent-skills --skill rudder-tracking-plans

Installs into the current project.

Summary

Creates and manages tracking plans that validate events against schema contracts. Use when creating or managing tracking plans that define which events are allowed for a source

Files · 1

View on GitHub

SKILL.md

1	# RudderStack Tracking Plans Management
2
3	This skill teaches how to assemble events into tracking plans - contracts that define which events a source can send and what properties each event must have.
4
5	## What is a Tracking Plan?
6
7	A tracking plan is a schema that:
8	- Defines which events are allowed from a source
9	- Specifies required vs optional properties for each event
10	- Enables validation at event ingestion time
11	- Provides governance over what data enters your warehouse
12
13	```
14	┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
15	│ Source │────▶│ Tracking Plan │────▶│ Destination │
16	│ (Web App SDK) │ │ (Validator) │ │ (Warehouse) │
17	└─────────────────┘ └─────────────────┘ └─────────────────┘
18	│
19	Validates events
20	against schema
21	```
22
23	## YAML Schema
24
25	### Basic Tracking Plan
26
27	```yaml
28	version: "rudder/v1"
29	kind: "tracking-plan"
30	metadata:
31	name: "tracking-plans"
32	spec:
33	name: "Web App Tracking Plan"
34	description: "Events for the main e-commerce web application"
35	events:
36	- event: "urn:rudder:event/product-viewed"
37	- event: "urn:rudder:event/product-added-to-cart"
38	- event: "urn:rudder:event/order-completed"
39	```
40
41	### Tracking Plan with Rule Overrides
42
43	Override event-level rules at the tracking plan level:
44
45	```yaml
46	version: "rudder/v1"
47	kind: "tracking-plan"
48	metadata:
49	name: "tracking-plans"
50	spec:
51	name: "Mobile App Tracking Plan"
52	description: "Events for iOS and Android apps"
53	events:
54	- event: "urn:rudder:event/product-viewed"
55	rules:
56	# Make session_id required for mobile (optional in event definition)
57	- property: "urn:rudder:property/session_id"
58	required: true
59	# Make device_id required for mobile attribution
60	- property: "urn:rudder:property/device_id"
61	required: true
62	- event: "urn:rudder:event/product-added-to-cart"
63	- event: "urn:rudder:event/order-completed"
64	```
65
66	## Rule Precedence
67
68	When the same property appears at multiple levels:
69
70	```
71	1. Tracking Plan event rules (highest priority)
72	2. Event-level rules (default)
73	3. Property definitions (validation config only)
74	```
75
76	Example: If `session_id` is optional in the event definition but required in the tracking plan, it's required for that tracking plan.
77
78	## Real-World Example
79
80	See `references/ecommerce-example.md` for a complete e-commerce example showing:
81	- Shared event catalog used by web, mobile, and kiosk apps
82	- Web App tracking plan (full funnel with page attribution)
83	- Mobile App tracking plan (device_id attribution)
84	- Kiosk tracking plan (limited event set)
85	- Environment-specific plans (production vs development)
86	- Gradual rollout patterns
87
88	## Governance Settings
89
90	When events violate the tracking plan:
91
92	```yaml
93	spec:
94	name: "Strict Tracking Plan"
95	governance:
96	# Options: block, forward, log
97	unplannedEvents: block # Reject events not in plan
98	violatingEvents: forward # Forward violations with flag
99	```
100
101	\| Setting \| Behavior \|
102	\|---------\|----------\|
103	\| `block` \| Reject event entirely \|
104	\| `forward` \| Forward event with violation metadata \|
105	\| `log` \| Allow event, log violation for review \|
106
107	## Directory Structure
108
109	```
110	tracking-plans/
111	├── web-app.yaml
112	├── mobile-app.yaml
113	├── kiosk.yaml
114	└── internal-tools.yaml
115	```
116
117	Each tracking plan in its own file for clear git history and code review.
118
119	## Workflow: Creating a New Tracking Plan
120
121	### Step 1: Identify the Source
122
123	What application/SDK will use this tracking plan?
124	- Web app (JavaScript SDK)
125	- Mobile app (iOS/Android SDK)
126	- Server-side (Node.js SDK)
127
128	### Step 2: List Required Events
129
130	Which events from your data catalog does this source need?
131
132	```
133	Web App needs:
134	✓ Product Viewed
135	✓ Product Added to Cart
136	✓ Order Completed
137	✗ App Opened (mobile only)
138	```
139
140	### Step 3: Determine Rule Overrides
141
142	For each event, what properties should be:
143	- Required for this source specifically?
144	- Optional even if required elsewhere?
145
146	### Step 4: Create the YAML
147
148	```yaml
149	version: "rudder/v1"
150	kind: "tracking-plan"
151	metadata:
152	name: "tracking-plans"
153	spec:
154	name: "Your Tracking Plan Name"
155	description: "Clear description of what source uses this"
156	events:
157	- event: "urn:rudder:event/event-name"
158	rules:
159	- property: "urn:rudder:property/property-name"
160	required: true
161	```
162
163	### Step 5: Validate and Apply
164
165	```bash
166	# Validate
167	rudder-cli validate -l ./
168
169	# Preview
170	rudder-cli apply --dry-run -l ./
171
172	# Apply
173	rudder-cli apply -l ./
174	```
175
176	### Step 6: Connect to Source
177
178	After applying, connect the tracking plan to your source:
179	- Via RudderStack UI: Sources → Select Source → Tracki

People who liked this also viewed

6 picks

Type