feat(c-binding): accept explicit span timestamps

Add `start_time_ns` to `dd_span_options_t` and introduce
`dd_span_finish_with_time(end_time_ns)`. Both accept wall-clock
nanoseconds since the UNIX epoch; 0 preserves today's "use current
time" behaviour so existing callers are unaffected.

The conversion from wall-ns to the tracer's internal `TimePoint`
derives the steady_clock tick from the current system/steady offset,
so duration math stays correct regardless of which endpoint is
explicit and which is implicit.

Motivated by FFI callers (e.g. the Kong plugin) that capture
timestamps in their host runtime before crossing the FFI boundary,
where using "now" inside the binding would lose the pre-FFI portion
of the span and bake in call-overhead skew.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: adeshkumar1

binding/c/include/datadog/c/tracer.h

@@ -1,6 +1,7 @@
 #pragma once
 
 #include <stddef.h>
+#include <stdint.h>
 
 #if defined(_WIN32)
 #if defined(DD_TRACE_C_BUILDING)
@@ -51,6 +52,7 @@ typedef struct {
   const char* service_type;
   const char* environment;
   const char* version;
+  int64_t start_time_ns;  // UNIX-epoch nanoseconds; 0 = use current time
 } dd_span_options_t;
 
 // Error codes returned by the C binding.
@@ -179,6 +181,13 @@ DD_TRACE_C_API dd_span_t* dd_span_create_child(dd_span_t* span_handle,
 // @param span_handle Span handle
 DD_TRACE_C_API void dd_span_finish(dd_span_t* span_handle);
 
+// Finish a span using an explicit end time. No-op if span_handle is NULL.
+//
+// @param span_handle Span handle
+// @param end_time_ns Wall-clock end time (UNIX-epoch ns); 0 = current time
+DD_TRACE_C_API void dd_span_finish_with_time(dd_span_t* span_handle,
+                                             int64_t end_time_ns);
+
 // Get the trace ID as a zero-padded hex string.
 //
 // @param span_handle  Span handle

binding/c/src/tracer.cpp

@@ -44,6 +44,18 @@ class ContextWriter : public dd::DictWriter {
   }
 };
 
