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.
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 namespree_opentelemetry, beside core/api/emails. Not underspree/providers/(that shelf means commerce providers with anIntegrationcredential surface) and not an optional require insidespree_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, andOTEL_SDK_DISABLED=trueis the kill switch. No mandatory host initializer. Accepted trade-off: activation via environment can surprise — mitigated by honoringOTEL_SDK_DISABLEDand 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. NoSpree::Configpreference, no store preference, no admin UI. ASpreeOpenTelemetry.configureblock 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 sameActiveSupport::ParameterFilterthatSpree::EventLogSubscriberalready uses (filter_parameters+ Spree's additions inengine.rb). external_stepself-identifies in the notification payload (external: trueonstep.spree_workflow). One payload key marks all 11 declared gateway/carrier boundaries asCLIENTspans; newexternal_stepcall sites get this for free.- Workflow failures must mark spans errored.
FailureSignalandHaltedinheritException(deliberately, so a plainrescuecan't swallow them), and a failureResultis detected after the instrumented block returns. The step instrumentation writes anoutcomepayload key inside the block; the span subscriber mapsfailure/haltedoutcomes and:exceptionpayloads to span error status. Instrumentation code must neverrescue StandardErroraround 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. Defaultpropagation_style: :link(a checkout trace should not stretch until the last webhook retry finishes). - Outbound webhooks propagate W3C trace context.
traceparent/tracestateheaders 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 onSpree::Webhooks::DeliverWebhook; the gem registers the propagator there. - Span sources are hand-rolled notification subscribers, following the
Spree::EventLogSubscriberpattern (module-level subscription handle outside Zeitwerk,detachbefore every attach for reload safety), not the contribActiveSupport.subscribehelper — we need control over span kind (CLIENT for external steps), status mapping fromoutcome, 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 — theSsrfFilterpath is Net::HTTP underneath — plus OIDC discovery/token calls and image downloads)
Responsibilities:
- SDK bootstrap in an engine initializer:
OpenTelemetry::SDK.configurereading 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; honorsOTEL_SDK_DISABLED. - 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) withspree.*attributes. Reload-safe via theEventLogSubscriberhandle pattern. - ActiveJob propagation config (
propagation_style: :linkdefault, overridable). - Webhook
traceparentinjection via the core header-decorator hook. SpreeOpenTelemetry.configurefor 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
externalandoutcomekeys, and thatFailureSignalstill 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.
- Phase 1 (core) — shipped 2026-08-12: payload extensions + new
notifications listed above (
Spree::Workflow, events adapter,DeliverWebhook+ header decorators,Spree::InstrumentsGatewayCallsinPayment::Processing/Refund/payment-session controllers). - Phase 2 (gem) — shipped 2026-08-12:
spree/opentelemetry(spree_opentelemetry) with env-driven SDK bootstrap, oneSpanSubscriberper notification family, domain events as span events, ActiveJob link propagation, webhooktraceparentinjection; wired into CI matrices and the release Rakefile. - Phase 3 (docs) — shipped 2026-08-12:
docs/developer/deployment/telemetry.mdxin 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 anOTEL_*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 owntraces_sample_ratealongside. The Sentry-backend recipe requires explicit ordering (SpreeOpenTelemetry.install!beforeSentry.init, withOTEL_TRACES_EXPORTER=none) — see decisions.md 2026-08-12; auto-detecting Sentry from the gem was reverted as unworkable. - 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.
- 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.rbis the template); storefront (Next.js) trace propagation guide.
Constraints on Current Work
- New
external_stepcall sites need no extra work — but never model an outbound network call as a plainstep; theexternal_stepdistinction is now also the tracing contract, not just the transaction guard. - Never
rescue StandardErroraround workflow execution in instrumentation or middleware —FailureSignal/HaltedinheritExceptionand 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::Storeor 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_missingforwarding — arbitrary provider methods bypass the instrumented gateway boundary; decide whether to deprecate the escape hatch or instrumentmethod_missingwhen 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
- Codebase instrumentation inventory (2026-08-12):
step.spree_workflowatspree/core/lib/spree/workflow.rb:178, events adapter atspree/core/lib/spree/events/adapters/active_support_notifications.rb:32, dispatch atspree/core/lib/spree/events/adapters/base.rb:147, log subscriber pattern atspree/core/app/subscribers/spree/event_log_subscriber.rb, webhook delivery atspree/api/app/services/spree/webhooks/deliver_webhook.rb, gateway boundary atspree/core/app/models/spree/payment/processing.rb. docs/plans/6.0-service-workflows.md— workflow tier, hook contracts,step.spree_workflowbattery.- Medusa instrumentation: https://docs.medusajs.com/learn/debugging-and-testing/instrumentation
- Saleor telemetry: https://docs.saleor.io/setup/telemetry
- Vendure telemetry: https://docs.vendure.io/current/core/how-to/telemetry
- opentelemetry-ruby: https://github.com/open-telemetry/opentelemetry-ruby (traces stable; metrics/logs SDKs experimental)
- opentelemetry-ruby-contrib (Rails umbrella, ActiveJob propagation): https://github.com/open-telemetry/opentelemetry-ruby-contrib