Insights as Code in Practice

We're excited to announce full support for version-controlled insight trackers in Journium. Define, review, and deploy your product intelligence exactly like you ship code—in Git, through pull requests, with automatic deployments.

The Problem: Analytics Configuration Trapped in UIs

Most analytics tools force you to configure everything through dashboards. This approach works for exploration, but breaks down when analytics become critical infrastructure.

Consider what happens when a tracker starts producing incorrect insights. Who modified it? What was the configuration before? Why did they make that change? The answers require checking with multiple people, hoping someone remembers the context, and manually reconstructing the previous state from memory.

Or shipping a feature and realizing two weeks later that nobody configured analytics for it—you've lost two weeks of critical launch period data.

These aren't edge cases. They're inevitable when analytics configuration lives in dashboards instead of version control, changes without review, and deploys independently of the features it monitors.

For teams that already treat infrastructure, testing, and observability as code, this workflow feels broken.

The Solution: Trackers as YAML in Git

Journium tracker repositories put insight definitions in your codebase:

apiVersion: journium.app/v0Beta
kind: InsightTracker
metadata:
  name: onboarding-dropoff
  displayName: Onboarding Completion Analysis
  description: Track users who start but don't complete onboarding.
spec:
  type: LLM
  trigger:
    mode: automatic
    schedule: daily
  window:
    period: last_7d
    granularity: day
  analysis:
    type: funnel
    entity: person_id
    conversionWindow: 48h
    steps:
      - event: onboarding_started
        label: Started Onboarding
      - event: profile_completed
        label: Completed Profile
      - event: team_invited
        label: Invited Team
      - event: onboarding_completed
        label: Completed Onboarding
    breakdowns:
      - property: account_type
      - property: traffic_source
  llm:
    promptTemplate: |
      Onboarding funnel (last 7 days): {{stepsSummary}}
      Biggest drop-off: {{worstStep}} ({{worstStepLoss}} users lost, {{worstStepCvr}} conversion).
      Breakdown by account type: {{breakdownSummary}}
      In 2-3 sentences: identify the most critical drop-off, suggest one hypothesis, and recommend one experiment.
    maxOutputTokens: 400

Trackers are first-class artifacts in your repository—reviewed, versioned, and deployed like application code.

How It Works

my-app/
├── .journium/
│   └── trackers/
│       ├── onboarding-dropoff.yml
│       ├── purchase-funnel.yml
│       └── feature-adoption.yml
├── src/
│   └── ... your application code
└── package.json

The Developer Experience

Real-Time Validation in Your Editor

The Journium VS Code extension validates YAML against the tracker schema as you type, suggests valid values via auto-completion, and shows inline documentation on hover. Write trackers with the same confidence you write code—invalid configurations are caught immediately, not after deployment.

spec:
  trigger:
    mode: automatic
    schedule: # ← Auto-complete suggests: hourly, daily, weekly, monthly, or cron

Review Trackers in Pull Requests

Treat analytics changes like code changes:

spec:
  trigger:
    mode: automatic
    schedule: weekly
    schedule: daily
  window:
    period: last_7d
    period: last_14d

Your team reviews the change, discusses the rationale, approves or requests modifications. Insight logic is now part of your code review process.

Rollback with Git

Tracker causing issues? Rollback is one command:

git revert abc123
git push

Trackers revert to the previous working state instantly.

CI/CD Integration

Trackers are YAML files in your repository—validate them in CI before production:

name: Validate Trackers

