Add OTEP #4947 OTEL-compatible context storage (#347)

Author: jbachorik

ddprof-lib/src/main/cpp/arguments.h

@@ -223,8 +223,7 @@ class Arguments {
         _context_attributes({}),
         _lightweight(false),
         _enable_method_cleanup(true),
-        _remote_symbolication(false) { }
-
+        _remote_symbolication(false) {}
 
   ~Arguments();
 

ddprof-lib/src/main/cpp/context.cpp

@@ -18,10 +18,6 @@
 #define _CONTEXT_H
 
 #include "arch.h"
-#include "arguments.h"
-#include "common.h"
-#include "os.h"
-#include "vmEntry.h"
 
 static const u32 DD_TAGS_CAPACITY = 10;
 
@@ -31,27 +27,11 @@ typedef struct {
 
 class alignas(DEFAULT_CACHE_LINE_SIZE) Context {
 public:
-  volatile u64 spanId;
-  volatile u64 rootSpanId;
-  volatile u64 checksum;
+  u64 spanId;
+  u64 rootSpanId;
   Tag tags[DD_TAGS_CAPACITY];
 
   Tag get_tag(int i) { return tags[i]; }
 };
 
-class Contexts {
-
-public:
-  static Context& initializeContextTls();
-  static Context& get();
-
-  static u64 checksum(u64 spanId, u64 rootSpanId) {
-    u64 swappedRootSpanId = ((rootSpanId & 0xFFFFFFFFULL) << 32) | (rootSpanId >> 32);
-    u64 computed = (spanId * KNUTH_MULTIPLICATIVE_CONSTANT) ^ (swappedRootSpanId * KNUTH_MULTIPLICATIVE_CONSTANT);
-    return computed == 0 ? 0xffffffffffffffffull : computed;
-  }
-};
-
-DLLEXPORT extern thread_local Context context_tls_v1;
-
 #endif /* _CONTEXT_H */

ddprof-lib/src/main/cpp/context.h

@@ -0,0 +1,115 @@
+/*
+ * Copyright 2026, Datadog, Inc
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#include "context_api.h"
+#include "context.h"
+#include "guards.h"
+#include "otel_context.h"
+#include "otel_process_ctx.h"
+#include "profiler.h"
+#include "thread.h"
+#include <cstring>
+
+// Reserved attribute index for local root span ID in OTEL attrs_data.
+// Only used within this translation unit; not part of the public ContextApi header.
+static const uint8_t LOCAL_ROOT_SPAN_ATTR_INDEX = 0;
+
+/**
+ * Initialize context TLS for the current thread on first use.
+ * Must be called with signals blocked to prevent musl TLS deadlock:
+ * on musl, the first write to a TLS variable triggers lazy slot allocation,
+ * which acquires an internal lock that is also held during signal delivery,
+ * causing deadlock if a signal fires mid-init.
+ * The OtelThreadContextRecord is already zero-initialized by the ProfiledThread ctor.
+ */
+void ContextApi::initializeContextTLS(ProfiledThread* thrd) {
+    SignalBlocker blocker;
+    // Set the TLS pointer permanently to this thread's record.
+    // This first write triggers musl's TLS slot initialization (see above).
+    // The pointer remains stable for the thread's lifetime; external profilers
+    // rely solely on the valid flag for consistency, not pointer nullness.
+    otel_thread_ctx_v1 = thrd->getOtelContextRecord();
+    thrd->markContextInitialized();
+}
+
+bool ContextApi::get(u64& span_id, u64& root_span_id) {
+    ProfiledThread* thrd = ProfiledThread::currentSignalSafe();
+    if (thrd == nullptr || !thrd->isContextInitialized()) {
+        return false;
+    }
+
+    OtelThreadContextRecord* record = thrd->getOtelContextRecord();
+    if (__atomic_load_n(&record->valid, __ATOMIC_ACQUIRE) != 1) {
+        return false;
+    }
+    u64 val = 0;
+    for (int i = 0; i < 8; i++) { val = (val << 8) | record->span_id[i]; }
+    span_id = val;
+
+    root_span_id = thrd->getOtelLocalRootSpanId();
+    return true;
+}
+
+Context ContextApi::snapshot() {
+    ProfiledThread* thrd = ProfiledThread::currentSignalSafe();
+    if (thrd == nullptr) {
+        return {};
+    }
+    size_t numAttrs = Profiler::instance()->numContextAttributes();
+    return thrd->snapshotContext(numAttrs);
+}
+
+void ContextApi::registerAttributeKeys(const char** keys, int count) {
+    // Clip to DD_TAGS_CAPACITY: that is the actual sidecar slot limit and the
+    // maximum keyIndex accepted by ThreadContext.setContextAttribute.
+    int n = count < (int)DD_TAGS_CAPACITY ? count : (int)DD_TAGS_CAPACITY;
+
+    // Build NULL-terminated key array for the process context config.
+    // Index LOCAL_ROOT_SPAN_ATTR_INDEX (0) is reserved for local_root_span_id; user keys start at index 1.
+    // otel_process_ctx_publish copies all strings, so no strdup is needed.
+    const char* key_ptrs[DD_TAGS_CAPACITY + 2]; // +1 reserved, +1 null
+    key_ptrs[LOCAL_ROOT_SPAN_ATTR_INDEX] = "datadog.local_root_span_id";
+    for (int i = 0; i < n; i++) {
+        key_ptrs[i + 1] = keys[i];
+    }
+    key_ptrs[n + 1] = nullptr;
+
+    otel_thread_ctx_config_data config = {
+        .schema_version = "tlsdesc_v1_dev",
+        .attribute_key_map = key_ptrs,
+    };
+
+#ifndef OTEL_PROCESS_CTX_NO_READ
+    otel_process_ctx_read_result read_result = otel_process_ctx_read();
+    if (read_result.success) {
+        otel_process_ctx_data data = {
+            .deployment_environment_name = read_result.data.deployment_environment_name,
+            .service_instance_id = read_result.data.service_instance_id,
+            .service_name = read_result.data.service_name,
+            .service_version = read_result.data.service_version,
+            .telemetry_sdk_language = read_result.data.telemetry_sdk_language,
+            .telemetry_sdk_version = read_result.data.telemetry_sdk_version,
+            .telemetry_sdk_name = read_result.data.telemetry_sdk_name,
+            .resource_attributes = read_result.data.resource_attributes,
+            .extra_attributes = read_result.data.extra_attributes,
+            .thread_ctx_config = &config,
+        };
+
+        otel_process_ctx_publish(&data);
+        otel_process_ctx_read_drop(&read_result);
+    }
+#endif
+}

ddprof-lib/src/main/cpp/context_api.cpp

@@ -0,0 +1,83 @@
+/*
+ * Copyright 2026, Datadog, Inc
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#ifndef _CONTEXT_API_H
+#define _CONTEXT_API_H
+
+#include "arch.h"
+#include "context.h"
+#include <cstdint>
+
+class ProfiledThread;
+
+/**
+ * Unified context API for trace/span context storage.
+ *
+ * Uses OTEP #4947 TLS pointer (otel_thread_ctx_v1) for all
+ * context reads and writes. The OTEP record is embedded in ProfiledThread
+ * and discovered by external profilers via ELF dynsym.
+ */
+class ContextApi {
+public:
+    /**
+     * Initialize context TLS for the given thread on first use.
+     * Must be called with signals blocked (SignalBlocker).
+     */
+    static void initializeContextTLS(ProfiledThread* thrd);
+
+    /**
+     * Read span ID and local root span ID for the current thread.
+     *
+     * Used by signal handlers to get the current trace context.
+     * Returns false if the OTEP valid flag is not set (record being mutated
+     * or thread not yet initialized). Does not modify span_id or root_span_id
+     * on failure; callers must pre-initialize output parameters to their
+     * desired default. Does not detect torn reads (the valid flag guards that).
+     *
+     * Unlike snapshot(), this reads only spanId and rootSpanId — use
+     * snapshot() when tag encodings are also needed.
+     *
+     * @param span_id Output: the span ID
+     * @param root_span_id Output: the root span ID (from sidecar)
+     * @return true if the valid flag was set and context was read
+     */
+    static bool get(u64& span_id, u64& root_span_id);
+
+    /**
+     * Snapshot the current thread's full context into a Context struct.
+     *
+     * Populates a Context with spanId, rootSpanId (from sidecar)
+     * and tag encodings (from sidecar) so that writeContextSnapshot()
+     * works for both live and deferred event paths. Unlike get(), this
+     * also captures custom attribute tag encodings.
+     *
+     * @return A Context struct representing the current thread's context
+     */
+    static Context snapshot();
+
+    /**
+     * Register attribute key names and publish them in the process context.
+     * Must be called before setAttribute().
+     * Keys beyond DD_TAGS_CAPACITY are silently clipped.
+     *
+     * @param keys Array of key name strings
+     * @param count Number of keys (clipped to DD_TAGS_CAPACITY)
+     */
+    static void registerAttributeKeys(const char** keys, int count);
+
+};
+
+#endif /* _CONTEXT_API_H */

ddprof-lib/src/main/cpp/context_api.h

@@ -41,7 +41,6 @@
   X(CONTEXT_STORAGE_PAGES, "context_storage_pages")                            \
   X(CONTEXT_BOUNDS_MISS_INITS, "context_bounds_miss_inits")                    \
   X(CONTEXT_BOUNDS_MISS_GETS, "context_bounds_miss_gets")                      \
-  X(CONTEXT_CHECKSUM_REJECT_GETS, "context_checksum_reject_gets")              \
   X(CONTEXT_NULL_PAGE_GETS, "context_null_page_gets")                          \
   X(CONTEXT_ALLOC_FAILS, "context_alloc_fails")                                \
   X(CALLTRACE_STORAGE_BYTES, "calltrace_storage_bytes")                        \