Skip to content

armgit / spree

Public Imported from GitHub
0

Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.

16.6 KB
Raw Blame

OpenTelemetry Instrumentation

Status: In Progress — Phases 1–3 implemented 2026-08-12 (core notifications, spree_opentelemetry gem, telemetry docs page); remaining: fast-follow spans, spree-starter Gemfile mention, collector smoke test Target: Spree 6.0 Depends on: 6.0-service-workflows.md (workflow step instrumentation is the backbone) Author: Damian Legawiec (design driven with Claude) Last updated: 2026-08-12

Summary

Enterprise buyers ask whether Spree supports OpenTelemetry the way Medusa, Saleor and Vendure do, and today the answer is no — there is zero tracing, metrics or APM code in any gem. This plan closes that gap with a two-layer design: core emits a rich, documented ActiveSupport::Notifications surface (and takes no OpenTelemetry dependency), and a new optional spree_opentelemetry gem boots the OpenTelemetry SDK from standard OTEL_* environment variables, installs the Rails auto-instrumentation suite, and translates Spree's notifications into properly-attributed spans. The result matches the competitor bar: HTTP → workflow → step → gateway/carrier call as one distributed trace, configured the same way an SRE configures any other OpenTelemetry service.

Ruby's OpenTelemetry implementation has stable traces but an experimental metrics SDK and logs SDK, so this plan is traces-first; metrics arrive via the collector (spanmetrics) now and via the metrics SDK when it stabilizes.

