Tracking Golden Path Adoption

A golden path only pays off if teams actually take it. Building a paved road that 10% of new services use is a signal the road leads somewhere people do not want to go — but you only learn that if you measure adoption. This how-to instruments golden-path usage, defines an adoption metric, and surfaces the trend so you can tell a popular path from an ignored one. It extends Developer Experience Metrics within Developer Experience & Self-Service Platforms.

Prerequisites

  • Backstage 1.20+ with the scaffolder in use and a catalog of services.
  • Golden paths implemented as scaffolder templates, per Golden Paths & Paved Roads.
  • A way to record scaffolder task events — the scaffolder’s task history or an analytics sink.
  • Agreement on what “adoption” means: share of new services created from a template versus by hand.
Prerequisites for adoption tracking A working scaffolder, templated golden paths, task-event recording, and an adoption definition enable measurement. working scaffolder templated paths task-event recording adoption defined Measured uptake per path
Define the denominator before the numerator — adoption is templated-creations over all new services, so you must count both.

Exact Configuration

  1. Record a scaffolder event on each template run so usage is countable.

    // capture template usage from scaffolder task completion
// Requires @backstage/plugin-scaffolder-backend >= 1.22
scaffolder.onTaskComplete(async task => {
  await analytics.emit({
    type: 'scaffolder.task',
    template: task.spec.templateInfo?.entityRef,
    user: task.createdBy,
    at: task.completedAt,
  });
});

  2. Define the adoption metric as templated creations over total new services in a window.

    -- adoption = templated / all new services, last 90 days
SELECT
  COUNT(*) FILTER (WHERE created_via_template) AS templated,
  COUNT(*)                                     AS total,
  ROUND(100.0 * COUNT(*) FILTER (WHERE created_via_template) / COUNT(*), 1) AS adoption_pct
FROM services WHERE created_at > now() - interval '90 days';

  3. Break it down per path so you can see which templates land and which are ignored.

    SELECT template, COUNT(*) AS runs
FROM scaffolder_events WHERE at > now() - interval '90 days'
GROUP BY template ORDER BY runs DESC;
From event to adoption metric Scaffolder task events are recorded, aggregated into a templated-versus-total ratio, and broken down per path. task event per run aggregate templated / total per-path breakdown adoption % trend
The per-path breakdown is where the insight lives — one blended number hides that path A is thriving while path B is dead.

Validation

# Requires psql or your analytics query tool
# 1. Events are being recorded
psql -c "SELECT COUNT(*) FROM scaffolder_events WHERE at > now() - interval '7 days';"
# Expected: > 0 for an active org

# 2. The adoption metric computes and is sane
psql -c "SELECT adoption_pct FROM golden_path_adoption;"
# Expected: a percentage between 0 and 100, not null

# 3. Per-path breakdown distinguishes winners from losers
psql -c "SELECT template, runs FROM path_usage ORDER BY runs;"
# Expected: a spread — some paths high, some near zero
Adoption tracking validation checks Events record, the adoption metric is sane, and the per-path breakdown shows a spread. Events record count > 0 Metric sane 0–100% Spread visible winners vs dead
A spread across paths is the healthy signal — if every path reads the same, your instrumentation is probably not distinguishing them.

Edge Cases & Troubleshooting

Symptom Root Cause Resolution
Adoption looks 100% Only templated creations are counted Count hand-made services in the denominator too
Adoption looks 0% Events not recorded Confirm the task-complete hook fires and writes
A path shows huge numbers Test or CI runs counted Exclude non-production and test runs
Trend jumps around Window too short Use a rolling 90-day window to smooth noise
Can’t tell why a path is ignored Metric without qualitative input Pair the number with a short user survey
Adoption tracking pitfalls by class Wrong denominators and unrecorded events are counting issues; noisy trends and missing context are interpretation issues. Counting wrong denominator events missed → count all + verify hook Interpretation noisy trend no context → rolling window + survey
Excluding CI and test runs matters — counting them inflates a path's numbers and hides that real teams are avoiding it.

Frequently Asked Questions

Is high adoption always good?

Not if it is coerced. Adoption driven by a mandate can hide a painful path that teams use only because they must. Read adoption alongside satisfaction and time-to-first-deploy: a golden path is working when teams choose it and are glad they did, not merely when a policy forces the number up.

What do I do with a path nobody uses?

Treat low adoption as a discovery signal, not a failure to punish. Interview a couple of teams that went their own way — usually the path is missing a step, too rigid, or solves a problem they do not have. Fix it or retire it; a paved road nobody drives on is maintenance cost with no return.