on: [pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: pnpm/action-setup@v4
        with:
          version: latest

      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Download tracker schemas
        run: |
          mkdir -p .journium/schemas
          curl -sf -o .journium/schemas/root.schema.json \
            https://journium.app/schemas/journium-insight-tracker.schema.json
          curl -sf -o .journium/schemas/v0Beta.schema.json \
            https://journium.app/schemas/journium-insight-tracker.v0Beta.schema.json
          curl -sf -o .journium/schemas/base.schema.json \
            https://journium.app/schemas/journium-insight-tracker.base.schema.json

      - name: Validate tracker schemas
        run: |
          pnpm add -g ajv-cli ajv-formats
          ajv validate \
            --spec=draft2020 \
            -c ajv-formats \
            -s .journium/schemas/root.schema.json \
            -r ".journium/schemas/v0Beta.schema.json" \
            -r ".journium/schemas/base.schema.json" \
            -d ".journium/trackers/*.yml"

Broken trackers fail CI and never merge. Analytics stay reliable through the same quality gates as application code.

Why This Matters

Insights Become Reviewable

Three months after launch, you discover that a critical onboarding insight tracker has been quietly misconfigured. It's been analyzing the wrong events. Nobody noticed because the change happened in a dashboard somewhere, and there's no record of who made it or why.

This scenario plays out constantly in organizations using traditional analytics tools. Analytics logic lives in dashboard configurations—hidden from view, unversioned, unreviewable. When something breaks or produces misleading results, there's no paper trail. Just a guess about what might have changed.

Version-controlled trackers eliminate this. Every tracker is a YAML file in your repository—explicit, readable, and subject to the same review process as application code.

When someone proposes changing the schedule from weekly to daily and widening the analysis window from 7 to 14 days, the change appears in a pull request. Your team discusses whether the broader window is worth the additional processing. Someone points out the tracker already struggles to complete within its time window. The change gets refined before merge. Insight logic improves through peer review, not trial-and-error in production.

Change History is Preserved

Six months ago, your purchase funnel tracker was producing reliable insights. Today, it's generating noise. What changed?

With version-controlled trackers, the answer is immediate:

git log --oneline .journium/trackers/

a7b3c1d Increase event limit for purchase-funnel tracker
f2e9d8a Add new tracker for feature-adoption analysis
c4b1a6e Update onboarding-dropoff to run daily instead of weekly

Every modification to your analytics is captured in Git history with full context—who changed what, when, the commit message, and the code review discussion. This audit trail creates institutional knowledge about why your analytics are configured the way they are.

When a new team member asks "why does this tracker only analyze 100 events?", the answer isn't lost in someone's memory or buried in Slack. It's in Git history, often with a link to the original discussion about performance tradeoffs.

Analytics Logic Lives Near Code

Here's a common pattern version-controlled trackers eliminate: Team ships a new collaboration feature Monday. Tuesday, someone files a ticket to "add analytics for the new feature." Wednesday, a PM configures a tracker in the dashboard. Thursday, you realize the tracker is misconfigured because the PM didn't know about the edge cases engineers handled during implementation.

Version-controlled trackers collapse this timeline. When you ship a feature, the insight tracker ships in the same pull request:

# PR: Add team collaboration feature

src/
  features/collaboration/
    ├── TeamInvite.tsx
    └── CollaborationProvider.tsx

.journium/trackers/
  team-collaboration-adoption.yml

The developer who built the feature writes the tracker. They know which events matter, which edge cases to consider, and what "success" looks like. That knowledge gets encoded into the tracker specification, reviewed alongside the feature code, and deployed simultaneously. No follow-up tickets. No lag between shipping features and understanding their impact.

Deployment is Automatic

Traditional analytics create a coordination problem: deploy application code through CI/CD, configure analytics through a dashboard. Two workflows operating independently, creating constant synchronization issues.

Did someone remember to update the tracker after deployment? Did the tracker configuration change while the feature was in code review? Is staging configured like production? These questions disappear with version-controlled trackers.

Push your branch—insights deploy automatically. The same Git workflow that manages application code manages analytics configuration. Trackers stay synchronized with your application because they're deployed by the same process.

Real-World Workflow

Launching a new onboarding flow:

git checkout -b feature/new-onboarding-flow

apiVersion: journium.app/v0Beta
kind: InsightTracker
metadata:
  name: onboarding-v2-analysis
  displayName: New Onboarding Flow Performance
  description: Monitor adoption and completion of the redesigned onboarding flow.
spec:
  type: LLM
  trigger:
    mode: automatic
    schedule: daily
  window:
    period: last_7d
    granularity: day
  analysis:
    type: funnel
    entity: person_id
    conversionWindow: 48h
    steps:
      - event: onboarding_v2_started
        label: Started Onboarding (v2)
      - event: onboarding_v2_step_completed
        label: Completed Step
      - event: onboarding_v2_completed
        label: Completed Onboarding (v2)
  llm:
    promptTemplate: |
      New onboarding flow (v2) performance (last 7 days): {{stepsSummary}}
      Biggest drop-off: {{worstStep}} ({{worstStepLoss}} users lost, {{worstStepCvr}} conversion).
      In 2-3 sentences: assess completion health, identify the sharpest drop-off step, and suggest one improvement.
    maxOutputTokens: 400

git merge feature/new-onboarding-flow
git push origin main

Advanced Patterns

Scheduled vs. Manual: Run some trackers continuously (mode: automatic, schedule: hourly), trigger others on-demand (mode: manual). Manual trackers are useful for exploratory analysis or expensive operations.

Custom Cron Schedules: Use cron expressions for precise timing (cron: "0 9 * * 1" for Monday 9 AM).

Event Filtering: Scope analysis to the exact user journey that matters. Funnel trackers define each step via analysis.steps[].event; adoption trackers list analysis.featureEvents. Analysis runs only over the signals you specify.

Multi-Environment: Deploy from develop branch for staging, main for production. Same workflow as application deployments.

Comparison: UI vs. Git-Based Trackers

Both approaches work. Choose the UI for quick experiments. Choose Git for production trackers.

Getting Started

Install the VS Code extension for validation and auto-completion. Add .journium/trackers/ to your repository with tracker YAML files. Link your repository in the Journium dashboard (Developers → Insight Trackers → Link Git Repository). Push to your deployment branch—Journium validates and deploys automatically.

See the tracker repositories documentation for detailed setup.

Version-controlled trackers are live. We're expanding with enhanced CI validation, tracker dependencies for composing complex analyses, Terraform provider for infrastructure management, and webhook integrations for custom workflows.

Feedback? Reach out.

The Bigger Picture

Over the past decade, software teams systematically eliminated manual configuration in favor of declarative, version-controlled definitions. Infrastructure as Code replaced manual server provisioning. Policy as Code replaced security checklists. Observability as Code replaced ad-hoc monitoring setups.

Each shift followed the same pattern: take something critical previously managed through UIs and tribal knowledge, and move it into version control where it can be reviewed, tested, and deployed like code.

Version-controlled trackers complete this arc for product analytics. Your insight definitions now live in Git, subject to the same rigorous workflow as everything else you build. When you deploy infrastructure, you review Terraform configs. When you deploy policy, you review OPA rules. When you deploy observability, you review SLO definitions. When you deploy analytics, you review tracker specifications.

The result: product intelligence that ships with your product, not weeks after it. Features and the insights that monitor them go live simultaneously. Rollbacks include analytics. Your product and your understanding of it stay synchronized, managed by the same workflow.

Ready to version-control your insights? Check out the tracker repositories documentation or link your first repository today.

Questions? Feedback? Let us know. We'd love to hear how you're using version-controlled trackers.