UTM Sentinel

Make campaign tracking rules visible before inconsistent parameters distort your reporting.

UTM Sentinel is a small Python command-line tool for people who inherit messy campaign exports. It reads a CSV, compares each row with a versioned JSON taxonomy, and writes a plain Markdown report plus a filterable findings CSV. The tool is deliberately deterministic: it does not call an AI model, a browser, or an advertising platform.

First useful command

pip install -e .
utm-sentinel examples/campaigns.csv --taxonomy examples/taxonomy.json --report report.md

The included fixture is deliberately tiny and synthetic. It has one uppercase source and an unapproved medium so the report shows the kinds of discrepancies that deserve a human review.

What it checks

Check	Why it matters
Required fields	Incomplete UTM tuples fragment attribution.
Regex patterns	Keeps naming conventions machine-readable.
Approved vocabularies	Stops paid-social, paid_social, and social becoming separate channels.
Whitespace and casing	Catches ordinary spreadsheet mistakes before upload.
Duplicate tracking tuples	Flags repeat source/medium/campaign combinations for review.

Taxonomy format

{"required":["utm_source","utm_medium","utm_campaign"],"patterns":{"utm_campaign":"[a-z0-9_-]+"},"allowed_values":{"utm_medium":["email","cpc","paid_social"]}}

Version this file beside your campaign plan. The validator can only enforce rules that your team actually declares.

Safety and scope

Do not commit real campaign exports. This tool reports data-quality issues; it does not edit your source file, deploy tracking links, or confirm that an ad platform accepted a parameter.

Development

python -m pytest

License

MIT.