Key Decisions (do not deviate without discussion)

  • Packaging (2026-08-12): new top-level optional engine spree/opentelemetry, gem name spree_opentelemetry, beside core/api/emails. Not under spree/providers/ (that shelf means commerce providers with an Integration credential surface) and not an optional require inside spree_core (core's gemspec could not declare the OpenTelemetry dependencies, pushing version drift onto merchants).
  • Activation (2026-08-12): env vars only, Saleor-style. Gem in the Gemfile + standard OTEL_* env vars = traces flow; without an exporter endpoint the SDK stays dormant, and OTEL_SDK_DISABLED=true is the kill switch. No mandatory host initializer. Accepted trade-off: activation via environment can surprise — mitigated by honoring OTEL_SDK_DISABLED and a boot-time log line stating telemetry is active and where it exports.
  • First-cut span scope (2026-08-12): the commerce core four — workflows (with external_step/outcome), events dispatch, webhook delivery, and the payment gateway boundary. These cover what enterprise deals actually ask about (checkout traces, payment latency, webhook reliability); Rack/Active Record/Active Job/Net::HTTP spans come free from auto-instrumentation. Provider base classes (delivery rates, tax, fulfillment), Meilisearch, imports/exports and OIDC are a fast-follow (see Migration Path), not the first cut.
  • Metrics posture (2026-08-12): traces only in 6.0. RED metrics (rate/errors/duration per endpoint, workflow, gateway) are derived from spans via the collector's spanmetrics connector and documented as such; no experimental Ruby metrics SDK ships. Accepted trade-off: no custom business counters (orders placed, payment failures) until the metrics SDK stabilizes — revisit in 6.1.
  • Core never depends on OpenTelemetry gems. Spree's instrumentation contract is ActiveSupport::Notifications — the Rails-native bus that any APM (Scout, Datadog, AppSignal) can also consume. The OpenTelemetry translation lives entirely in the optional gem. This mirrors how Rails itself is instrumented and keeps core dependency-free.
  • Traces first. Only the trace signal ships in 6.0. The Ruby metrics and logs SDKs are 0.x/experimental; RED metrics are derived in the collector (spanmetrics connector) and documented as such. Log correlation ships as trace/span IDs injected into Rails log tags, exported by the host's existing log pipeline — never the experimental logs SDK.
  • Telemetry is deployment configuration, never store data. Standard OTEL_* environment variables (OTEL_SERVICE_NAME, OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_TRACES_SAMPLER, OTEL_SDK_DISABLED) configure everything, exactly like Saleor. No Spree::Config preference, no store preference, no admin UI. A SpreeOpenTelemetry.configure block exists only for code-level needs (extra instrumentations, resource attributes, custom samplers).
  • No PII in span attributes — ever. Attributes carry prefixed IDs (spree.order.id = "order_86Rf07xd4z"), workflow/step names, gateway action names, HTTP metadata. Never event payloads, customer emails, addresses, credentials, or webhook bodies. Any dynamic value passes through the same ActiveSupport::ParameterFilter that Spree::EventLogSubscriber already uses (filter_parameters + Spree's additions in engine.rb).
  • external_step self-identifies in the notification payload (external: true on step.spree_workflow). One payload key marks all 11 declared gateway/carrier boundaries as CLIENT spans; new external_step call sites get this for free.
  • Workflow failures must mark spans errored. FailureSignal and Halted inherit Exception (deliberately, so a plain rescue can't swallow them), and a failure Result is detected after the instrumented block returns. The step instrumentation writes an outcome payload key inside the block; the span subscriber maps failure/halted outcomes and :exception payloads to span error status. Instrumentation code must never rescue StandardError around workflow execution.
  • Async trace continuity comes from the contrib ActiveJob instrumentation (trace context injected into job metadata at enqueue, restored at perform), covering Spree::Events::SubscriberJob, webhook delivery jobs, search indexing and imports without any core change. Default propagation_style: :link (a checkout trace should not stretch until the last webhook retry finishes).
  • Outbound webhooks propagate W3C trace context. traceparent / tracestate headers are injected into webhook POSTs (Saleor does the same), so a merchant's receiving system can join the trace. Core exposes a small header-decorator hook on Spree::Webhooks::DeliverWebhook; the gem registers the propagator there.
  • Span sources are hand-rolled notification subscribers, following the Spree::EventLogSubscriber pattern (module-level subscription handle outside Zeitwerk, detach before every attach for reload safety), not the contrib ActiveSupport.subscribe helper — we need control over span kind (CLIENT for external steps), status mapping from outcome, and attribute filtering that the generic helper doesn't offer.

Design Details

Layer 1 — core notification surface (no new dependencies)

Today only two production instrument calls exist: step.spree_workflow (spree/core/lib/spree/workflow.rb) and the events adapter's <event>.spree (whose instrumented block is intentionally empty — fan-out bookkeeping, not business work). Layer 1 hardens and extends this surface so any consumer — the OpenTelemetry gem, an APM, a log subscriber — sees the full picture:

Notification New/changed Payload Purpose
perform.spree_workflow new workflow, outcome One span per workflow run (today only steps are visible)
step.spree_workflow extended + external (from external_step), + outcome (success/failure, set inside the block) Step spans; external steps become CLIENT spans
hooks.spree_workflow new workflow, hook, handler_count Extension handler dispatch, invisible today
dispatch.spree_events new event_name, subscriber, async Per-subscriber dispatch (enqueue vs inline), uninstrumented today
deliver.spree_webhooks new event_name, url_host, response_code, error_type Wraps the POST in Webhooks::DeliverWebhook#call, which already measures monotonic time and records these values
gateway.spree_payments new action, payment_method_type Wraps Payment::Processing#gateway_action/capture!/void_transaction!, Refund#process!, and the payment-session methods (currently untraced controller-path network calls)

Fast-follow notifications (same shape, after the first cut ships): estimate.spree_delivery_rates / <op>.spree_tax / <op>.spree_fulfillment instrumented in the provider base-class dispatch path (so third-party providers are covered on arrival, and the per-line-item tax call in LineItem becomes immediately visible as an N+1), Meilisearch client calls, imports/exports continuation steps, and OIDC discovery/token exchange.

<event>.spree events stay as they are and surface as span events on the current span (they wrap no work, so they must not become spans).

Existing consumers are unaffected: payload keys are only added, never renamed, and step.spree_workflow semantics stay byte-compatible (the 6.0-service-workflows.md battery must pass unmodified).

Layer 2 — the spree_opentelemetry gem

A new optional engine at spree/opentelemetry depending on:

  • opentelemetry-sdk + opentelemetry-exporter-otlp (stable)
  • opentelemetry-instrumentation-rails (umbrella: Rack, Action Pack, Active Record, Active Job, Action Mailer, Active Support, Concurrent Ruby)
  • opentelemetry-instrumentation-net_http (covers webhook POSTs — the SsrfFilter path is Net::HTTP underneath — plus OIDC discovery/token calls and image downloads)

Responsibilities:

  1. SDK bootstrap in an engine initializer: OpenTelemetry::SDK.configure reading standard env vars, installing the curated instrumentation list, setting service resource attributes (service.name, spree.version), and logging one boot-time line stating telemetry is active and its export endpoint. Dormant (no-op) when no exporter is configured; honors OTEL_SDK_DISABLED.
  2. Spree span subscribers — one subscriber class per notification family above, producing spans named from a bounded vocabulary (carts.add_item, carts.add_item validate_stock, spree.webhook.deliver, spree.gateway.capture) with spree.* attributes. Reload-safe via the EventLogSubscriber handle pattern.
  3. ActiveJob propagation config (propagation_style: :link default, overridable).
  4. Webhook traceparent injection via the core header-decorator hook.
  5. SpreeOpenTelemetry.configure for host-level extension.

What auto-instrumentation already gives us for free

Rack/Action Pack server spans (every Store/Admin API request), Active Record query spans, Active Job enqueue/perform spans with context propagation, Action Mailer, Net::HTTP client spans. Spree's layer adds the commerce semantics on top — which is exactly the split Medusa (workflow:/step: spans) and Vendure (@Instrument() on services) ship.

Testing

  • Core: specs asserting notification names/payloads (including external and outcome keys, and that FailureSignal still propagates).
  • Gem: specs with the in-memory span exporter (opentelemetry-test-helpers) asserting span hierarchy, kinds, error status mapping, and that filtered keys never appear in attributes.
  • One end-to-end smoke: worktree Rails + OTLP collector (or Jaeger all-in-one) verifying a checkout produces the expected trace shape.

Documentation

New docs/developer/deployment/telemetry.mdx (task-focused, mirroring the competitor pages): install the gem, set env vars, point at a collector, screenshot of a checkout trace, span catalog table, PII guarantees, sampling guidance, log-correlation setup. The notification catalog also lands in the customization docs since it doubles as the APM-agnostic instrumentation contract.

Migration Path

Purely additive — no schema changes, no behavior changes, no upgrade tasks.

  1. Phase 1 (core) — shipped 2026-08-12: payload extensions + new notifications listed above (Spree::Workflow, events adapter, DeliverWebhook + header decorators, Spree::InstrumentsGatewayCalls in Payment::Processing/Refund/payment-session controllers).
  2. Phase 2 (gem) — shipped 2026-08-12: spree/opentelemetry (spree_opentelemetry) with env-driven SDK bootstrap, one SpanSubscriber per notification family, domain events as span events, ActiveJob link propagation, webhook traceparent injection; wired into CI matrices and the release Rakefile.
  3. Phase 3 (docs) — shipped 2026-08-12: docs/developer/deployment/telemetry.mdx in both v6 nav trees (including Sentry coexistence guidance). Still needs a spree-starter PR — and amended 2026-08-12: the starter bundles the gem by default, not commented out. The Docker image is built from the starter, so image users cannot edit the Gemfile; with the gem dormant until an OTEL_* exporter variable appears, bundling it makes tracing a pure env-var opt-in for container deployments at the cost of a few MB of image size. The starter already ships Sentry for errors — the docs page covers the three arrangements (independent, Sentry OTLP as trace backend, collector fan-out) and warns against enabling Sentry's own traces_sample_rate alongside. The Sentry-backend recipe requires explicit ordering (SpreeOpenTelemetry.install! before Sentry.init, with OTEL_TRACES_EXPORTER=none) — see decisions.md 2026-08-12; auto-detecting Sentry from the gem was reverted as unworkable.
  4. Fast-follow (can land within 6.0 after the first cut): provider base-class spans (delivery rates, tax, fulfillment), Meilisearch client spans, imports/exports continuation-step spans, OIDC spans.
  5. 6.1 (deferred): metrics via the Ruby metrics SDK once stable (checkout conversion counters, payment failure counters, queue depth); provider-gem HTTP spans using native client hooks (EasyPost's response hook in spree_easypost/engine.rb is the template); storefront (Next.js) trace propagation guide.

Constraints on Current Work

  • New external_step call sites need no extra work — but never model an outbound network call as a plain step; the external_step distinction is now also the tracing contract, not just the transaction guard.
  • Never rescue StandardError around workflow execution in instrumentation or middleware — FailureSignal/Halted inherit Exception and would be missed (failed work reported as OK).
  • Notification payload keys are public API once this ships: additive changes only, same rule as workflow hook keys.
  • No telemetry configuration on Spree::Store or in admin UIs — it is process-level deployment config.
  • Anything added to a notification payload must be PII-safe or run through the parameter filter; assume every payload key becomes a span attribute on someone's dashboard.

Open Questions

All four launch questions (packaging, activation, first-cut span scope, metrics posture) were resolved 2026-08-12 — see Key Decisions. Genuinely deferred items, each with its unblock condition:

  • Native metrics instruments — unblocked when the Ruby metrics SDK reaches a stable release (track opentelemetry-ruby releases).
  • Gateway#method_missing forwarding — arbitrary provider methods bypass the instrumented gateway boundary; decide whether to deprecate the escape hatch or instrument method_missing when the Stripe/Adyen provider gems land in the monorepo.
  • Span naming semantic conventions — OpenTelemetry has no commerce semantic conventions yet; spree.* attribute names are our own vocabulary. Revisit if/when an upstream convention appears.

References