Skip to content

feat(analytics): add explicit source param + 'system' default to capture/captureException #3652

@PierreBrisorgueil

Description

@PierreBrisorgueil

Problem

Today analytics.capture() accepts an optional req (whose posthogContext.source is merged into event properties), and analyticsService.captureException(err, ctx) accepts {distinctId, requestId}. Neither has an explicit source parameter.

Consequence:

  • Server-side emissions with no req (scrap_run_completed from worker callback, compute_consumed from historys, subscription_changed from Stripe webhook, cron tasks) end up with source = null in PostHog.
  • Validated 2026-05-11: 100% of Vue events have null source (expected), but all 3 Node events from a manual scrap run also had null source — worker-callback and stripe-webhook emissions can't be attributed.

Spec

Extend capture({distinctId, event, properties, req, source}) and captureException(err, {distinctId, requestId, source, properties}) to accept an explicit source override. Precedence: explicit source > properties.source > req.posthogContext.source > 'system' default.

Acceptance criteria

  • capture() adds optional source param to JSDoc + destructure
  • captureException() accepts ctx.source and ctx.properties
  • Default 'system' baked into the merged defaults of both helpers
  • Unit tests cover the 4-tier precedence
  • Coverage thresholds unchanged
  • README convention table updated

Follow-up after merge:

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions