feat: stamp W3C trace context on MongoDB metadata writes

Add a traceContext field to ObjectMD carrying the currently-active
OTEL trace context (W3C traceparent/tracestate). Inject it
automatically at the three metadata write chokepoints where originOp
is set today: internalPutObject, repair, and internalDeleteObject.

The value ends up in the MongoDB oplog; downstream consumers
(backbeat, sorbet) can extract it to continue the trace across the
async boundary, closing the loop on end-to-end tracing for flows
that cross the oplog.

When OTEL is not active on the caller (no SDK, or request outside
a traced context), captureCurrentTraceContext returns undefined,
setTraceContext no-ops, and the field stays absent — zero cost.

Only adds @opentelemetry/api as a runtime dependency (the API-only
surface package, becomes a no-op when no SDK is registered).

Issue: ARSN-572

Author: delthas

lib/models/ObjectMD.ts

@@ -89,6 +89,10 @@ export type ObjectMDData = {
     replicationInfo: ReplicationInfo;
     dataStoreName: string;
     originOp: string;
+    traceContext?: {
+        traceparent?: string;
+        tracestate?: string;
+    };
     microVersionId?: string;
     // Deletion flag
     // Used for keeping object metadata in the oplog event
@@ -1442,6 +1446,33 @@ export default class ObjectMD {
         return this._data.originOp;
     }
 
+    /**
+     * Attach a W3C trace context to the metadata so it ends up in
+     * the MongoDB oplog and downstream consumers can continue the trace.
+     * Always reflects the current write: passing undefined (or a value
+     * without traceparent) clears any previously-set traceContext so that
+     * a stale context does not get carried forward from an existing
+     * ObjectMD loaded from storage.
+     * @param tc - W3C trace context carrier
+     * @return itself
+     */
+    setTraceContext(tc?: { traceparent?: string; tracestate?: string }) {
+        if (tc && tc.traceparent) {
+            this._data.traceContext = tc;
+        } else {
+            delete this._data.traceContext;
+        }
+        return this;
+    }
+
+    /**
+     * Returns the trace context attached to the metadata, if any.
+     * @return W3C trace context carrier or undefined
+     */
+    getTraceContext() {
+        return this._data.traceContext;
+    }
+
     /**
      * Returns metadata object
      *

lib/storage/metadata/captureTraceContext.ts

@@ -0,0 +1,32 @@
+import { context, propagation, trace } from '@opentelemetry/api';
+
+/**
+ * Capture the currently-active OTEL trace context as a plain object
+ * suitable for storing alongside metadata (ends up in the MongoDB oplog).
+ * Returns undefined when no trace is active (e.g., OTEL not enabled,
+ * or called outside a traced request).
+ */
+export function captureCurrentTraceContext():
+    { traceparent: string; tracestate?: string } | undefined {
+    const ctx = context.active();
+    const span = trace.getSpan(ctx);
+    if (!span) {
+        return undefined;
+    }
+
+    const carrier: Record<string, string> = {};
+    propagation.inject(ctx, carrier, {
+        set: (c, k, v) => { c[k] = v; },
+    });
+    if (!carrier.traceparent) {
+        return undefined;
+    }
+
+    const out: { traceparent: string; tracestate?: string } = {
+        traceparent: carrier.traceparent,
+    };
+    if (carrier.tracestate) {
+        out.tracestate = carrier.tracestate;
+    }
+    return out;
+}

lib/storage/metadata/mongoclient/MongoClientInterface.ts

@@ -18,6 +18,7 @@ import { ErrorLike, reshapeExceptionError } from '../../../errorUtils';
 import errors, { ArsenalError, errorInstances } from '../../../errors';
 import BucketInfo, { BucketMetadata, Capabilities } from '../../../models/BucketInfo';
 import ObjectMD, { ObjectMDData } from '../../../models/ObjectMD';
+import { captureCurrentTraceContext } from '../captureTraceContext';
 import * as jsutil from '../../../jsutil';
 import { ArsenalCallback, NestedOmit } from '../../../types';
 
@@ -1361,6 +1362,12 @@ class MongoClientInterface {
         cb: ArsenalCallback<string | void>,
     ): void {
         MongoUtils.serialize(objVal);
+        const tc = captureCurrentTraceContext();
+        if (tc) {
+            objVal.traceContext = tc;
+        } else {
+            delete objVal.traceContext;
+        }
         const c = this.getCollection<ObjectMetastoreDocument>(bucketName);
         const _params = Object.assign({}, params);
         return this.getBucketVFormat(bucketName, log, (err, vFormat?) => {
@@ -1635,6 +1642,15 @@ class MongoClientInterface {
         const masterKey = formatMasterKey(objName, vFormat);
         MongoUtils.serialize(objVal);
         objVal.originOp = 's3:ObjectRemoved:Delete';
+        const tc = captureCurrentTraceContext();
+        if (tc) {
+            objVal.traceContext = tc;
+        } else {
+            // Clear any carried-forward trace context from the loaded
+            // ObjectMD so this repair write doesn't get wrongly linked
+            // to a previous operation's trace.
+            delete objVal.traceContext;
+        }
         c.findOneAndReplace({
             '_id': masterKey,
             'value.isPHD': true,
@@ -2073,6 +2089,7 @@ class MongoClientInterface {
                 const obj = doc.value;
                 const objMetadata = new ObjectMD(obj.value);
                 objMetadata.setOriginOp(originOp);
+                objMetadata.setTraceContext(captureCurrentTraceContext());
                 objMetadata.setDeleted(true);
                 return next(null, objMetadata.getValue());
             }).catch(err => {

package.json

@@ -24,6 +24,7 @@
     "@azure/identity": "^4.13.0",
     "@azure/storage-blob": "^12.31.0",
     "@js-sdsl/ordered-set": "^4.4.2",
+    "@opentelemetry/api": "^1.9.0",
     "@scality/hdclient": "^1.3.1",
     "@smithy/node-http-handler": "^4.3.0",
     "@smithy/protocol-http": "^5.3.5",

tests/unit/models/ObjectMD.spec.js

@@ -328,6 +328,59 @@ describe('ObjectMD class setters/getters', () => {
         assert.deepStrictEqual(md.getOriginOp(), 'Copy');
     });
 
+    it('ObjectMD::set/getTraceContext with valid traceparent', () => {
+        const tc = {
+            traceparent: '00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01',
+            tracestate: 'rojo=00f067aa0ba902b7',
+        };
+        md.setTraceContext(tc);
+        assert.deepStrictEqual(md.getTraceContext(), tc);
+    });
+
+    it('ObjectMD::setTraceContext with undefined clears any existing value', () => {
+        md.setTraceContext({
+            traceparent: '00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01',
+        });
+        md.setTraceContext(undefined);
+        assert.strictEqual(md.getTraceContext(), undefined);
+        assert.strictEqual(md.getValue().traceContext, undefined);
+    });
+
+    it('ObjectMD::setTraceContext without traceparent clears any existing value', () => {
+        md.setTraceContext({
+            traceparent: '00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01',
+        });
+        md.setTraceContext({ tracestate: 'rojo=00f067aa0ba902b7' });
+        assert.strictEqual(md.getTraceContext(), undefined);
+    });
+
+    it('ObjectMD reconstructed from existing data clears stale trace context when setTraceContext(undefined) is called', () => {
+        // Simulates the real hazard: an ObjectMD loaded from storage
+        // already has a traceContext from a previous write. A new
+        // operation without an active span must not inherit that stale
+        // context into its own oplog entry.
+        const stale = {
+            traceparent: '00-aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa-bbbbbbbbbbbbbbbb-01',
+        };
+        const loaded = new ObjectMD(
+            new ObjectMD().setTraceContext(stale).getValue(),
+        );
+        assert.deepStrictEqual(loaded.getTraceContext(), stale);
+        loaded.setTraceContext(undefined);
+        assert.strictEqual(loaded.getTraceContext(), undefined);
+        assert.strictEqual(loaded.getValue().traceContext, undefined);
+    });
+
+    it('ObjectMD::getValue serializes traceContext only when set', () => {
+        assert.strictEqual(md.getValue().traceContext, undefined);
+        md.setTraceContext({
+            traceparent: '00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01',
+        });
+        assert.deepStrictEqual(md.getValue().traceContext, {
+            traceparent: '00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01',
+        });
+    });
+
     it('ObjectMD::set/getAmzRestore', () => {
         md.setAmzRestore({
             'ongoing-request': false,

yarn.lock

@@ -2466,6 +2466,11 @@
   resolved "https://registry.yarnpkg.com/@opentelemetry/api/-/api-1.9.0.tgz#d03eba68273dc0f7509e2a3d5cba21eae10379fe"
   integrity sha512-3giAOQvZiH5F9bMlMiv8+GSPMeqg0dbaeo58/0SlA9sxSqZhnUtxzX9/2FzyhS9sWQf5S0GJE0AKBrFqjpeYcg==
 
+"@opentelemetry/api@^1.9.0":
+  version "1.9.1"
+  resolved "https://registry.yarnpkg.com/@opentelemetry/api/-/api-1.9.1.tgz#c1b0346de336ba55af2d5a7970882037baedec05"
+  integrity sha512-gLyJlPHPZYdAk1JENA9LeHejZe1Ti77/pTeFm/nMXmQH/HFZlcS/O2XJB+L8fkbrNSqhdtlvjBVjxwUYanNH5Q==
+
 "@pkgjs/parseargs@^0.11.0":
   version "0.11.0"
   resolved "https://registry.yarnpkg.com/@pkgjs/parseargs/-/parseargs-0.11.0.tgz#a77ea742fab25775145434eb1d2328cf5013ac33"