+// tick is derived from the current system/steady offset so that duration
+// (end.tick - start.tick) stays correct across FFI-supplied timestamps.
+dd::TimePoint wall_ns_to_timepoint(int64_t wall_ns) {
+  const auto wall = std::chrono::system_clock::time_point(
+      std::chrono::round<std::chrono::system_clock::duration>(
+          std::chrono::nanoseconds(wall_ns)));
+  const auto now_wall = std::chrono::system_clock::now();
+  const auto now_tick = std::chrono::steady_clock::now();
+  return {wall,
+          now_tick - std::chrono::duration_cast<dd::Duration>(now_wall - wall)};
+}
+
 dd::SpanConfig make_span_config(dd_span_options_t options) {
   dd::SpanConfig span_config;
   if (options.name != nullptr) {
@@ -64,6 +76,9 @@ dd::SpanConfig make_span_config(dd_span_options_t options) {
   if (options.version != nullptr) {
     span_config.version = options.version;
   }
+  if (options.start_time_ns != 0) {
+    span_config.start = wall_ns_to_timepoint(options.start_time_ns);
+  }
   return span_config;
 }
 
@@ -249,12 +264,34 @@ dd_span_t *dd_span_create_child(dd_span_t *span_handle,
   }
 }
 
-void dd_span_finish(dd_span_t *span_handle) {
+void dd_span_finish_with_time(dd_span_t *span_handle, int64_t end_time_ns) {
   if (span_handle == nullptr) {
     return;
   }
-  reinterpret_cast<dd::Span *>(span_handle)
-      ->set_end_time(std::chrono::steady_clock::now());
+  auto *span = reinterpret_cast<dd::Span *>(span_handle);
+  const auto start = span->start_time();
+  // Explicit path anchors to start.wall so NTP adjustments during the
+  // span's lifetime don't skew duration; implicit path uses steady now.
+  // Both clamp to start.tick so a negative duration never ships
+  // (serialization casts duration to uint64_t).
+  std::chrono::steady_clock::time_point end_tick;
+  if (end_time_ns == 0) {
+    end_tick = std::chrono::steady_clock::now();
+  } else {
+    const auto end_wall = std::chrono::system_clock::time_point(
+        std::chrono::round<std::chrono::system_clock::duration>(
+            std::chrono::nanoseconds(end_time_ns)));
+    end_tick =
+        start.tick +
+        (end_wall > start.wall
+             ? std::chrono::duration_cast<dd::Duration>(end_wall - start.wall)
+             : dd::Duration::zero());
+  }
+  span->set_end_time(end_tick > start.tick ? end_tick : start.tick);
+}
+
+void dd_span_finish(dd_span_t *span_handle) {
+  dd_span_finish_with_time(span_handle, 0);
 }
 
 int dd_span_get_trace_id(dd_span_t *span_handle, char *buffer,

binding/c/test/test_c_binding.cpp

@@ -91,7 +91,11 @@ TEST_CASE("tracer new propagates error", "[c_binding]") {
 TEST_CASE("span create, tag, finish, free", "[c_binding]") {
   auto ctx = make_tracer();
 
-  auto *span = dd_tracer_create_span(ctx.tracer, {.name = "test.op"});
+  const int64_t start_ns = 1'700'000'000'000'000'000LL;
+  const int64_t end_ns = start_ns + 42'000'000LL;
+
+  auto *span = dd_tracer_create_span(
+      ctx.tracer, {.name = "test.op", .start_time_ns = start_ns});
   REQUIRE(span != nullptr);
 
   dd_span_set_tag(span, "http.method", "GET");
@@ -100,7 +104,7 @@ TEST_CASE("span create, tag, finish, free", "[c_binding]") {
   dd_span_set_error(span, 1);
   dd_span_set_error_message(span, "something broke");
 
-  dd_span_finish(span);
+  dd_span_finish_with_time(span, end_ns);
   dd_span_free(span);
 
   const auto &sd = ctx.collector->first_span();
@@ -109,6 +113,40 @@ TEST_CASE("span create, tag, finish, free", "[c_binding]") {
   CHECK(sd.service == "user-service");
   CHECK(sd.error == true);
   CHECK(sd.tags.at("error.message") == "something broke");
+
+  CHECK(std::chrono::duration_cast<std::chrono::nanoseconds>(
+            sd.start.wall.time_since_epoch())
+            .count() == start_ns);
+  CHECK(std::chrono::abs(sd.duration -
+                         std::chrono::nanoseconds(end_ns - start_ns)) <
+        std::chrono::milliseconds(1));
+}
+
+TEST_CASE("finish clamps negative durations to zero", "[c_binding]") {
+  auto ctx = make_tracer();
+
+  // Explicit end before explicit start.
+  const int64_t past_ns = 1'700'000'000'000'000'000LL;
+  auto *s1 = dd_tracer_create_span(
+      ctx.tracer, {.name = "explicit", .start_time_ns = past_ns});
+  dd_span_finish_with_time(s1, past_ns - 1'000'000LL);
+  dd_span_free(s1);
+
+  // Sentinel finish (steady_clock::now()) with a start projected into
+  // the future — exercises the implicit-path clamp.
+  const int64_t future_ns =
+      std::chrono::duration_cast<std::chrono::nanoseconds>(
+          (std::chrono::system_clock::now() + std::chrono::hours(1))
+              .time_since_epoch())
+          .count();
+  auto *s2 = dd_tracer_create_span(
+      ctx.tracer, {.name = "implicit", .start_time_ns = future_ns});
+  dd_span_finish(s2);
+  dd_span_free(s2);
+
+  for (const auto &chunk : ctx.collector->chunks)
+    for (const auto &span : chunk)
+      CHECK(span->duration >= std::chrono::nanoseconds(0));
 }
 
 TEST_CASE("create span with resource", "[c_binding]") {
@@ -253,6 +291,7 @@ TEST_CASE("null arguments do not crash", "[c_binding]") {
   dd_span_set_error_message(nullptr, "msg");
   dd_span_inject(nullptr, test_header_writer);
   dd_span_finish(nullptr);
+  dd_span_finish_with_time(nullptr, 0);
   dd_span_set_resource(nullptr, "res");
   dd_span_set_service(nullptr, "svc");
 }