feat(observability): WS4 funnel custom events → New Relic (InstantFunnel)

[mastermanas805]

What

Wires common/analyticsevent (merged in common #44) into the api so the conversion funnel (anonymous→provision→claim→paid) is recorded as a per-entity New Relic custom event (InstantFunnel), alongside the existing aggregate Prometheus counter instant_conversion_funnel_total. Closes the WS4 gap from OBSERVABILITY-AND-INTELLIGENCE-PLAN.md — the backend→NR custom-event bridge now emits at the funnel points.

Prometheus answers "how many"; the NR custom event answers "for which entity / cohort" — the KPIs anon→claimed (>2%) and claimed→paid (>20%) need a stable key (fingerprint bucket / teamId), which a counter can't carry.

Emitter construction / config

• Package-level analyticsevent.Emitter in handlers (atomic, boxed for type-stable atomic.Value), default = noop.
• Router builds it once at boot (wireAnalyticsEmitter) from ANALYTICS_BACKEND (default "noop" = inert; "newrelic" reuses the api's existing *newrelic.Application — no second NR connection).
• Fail-open: the analyticsevent Wrap swallows panics and PII-sanitizes (allowlist) before any backend sees the attrs; emit calls add no error handling that could fail the request path.
• noop-default IS the flag protection — inert in any env where NR isn't configured, so no separate feature flag is needed.

Funnel emit points wired (10; ADD, never replace the Prom counter)

Step	Site
provision	db.go / cache.go / nosql.go / vector.go / queue.go / storage.go / webhook.go — NewX anon path
claim	onboarding.go Claim
landing	onboarding.go StartLanding
paid	billing.go handleSubscriptionCharged

Enumeration: rg -F 'metrics.ConversionFunnel.WithLabelValues' → 10 sites; all 10 touched.

Attributes are PII-safe + low-cardinality: funnelStep, serviceName, tier, env, hashed fingerprint, opaque teamId. No raw email/token/connection string (allowlist backstop in the wrapper).

Observability (rule 25)

• New Prom counter instant_analytics_emit_failed_total{reason} (nil_app = NR unconfigured) via the nr failure hook.
• docs/OBSERVABILITY-FUNNEL-EVENTS.md documents the InstantFunnel event contract, NRQL starters, and the cohort='synthetic' exclusion for funnel analysis. The NR alert + dashboard tile live in the separate infra repo (no auto-apply).

Tests (test names)

• internal/handlers/analytics_test.go: TestGetAnalyticsEmitter_DefaultsToNoop, TestSetAnalyticsEmitter_NilIgnored, TestRecordFunnelEvent_EmitsFunnelEventWithStepAndAttrs, TestRecordFunnelEvent_OmitsEmptyOptionalAttrs, TestRecordFunnelEvent_EachCanonicalStep, TestRecordFunnelEvent_DoesNotEmitPII, TestFunnelAttrs_ToMap_OnlyAllowlistedKeys, TestFunnelStepsMatchCanonical
• internal/router/analytics_wiring_test.go: TestWireAnalyticsEmitter_DefaultNoop, TestWireAnalyticsEmitter_UnknownBackendDegradesToNoop, TestWireAnalyticsEmitter_NewRelicNilAppFiresFailureHook
• internal/handlers/billing_funnel_event_test.go: TestBillingWebhook_SubscriptionCharged_EmitsPaidFunnelEvent (DB-backed, real webhook path)

Gate

make gate: build + vet clean; all touched-package tests pass. The handlers -p 1 run reds only on pre-existing NATS/customer-DB environmental flakes (TestDBNew 503 = customer-DB provisioner down, TestQueue "NATS health check failed — is the NATS pod running?", etc.) — verified identical on clean origin/master with these files stashed. CI (which has those services) is authoritative.

🤖 Generated with Claude Code