Segment Tracking & Governance
Build a scalable, maintainable tracking implementation with proper governance. This guide covers event dictionaries, environment management, spec reviews, and common pitfalls.
Why This Matters
Poor tracking governance leads to data debt: inconsistent event names, missing properties, broken dashboards, and analytics teams spending 60%+ of their time cleaning data instead of generating insights. A well-governed tracking plan reduces data quality issues by 80% and cuts onboarding time for new engineers by half.
Event & Property Dictionary
Your event dictionary is the single source of truth. Every tracked event must be documented before implementation. Here's the structure:
| Field | Type | Description |
|---|---|---|
| event_name | string | Snake_case, verb_noun format (e.g., dashboard_created) |
| category | enum | lifecycle | engagement | conversion | system |
| description | string | When this event fires and what it represents |
| properties | object[] | Array of property definitions with name, type, required flag |
| owner | string | Team or person responsible for this event |
| destinations | string[] | Which Segment destinations receive this event |
Example Event Definition
{
"event_name": "dashboard_created",
"category": "engagement",
"description": "Fires when user successfully creates a new dashboard",
"properties": [
{ "name": "dashboard_id", "type": "string", "required": true },
{ "name": "template_used", "type": "string", "required": false },
{ "name": "widget_count", "type": "integer", "required": true },
{ "name": "creation_method", "type": "enum", "values": ["scratch", "template", "duplicate"], "required": true }
],
"owner": "product-analytics",
"destinations": ["amplitude", "bigquery", "intercom"]
}Environment Management (Prod vs Stage)
Segment supports multiple write keys for environment separation. The goal: never pollute production data with test events.
Production
- • Write key:
prod_xxx - • Real user data only
- • All destinations enabled
- • Strict schema enforcement
- • Violations logged and alerted
Staging / Development
- • Write key:
stage_xxx - • Test and QA data
- • Limited destinations (dev warehouse only)
- • Schema validation in warning mode
- • Safe for experimentation
Environment Configuration
// lib/analytics/config.ts
const SEGMENT_KEYS = {
production: process.env.SEGMENT_WRITE_KEY_PROD,
staging: process.env.SEGMENT_WRITE_KEY_STAGE,
development: process.env.SEGMENT_WRITE_KEY_DEV,
} as const;
export function getSegmentWriteKey(): string {
const env = process.env.NODE_ENV;
const vercelEnv = process.env.VERCEL_ENV;
if (vercelEnv === 'production') return SEGMENT_KEYS.production!;
if (vercelEnv === 'preview') return SEGMENT_KEYS.staging!;
return SEGMENT_KEYS.development!;
}Spec Review Workflow
Every new event or property change should go through review. This prevents naming collisions, ensures consistency, and maintains data quality.
Propose Event in Tracking Plan
Add new event to your tracking plan document (Notion, Confluence, or YAML file in repo). Include all required fields from the dictionary schema.
Review Checklist
Reviewer checks: naming convention compliance, property completeness, no duplicate events, correct category assignment, destination configuration.
Add to Segment Protocol Schema
Once approved, add the event to your Segment Protocols tracking plan. This enables schema enforcement and violation alerts.
Implement and QA in Staging
Implement the tracking call, verify in staging Segment debugger, check property values are populating correctly.
Merge and Monitor
Deploy to production, monitor Segment debugger for first events, verify data flows to all configured destinations.
Common Failure Modes
Inconsistent Naming
DashboardCreated vs dashboard_created vs dashboard-created
Fix: Enforce snake_case with linting. Add pre-commit hooks that validate event names.
Missing Required Properties
Events fire without critical context (user_id, timestamp, object_id).
Fix: Use typed wrappers that require properties. Enable Segment Protocol violations.
Test Data in Production
Developer forgets to switch write key, polluting prod with test events.
Fix: Environment-based configuration (not manual). CI checks for hardcoded keys.
Property Type Drift
Same property sent as string sometimes, number other times ("5" vs 5).
Fix: TypeScript types for all events. Runtime validation before track calls.
Orphaned Events
Events that fire but no one uses—cluttering dashboards and costing storage.
Fix: Quarterly audit. Add "last_used" metadata. Archive events with no queries for 90 days.