Context

Cloudserver recently gained OpenTelemetry tracing (CLDSRV-884, cloudserver PR scality/cloudserver#6140). That gives us a single end-to-end trace per S3 request spanning cloudserver → vault → hdproxy → hyperiod.

But many state mutations in the S3 stack are written to MongoDB and consumed asynchronously by worker services via the oplog:

• Backbeat — replication, lifecycle expiration/transition, garbage collection
• Sorbet — cold-storage restore completion
• Other oplog consumers

Today the oplog entry carries no trace context, so async work performed hours or days after the S3 request cannot be tied back to the request that caused it. A user's POST …?restore produces a trace that ends at the metadata write; the actual cold-tier retrieval by Sorbet is invisible from the original trace.

Solution

Stamp a W3C trace context (traceparent/tracestate) on every mutating metadata write, auto-derived from the currently-active OTEL context.

The field lives on ObjectMDData next to originOp:

traceContext?: {
    traceparent?: string;
    tracestate?: string;
};

A new helper stampActiveTraceContext(data) in lib/storage/metadata/captureTraceContext.ts:

• reads the active OTEL context via @opentelemetry/api
• serializes it via propagation.inject()
• writes the result to data.traceContext, or clears the field if no span is active (so a stale value loaded from storage cannot leak forward into a new oplog entry)

It is called from inside MongoUtils.serialize(), so every metadata write that goes through serialize automatically gets the stamp (3 sites in MongoClientInterface: putObject, putObjectVerCase4, repair). For the 2 paths that bypass serialize because they rewrite a doc previously read from the DB with already-escaped tags (internalPutObject, internalDeleteObject), stampActiveTraceContext() is called explicitly on the ObjectMD.getValue() result.

Consumers (backbeat, sorbet — out of scope for this PR) will later:

1. Read value.traceContext.traceparent from the oplog entry
2. propagation.extract() it to reconstruct a parent context
3. Wrap per-entry processing in context.with(extractedCtx, ...)

This closes the loop on end-to-end tracing across the async boundary.

Design decisions

1. Auto-inject at the arsenal write boundary (vs. param plumbing).
The alternative was to thread a new traceContext parameter through the ~15 cloudserver call sites that already set originOp. Rejected because:

• @opentelemetry/context-async-hooks (loaded by the OTEL SDK at cloudserver startup) already propagates the request context through arsenal's async call chain for free. Re-reading it at the mongo write is idiomatic OTEL.
• Zero cloudserver surface change — we can iterate on arsenal independently.
• Parallels existing behavior where arsenal reads originOp out of params and attaches it to the ObjectMD.
• Avoids replicating the maintenance cost that makes originOp easy to forget on new API endpoints today.

2. Only @opentelemetry/api as a runtime dep (~10 KB, no SDK).
The api package is specifically designed to be safe for libraries to depend on. When no SDK is registered (today's state for anyone not opting into cloudserver OTEL), context.active() returns a no-op context, trace.getSpan() returns undefined, and stampActiveTraceContext() clears the field and returns. Zero runtime cost when OTEL is off.

3. Optional field, no schema migration.
traceContext is absent by default — consistent with other optional ObjectMD fields like legalHold, retentionDate. No default-value change in the ObjectMDData construction. Existing consumers that don't understand the field simply ignore it; fully backward compatible.

4. Always reflects the current write — never carries a stale context forward.
If no span is active when stampActiveTraceContext() runs, it clears traceContext (rather than leaving whatever was loaded from storage). Same when propagation.inject() produces no traceparent. This prevents both edge-case OTEL output and the more practical hazard where a doc read for a delete/repair carries a traceContext from its original write that does not belong on the new oplog entry.

5. Single helper, single contract.
The trace-stamping API on arsenal is one function: stampActiveTraceContext(data). There is intentionally no public setter on ObjectMD — the contract is "trace context is stamped by the metadata backend at write time," and exposing a model-level setter would invite callers in cloudserver/backbeat to bypass that contract (issue raised in review). Internally this also keeps the stamp/clear semantics in exactly one place.

Interaction with async flows (cold restore as example)

Cold storage restore exercises both a sync and an async metadata write:

1. ObjectRestore:Post (sync, user-initiated via POST /bucket/key?restore) — cloudserver sets originOp; arsenal now also stamps traceContext pointing to the user's request trace. ✅
2. ObjectRestore:Completed (async, Sorbet-triggered via cloudserver's /_/backbeat/* route) — behavior depends on Sorbet:
   • If Sorbet forwards traceparent on its HTTP call (ideally extracted from step 1's stored traceContext): arsenal picks it up via context.with(remoteContext, ...) in cloudserver's server.js, and the Completed write ties back to the original user restore. ✅
   • If Sorbet calls without traceparent (today's state): safely no-ops — Completed write has no traceContext, no regression. ✅

Same pattern applies to lifecycle expiration/transition, CRR replication, and GC.

Verification

Unit tests

• tests/unit/storage/metadata/captureTraceContext.spec.js — covers stampActiveTraceContext: no-active-span clears (and is a no-op when there was nothing to clear), traceparent-only write, traceparent + tracestate write, defensive handling of a misbehaving propagator that injects no traceparent, overwrite of a stale value.
• tests/unit/storage/metadata/mongoclient/{putObject,delObject,repair}.spec.js — sinon-stubbed tests verify the field lands on the document handed to findOneAndReplace / bulkWrite for each of the 4 write paths the cloudserver hot path exercises, and that it is cleared rather than carried forward when no span is active.

All 449 tests in tests/unit/models/ and tests/unit/storage/metadata/ pass.

End-to-end (follow-up on a test cluster)

1. Bump cloudserver's arsenal pin to a build of this branch; roll the cloudserver deployment on an Artesca cluster with ENABLE_OTEL=true
2. Make a PutObject; note the trace ID in Jaeger
3. Inspect the MongoDB oplog: o.value.traceContext.traceparent should be present, with characters 3-35 matching the Jaeger trace ID
4. Negative test with ENABLE_OTEL=false → field should be absent

Issue: ARSN-572