rudder-instrumentation-debugging

Name: rudder-instrumentation-debugging
Author: rudderlabs

18stars0forks

How to install rudder-instrumentation-debugging?

rudderlabs/rudder-agent-skills/rudder-instrumentation-debugging

$npx -y skills add rudderlabs/rudder-agent-skills --skill rudder-instrumentation-debugging

Installs into the current project.

Summary

Diagnoses and fixes validation errors, schema issues, and instrumentation problems. Use when debugging validation errors, schema issues, or instrumentation problems

Files · 1

View on GitHub

SKILL.md

1	# Instrumentation Debugging
2
3	This skill teaches how to diagnose and fix common validation errors, schema issues, and instrumentation problems when working with RudderStack data catalog and tracking plans.
4
5	## Debugging Workflow
6
7	```
8	┌─────────────────┐
9	│ Error Occurs │
10	└────────┬────────┘
11	▼
12	┌─────────────────┐
13	│ Identify Type │ ← Validation? Schema? Runtime?
14	└────────┬────────┘
15	▼
16	┌─────────────────┐
17	│ Locate Source │ ← Which file? Which line?
18	└────────┬────────┘
19	▼
20	┌─────────────────┐
21	│ Understand Rule │ ← What does the validation expect?
22	└────────┬────────┘
23	▼
24	┌─────────────────┐
25	│ Fix & Validate │ ← Edit, then rudder-cli validate
26	└─────────────────┘
27	```
28
29	## Common Validation Errors
30
31	### Error: Reference Not Found
32
33	```
34	Error: data-catalog/events/product-viewed.yaml:15
35	Referenced property 'urn:rudder:property/proudct_id' not found
36	```
37
38	Cause: Typo in URN or property doesn't exist.
39
40	Fix:
41	```yaml
42	# Wrong
43	- property: "urn:rudder:property/proudct_id" # Typo!
44
45	# Right
46	- property: "urn:rudder:property/product_id"
47	```
48
49	Debug steps:
50	```bash
51	# List all properties to find correct name
52	ls data-catalog/properties/
53
54	# Search for the property
55	grep -r "product" data-catalog/properties/
56	```
57
58	### Error: Duplicate Resource Name
59
60	```
61	Error: Duplicate resource name 'Product Viewed' in kind 'event'
62	- data-catalog/events/ecommerce.yaml:5
63	- data-catalog/events/legacy.yaml:12
64	```
65
66	Cause: Same event name defined in multiple files.
67
68	Fix: Remove duplicate or rename one:
69	```bash
70	# Find duplicates
71	grep -r "name: \"Product Viewed\"" data-catalog/events/
72	```
73
74	### Error: Invalid Config for Type
75
76	```
77	Error: data-catalog/properties/price.yaml:8
78	Config 'minLength' is not valid for type 'number'
79	```
80
81	Cause: Using string config options on a number type.
82
83	Fix:
84	```yaml
85	# Wrong
86	spec:
87	name: "price"
88	type: "number"
89	config:
90	minLength: 1 # String config!
91
92	# Right
93	spec:
94	name: "price"
95	type: "number"
96	config:
97	minimum: 0 # Number config
98	```
99
100	Config options by type:
101
102	\| Type \| Valid Config \|
103	\|------\|--------------\|
104	\| `string` \| minLength, maxLength, pattern, format, enum \|
105	\| `number` \| minimum, maximum, exclusiveMinimum, exclusiveMaximum \|
106	\| `integer` \| minimum, maximum, exclusiveMinimum, exclusiveMaximum \|
107	\| `array` \| items, minItems, maxItems \|
108	\| `object` \| properties (with required flags) \|
109	\| `boolean` \| (none) \|
110
111	### Error: Circular Reference
112
113	```
114	Error: Circular reference detected in custom type 'RecursiveType'
115	RecursiveType -> NestedType -> RecursiveType
116	```
117
118	Cause: Custom type references itself directly or indirectly.
119
120	Fix: Restructure to avoid circular references:
121	```yaml
122	# Wrong: Circular
123	# RecursiveType references NestedType
124	# NestedType references RecursiveType
125
126	# Right: Flatten or use base types
127	spec:
128	name: "ParentType"
129	config:
130	properties:
131	- property: "urn:rudder:property/child_id" # Reference by ID instead
132	required: true
133	```
134
135	### Error: Invalid YAML Syntax
136
137	```
138	Error: data-catalog/events/checkout.yaml:7
139	YAML syntax error: unexpected indent
140	```
141
142	Cause: Incorrect indentation or YAML formatting.
143
144	Fix: Check indentation (use 2 spaces, not tabs):
145	```yaml
146	# Wrong
147	spec:
148	name: "Checkout Started"
149	rules: # Wrong indent!
150	- property: "..."
151
152	# Right
153	spec:
154	name: "Checkout Started"
155	rules: # Correct indent
156	- property: "..."
157	```
158
159	### Error: URN Format Invalid
160
161	```
162	Error: Invalid URN format 'property/product_id'
163	Expected: urn:rudder:<type>/<name>
164	```
165
166	Cause: Missing `urn:rudder:` prefix.
167
168	Fix:
169	```yaml
170	# Wrong
171	- property: "property/product_id"
172
173	# Right
174	- property: "urn:rudder:property/product_id"
175	```
176
177	## Dry-Run Output Analysis
178
179	```bash
180	rudder-cli apply --dry-run -l ./
181	```
182
183	### Understanding Output
184
185	```
186	Dry Run Results:
187	================
188	New [event] Checkout Started
189	Updated [property] product_id
190	Updated [tracking-plan] Web App Tracking Plan
191	Deleted [event] Legacy Event
192
193	Total: 1 new, 2 updated, 1 deleted
194	```
195
196	\| Status \| Meaning \| Action \|
197	\|--------\|---------\|--------\|
198	\| `New` \| Will create in workspace \| Verify it's intentional \|
199	\| `Updated` \| Will modify existing \| Review changes \|
200	\| `Deleted` \| Will remove from workspace \| Check if intentional! \|
201
202	### Unexpected Deletions
203
204	If you see unexpected `Deleted` entries:
205
206	Cause 1: File was accidentally removed
207	```bash
208	# Check git status
209	git status
210
211	# Restore if needed
212	git checkout -- data-catalog/events/missing-event.yaml
213	```
214
215	Cause 2: File excluded from validation path
216	```bash
217	# Ensure you're validating correct directory
218	rudder-cli apply --dry-run -l ./data-catalog/ # Might miss tracking-plans/
219	rudder-cli apply --dry-run -l ./ # Val

People who liked this also viewed

6 picks

Type

rudder-instrumentation-debugging

18stars0forks

View on GitHub

How to install rudder-instrumentation-debugging?

rudderlabs/rudder-agent-skills/rudder-instrumentation-debugging

$npx -y skills add rudderlabs/rudder-agent-skills --skill rudder-instrumentation-debugging

Installs into the current project.

Summary

Diagnoses and fixes validation errors, schema issues, and instrumentation problems. Use when debugging validation errors, schema issues, or instrumentation problems

Files · 1

View on GitHub

SKILL.md

1	# Instrumentation Debugging
2
3	This skill teaches how to diagnose and fix common validation errors, schema issues, and instrumentation problems when working with RudderStack data catalog and tracking plans.
4
5	## Debugging Workflow
6
7	```
8	┌─────────────────┐
9	│ Error Occurs │
10	└────────┬────────┘
11	▼
12	┌─────────────────┐
13	│ Identify Type │ ← Validation? Schema? Runtime?
14	└────────┬────────┘
15	▼
16	┌─────────────────┐
17	│ Locate Source │ ← Which file? Which line?
18	└────────┬────────┘
19	▼
20	┌─────────────────┐
21	│ Understand Rule │ ← What does the validation expect?
22	└────────┬────────┘
23	▼
24	┌─────────────────┐
25	│ Fix & Validate │ ← Edit, then rudder-cli validate
26	└─────────────────┘
27	```
28
29	## Common Validation Errors
30
31	### Error: Reference Not Found
32
33	```
34	Error: data-catalog/events/product-viewed.yaml:15
35	Referenced property 'urn:rudder:property/proudct_id' not found
36	```
37
38	Cause: Typo in URN or property doesn't exist.
39
40	Fix:
41	```yaml
42	# Wrong
43	- property: "urn:rudder:property/proudct_id" # Typo!
44
45	# Right
46	- property: "urn:rudder:property/product_id"
47	```
48
49	Debug steps:
50	```bash
51	# List all properties to find correct name
52	ls data-catalog/properties/
53
54	# Search for the property
55	grep -r "product" data-catalog/properties/
56	```
57
58	### Error: Duplicate Resource Name
59
60	```
61	Error: Duplicate resource name 'Product Viewed' in kind 'event'
62	- data-catalog/events/ecommerce.yaml:5
63	- data-catalog/events/legacy.yaml:12
64	```
65
66	Cause: Same event name defined in multiple files.
67
68	Fix: Remove duplicate or rename one:
69	```bash
70	# Find duplicates
71	grep -r "name: \"Product Viewed\"" data-catalog/events/
72	```
73
74	### Error: Invalid Config for Type
75
76	```
77	Error: data-catalog/properties/price.yaml:8
78	Config 'minLength' is not valid for type 'number'
79	```
80
81	Cause: Using string config options on a number type.
82
83	Fix:
84	```yaml
85	# Wrong
86	spec:
87	name: "price"
88	type: "number"
89	config:
90	minLength: 1 # String config!
91
92	# Right
93	spec:
94	name: "price"
95	type: "number"
96	config:
97	minimum: 0 # Number config
98	```
99
100	Config options by type:
101
102	\| Type \| Valid Config \|
103	\|------\|--------------\|
104	\| `string` \| minLength, maxLength, pattern, format, enum \|
105	\| `number` \| minimum, maximum, exclusiveMinimum, exclusiveMaximum \|
106	\| `integer` \| minimum, maximum, exclusiveMinimum, exclusiveMaximum \|
107	\| `array` \| items, minItems, maxItems \|
108	\| `object` \| properties (with required flags) \|
109	\| `boolean` \| (none) \|
110
111	### Error: Circular Reference
112
113	```
114	Error: Circular reference detected in custom type 'RecursiveType'
115	RecursiveType -> NestedType -> RecursiveType
116	```
117
118	Cause: Custom type references itself directly or indirectly.
119
120	Fix: Restructure to avoid circular references:
121	```yaml
122	# Wrong: Circular
123	# RecursiveType references NestedType
124	# NestedType references RecursiveType
125
126	# Right: Flatten or use base types
127	spec:
128	name: "ParentType"
129	config:
130	properties:
131	- property: "urn:rudder:property/child_id" # Reference by ID instead
132	required: true
133	```
134
135	### Error: Invalid YAML Syntax
136
137	```
138	Error: data-catalog/events/checkout.yaml:7
139	YAML syntax error: unexpected indent
140	```
141
142	Cause: Incorrect indentation or YAML formatting.
143
144	Fix: Check indentation (use 2 spaces, not tabs):
145	```yaml
146	# Wrong
147	spec:
148	name: "Checkout Started"
149	rules: # Wrong indent!
150	- property: "..."
151
152	# Right
153	spec:
154	name: "Checkout Started"
155	rules: # Correct indent
156	- property: "..."
157	```
158
159	### Error: URN Format Invalid
160
161	```
162	Error: Invalid URN format 'property/product_id'
163	Expected: urn:rudder:<type>/<name>
164	```
165
166	Cause: Missing `urn:rudder:` prefix.
167
168	Fix:
169	```yaml
170	# Wrong
171	- property: "property/product_id"
172
173	# Right
174	- property: "urn:rudder:property/product_id"
175	```
176
177	## Dry-Run Output Analysis
178
179	```bash
180	rudder-cli apply --dry-run -l ./
181	```
182
183	### Understanding Output
184
185	```
186	Dry Run Results:
187	================
188	New [event] Checkout Started
189	Updated [property] product_id
190	Updated [tracking-plan] Web App Tracking Plan
191	Deleted [event] Legacy Event
192
193	Total: 1 new, 2 updated, 1 deleted
194	```
195
196	\| Status \| Meaning \| Action \|
197	\|--------\|---------\|--------\|
198	\| `New` \| Will create in workspace \| Verify it's intentional \|
199	\| `Updated` \| Will modify existing \| Review changes \|
200	\| `Deleted` \| Will remove from workspace \| Check if intentional! \|
201
202	### Unexpected Deletions
203
204	If you see unexpected `Deleted` entries:
205
206	Cause 1: File was accidentally removed
207	```bash
208	# Check git status
209	git status
210
211	# Restore if needed
212	git checkout -- data-catalog/events/missing-event.yaml
213	```
214
215	Cause 2: File excluded from validation path
216	```bash
217	# Ensure you're validating correct directory
218	rudder-cli apply --dry-run -l ./data-catalog/ # Might miss tracking-plans/
219	rudder-cli apply --dry-run -l ./ # Val

People who liked this also viewed

6 picks

Type