SAP Commerce · Java 21 · Gradle

commerce-otel

Business-level distributed tracing and error-taxonomy analytics for SAP Commerce topologies (monolith + BTP microservices + lambdas + eventing).

The problem

You can't watch one cart flow storefront → OCC → decorator lambda → cart-service rules → pricing → export as a single business narrative. APM shows infra spans, not checkout scenarios. Domain error taxonomies live in code with no analytics.

Expertise-gated

You can't watch one cart flow storefront → OCC → decorator lambda → cart-service rules → pricing → export as a single business narrative. AP…

Costly & slow

Manual, error-prone work that scales badly across a large estate.

Under-tooled

The ecosystem lacks modern, opinionated backend tooling for this.

The solution & why it's useful

An OpenTelemetry-native layer that stitches OCC/OData/NATS/CPI hops into **business transactions**, plus an **error-code catalog & analytics** ('VAL_0046 buying-restriction fires 4k×/day, 80% on channel 02').

Business spans, not just infra

Spans carry domain semantics — scenario, channel, runway, transaction type — so a trace reads as a checkout story.

Cross-boundary stitching

Correlates sync REST and async NATS hops into one transaction via propagated trace context.

Error economics

Turns a de-facto error-code contract into a queryable catalog with live frequency analytics.

Standards-based

Pure OpenTelemetry — export to any backend you already run.

Capabilities

CapabilityDescription
Semantic conventionsA SAP-Commerce span/attribute vocabulary.
Trace stitchingJoin NATS-async hops to their originating transaction.
Error catalogRegistry + analytics over domain error codes.
ExportersOTLP-compatible; plug into your collector.

Early scaffold: the core abstraction, a starter implementation and tests are real. This is a foundation to build on.

Usage example

Distilled from the runnable tutorial examples/Example.java. The Output block is real captured stdout (deterministic ids/durations).

Start a business-attributed trace, assemble the span tree, and rank domain error codes:

BusinessSpanFactory factory = new BusinessSpanFactory(
        ids::getAndIncrement, () -> fakeNanos.getAndAdd(1_000_000L));

Span root = factory.startTrace("checkout-renewal");
factory.withDomain(root, "renewal", "01", "CR"); // scenario, channel, runway
recorder.record(root);
recorder.record(factory.startChild(root, "validate-cart"));
recorder.record(factory.startChild(root, "persist-order"));
List<Span> ordered = recorder.assemble(root.traceId());

ErrorCatalog catalog = new ErrorCatalog()
        .register("VAL_0210", "Configurable product missing required characteristic");
catalog.topCodes(3); // ranked by frequency
Output:
- checkout-renewal   [span=0000000000000002] 7.0 ms {commerce.scenario=renewal, commerce.channel=01, commerce.runway=CR}
  - validate-cart      [span=0000000000000003] 4.0 ms {...}
    - cpq-pricing-call   [span=0000000000000004] 2.0 ms {...}
  - persist-order      [span=0000000000000005] 3.0 ms {...}
Spans on channel 01: 4 of 4

Top 3 error codes by frequency:
  VAL_0210  x8    Configurable product missing required characteristic
  VAL_0046  x5    Quote total below the channel minimum
  VAL_0102  x2    Renewal end-date precedes start-date

Run it yourself (JDK 21, no Gradle): find src/main/java -name '*.java' | xargs javac -d /tmp/ex-otel && java -cp /tmp/ex-otel com.sapcommercetools.otel.examples.Example