react-native-nitro-tracing 0.6.0

package/cpp/HybridRecording.cpp

@@ -0,0 +1,66 @@
+#include "HybridRecording.hpp"
+#include "HybridTraceSpan.hpp"
+#include "NativeConversions.hpp"
+#include "core/TraceJson.hpp"
+#include <cmath>
+#include <stdexcept>
+namespace margelo::nitro::nitrotracing {
+HybridRecording::HybridRecording(tracingcore::Config c)
+    : HybridObject(TAG), recorder_(std::make_shared<tracingcore::Recorder>(c)) {}
+HybridRecording::~HybridRecording() {
+  stopNativeSampling();
+  recorder_->stop();
+}
+std::shared_ptr<HybridTraceSpanSpec> HybridRecording::startSpan(const SpanOptions &o) {
+  auto token = recorder_->startSpan(toCore(o.name, o.correlationId, o.attributes), o.parentSpanId.value_or(""));
+  return std::make_shared<HybridTraceSpan>(recorder_, token);
+}
+std::string HybridRecording::recordSpan(const CompletedSpanOptions &o) {
+  return recorder_->recordSpan(toCore(o.name, o.correlationId, o.attributes), o.parentSpanId.value_or(""),
+                               o.timestampMs, o.durationMs, toCore(o.outcome), o.sourceSpanId.value_or(""),
+                               o.sourceParentSpanId.value_or(""));
+}
+void HybridRecording::mark(const MarkOptions &o) {
+  recorder_->mark(toCore(o.name, o.correlationId, o.attributes), o.timestampMs);
+}
+void HybridRecording::recordMetric(const MetricOptions &o) {
+  recorder_->metric(toCore(o.name, o.correlationId, o.attributes), o.value, o.unit, o.timestampMs);
+}
+std::shared_ptr<Promise<TracePage>> HybridRecording::readEvents(const ReadOptions &o) {
+  auto after = checkedInteger(o.afterSequence, 9007199254740991.0, "afterSequence");
+  auto limit = checkedInteger(o.limit, 1000, "limit");
+  auto recorder = recorder_;
+  return Promise<TracePage>::async([recorder, after, limit]() { return toNative(recorder->read(after, limit)); });
+}
+RecordingStats HybridRecording::getStats() { return toNative(recorder_->stats()); }
+void HybridRecording::stop() {
+  stopNativeSampling();
+  recorder_->stop();
+}
+std::shared_ptr<Promise<std::string>> HybridRecording::exportJson() {
+  auto recorder = recorder_;
+  return Promise<std::string>::async([recorder]() { return tracingcore::exportJson(recorder->snapshot()); });
+}
+size_t HybridRecording::getExternalMemorySize() noexcept { return recorder_->memorySize(); }
+void HybridRecording::dispose() {
+  stopNativeSampling();
+  recorder_->clear();
+}
+std::shared_ptr<Promise<std::string>> HybridRecording::exportTraceEvents() {
+  auto recorder = recorder_;
+  return Promise<std::string>::async([recorder]() { return tracingcore::exportTraceEvents(recorder->snapshot()); });
+}
+void HybridRecording::startNativeSampling(const NativeSamplingOptions &o) {
+  if (!std::isfinite(o.intervalMs) || o.intervalMs < 250 || o.intervalMs > 60000)
+    throw std::invalid_argument("Native sampling interval must be 250..60000 ms");
+  if (!recorder_->stats().recording)
+    throw std::runtime_error("Recording has stopped");
+  std::lock_guard lock(samplerMutex_);
+  sampler_.reset(); // Join the previous thread before starting its replacement.
+  sampler_ = std::make_unique<tracingcore::NativeSampler>(recorder_, o.intervalMs, o.frames);
+}
+void HybridRecording::stopNativeSampling() {
+  std::lock_guard lock(samplerMutex_);
+  sampler_.reset();
+}
+} // namespace margelo::nitro::nitrotracing

package/cpp/HybridRecording.hpp

@@ -0,0 +1,30 @@
+#pragma once
+#include "HybridRecordingSpec.hpp"
+#include "core/NativeSampler.hpp"
+#include "core/Recorder.hpp"
+#include <mutex>
+namespace margelo::nitro::nitrotracing {
+class HybridRecording final : public HybridRecordingSpec {
+public:
+  explicit HybridRecording(tracingcore::Config config);
+  ~HybridRecording() override;
+  std::shared_ptr<HybridTraceSpanSpec> startSpan(const SpanOptions &options) override;
+  std::string recordSpan(const CompletedSpanOptions &options) override;
+  void mark(const MarkOptions &options) override;
+  void recordMetric(const MetricOptions &options) override;
+  std::shared_ptr<Promise<TracePage>> readEvents(const ReadOptions &options) override;
+  RecordingStats getStats() override;
+  void stop() override;
+  std::shared_ptr<Promise<std::string>> exportJson() override;
+  std::shared_ptr<Promise<std::string>> exportTraceEvents() override;
+  void startNativeSampling(const NativeSamplingOptions &options) override;
+  void stopNativeSampling() override;
+  size_t getExternalMemorySize() noexcept override;
+  void dispose() override;
+
+private:
+  std::shared_ptr<tracingcore::Recorder> recorder_;
+  std::mutex samplerMutex_;
+  std::unique_ptr<tracingcore::NativeSampler> sampler_;
+};
+} // namespace margelo::nitro::nitrotracing

package/cpp/HybridTraceSpan.cpp

@@ -0,0 +1,10 @@
+#include "HybridTraceSpan.hpp"
+#include "NativeConversions.hpp"
+namespace margelo::nitro::nitrotracing {
+HybridTraceSpan::HybridTraceSpan(std::shared_ptr<tracingcore::Recorder> r, uint64_t t)
+    : HybridObject(TAG), recorder_(std::move(r)), token_(t) {}
+std::string HybridTraceSpan::getSpanId() { return recorder_->spanId(token_); }
+bool HybridTraceSpan::getRecorded() { return token_ != 0; }
+void HybridTraceSpan::end(SpanOutcome outcome) { recorder_->endSpan(token_, toCore(outcome)); }
+void HybridTraceSpan::dispose() { recorder_->endSpan(token_, tracingcore::Outcome::Interrupted); }
+} // namespace margelo::nitro::nitrotracing

package/cpp/HybridTraceSpan.hpp

@@ -0,0 +1,17 @@
+#pragma once
+#include "HybridTraceSpanSpec.hpp"
+#include "core/Recorder.hpp"
+namespace margelo::nitro::nitrotracing {
+class HybridTraceSpan final : public HybridTraceSpanSpec {
+public:
+  HybridTraceSpan(std::shared_ptr<tracingcore::Recorder> recorder, uint64_t token);
+  std::string getSpanId() override;
+  bool getRecorded() override;
+  void end(SpanOutcome outcome) override;
+  void dispose() override;
+
+private:
+  std::shared_ptr<tracingcore::Recorder> recorder_;
+  uint64_t token_;
+};
+} // namespace margelo::nitro::nitrotracing

package/cpp/HybridTracing.cpp

@@ -0,0 +1,10 @@
+#include "HybridTracing.hpp"
+#include "HermesSampling.hpp"
+#include "HybridRecording.hpp"
+#include "NativeConversions.hpp"
+namespace margelo::nitro::nitrotracing {
+std::shared_ptr<HybridRecordingSpec> HybridTracing::startRecording(const RecordingOptions &o) {
+  return std::make_shared<HybridRecording>(toCore(o));
+}
+bool HybridTracing::disableHermesSampling() { return nitrotracing::disableHermesSampling(); }
+} // namespace margelo::nitro::nitrotracing

package/cpp/HybridTracing.hpp

@@ -0,0 +1,10 @@
+#pragma once
+#include "HybridTracingSpec.hpp"
+namespace margelo::nitro::nitrotracing {
+class HybridTracing final : public HybridTracingSpec {
+public:
+  HybridTracing() : HybridObject(TAG) {}
+  std::shared_ptr<HybridRecordingSpec> startRecording(const RecordingOptions &options) override;
+  bool disableHermesSampling() override;
+};
+} // namespace margelo::nitro::nitrotracing

package/cpp/NativeConversions.cpp

@@ -0,0 +1,77 @@
+#include "NativeConversions.hpp"
+#include <cmath>
+#include <stdexcept>
+namespace margelo::nitro::nitrotracing {
+uint64_t checkedInteger(double value, double maximum, const char *field) {
+  if (!std::isfinite(value) || value < 0 || value > maximum || std::floor(value) != value)
+    throw std::invalid_argument(std::string(field) + " must be a nonnegative integer within its documented limit");
+  return static_cast<uint64_t>(value);
+}
+tracingcore::Context toCore(const std::string &name, const std::string &id, const std::vector<TraceAttribute> &attrs) {
+  tracingcore::Context c{name, id, {}};
+  c.attributes.reserve(attrs.size());
+  for (const auto &a : attrs)
+    c.attributes.push_back({a.key, a.value});
+  return c;
+}
+tracingcore::Config toCore(const RecordingOptions &o) {
+  // Range-checked above, so the casts are safe where size_t is 32-bit (armeabi-v7a).
+  return {static_cast<size_t>(checkedInteger(o.maxEvents, 100000, "maxEvents")),
+          static_cast<size_t>(checkedInteger(o.maxBytes, 67108864, "maxBytes")),
+          static_cast<size_t>(checkedInteger(o.maxActiveSpans, 10000, "maxActiveSpans")), o.spanTimeoutMs};
+}
+tracingcore::Outcome toCore(SpanOutcome o) {
+  switch (o) {
+  case SpanOutcome::SUCCESS:
+    return tracingcore::Outcome::Success;
+  case SpanOutcome::ERROR:
+    return tracingcore::Outcome::Error;
+  case SpanOutcome::CANCELLED:
+    return tracingcore::Outcome::Cancelled;
+  case SpanOutcome::INTERRUPTED:
+    return tracingcore::Outcome::Interrupted;
+  }
+  throw std::invalid_argument("Invalid span outcome");
+}
+RecordingStats toNative(const tracingcore::Stats &s) {
+  return RecordingStats(s.sessionId, s.startedAtUnixMs, s.nowMs, s.recording, static_cast<double>(s.eventCount),
+                        static_cast<double>(s.retainedBytes), static_cast<double>(s.droppedEvents),
+                        static_cast<double>(s.activeSpans), static_cast<double>(s.droppedSpans),
+                        static_cast<double>(s.droppedMarks), static_cast<double>(s.droppedMetrics));
+}
+TracePage toNative(const tracingcore::Page &page) {
+  TracePage p;
+  p.nextSequence = page.nextSequence;
+  p.earliestSequence = page.earliestSequence;
+  p.droppedEvents = page.droppedEvents;
+  for (const auto &e : page.events) {
+    std::vector<TraceAttribute> attrs;
+    attrs.reserve(e.context.attributes.size());
+    for (const auto &a : e.context.attributes)
+      attrs.emplace_back(a.key, a.value);
+    if (const auto *s = std::get_if<tracingcore::SpanData>(&e.data)) {
+      SpanOutcome outcome = SpanOutcome::SUCCESS;
+      switch (s->outcome) {
+      case tracingcore::Outcome::Success:
+        break;
+      case tracingcore::Outcome::Error:
+        outcome = SpanOutcome::ERROR;
+        break;
+      case tracingcore::Outcome::Cancelled:
+        outcome = SpanOutcome::CANCELLED;
+        break;
+      case tracingcore::Outcome::Interrupted:
+        outcome = SpanOutcome::INTERRUPTED;
+        break;
+      }
+      p.spans.emplace_back(s->spanId, s->parentSpanId, s->durationMs, outcome, e.sequence, e.timestampMs,
+                           e.context.name, e.context.correlationId, attrs);
+    } else if (const auto *m = std::get_if<tracingcore::MetricData>(&e.data))
+      p.metrics.emplace_back(m->value, m->unit, e.sequence, e.timestampMs, e.context.name, e.context.correlationId,
+                             attrs);
+    else
+      p.marks.emplace_back(e.sequence, e.timestampMs, e.context.name, e.context.correlationId, attrs);
+  }
+  return p;
+}
+} // namespace margelo::nitro::nitrotracing

package/cpp/NativeConversions.hpp

@@ -0,0 +1,15 @@
+#pragma once
+#include "RecordingOptions.hpp"
+#include "RecordingStats.hpp"
+#include "TraceAttribute.hpp"
+#include "TracePage.hpp"
+#include "core/TraceTypes.hpp"
+namespace margelo::nitro::nitrotracing {
+tracingcore::Context toCore(const std::string &name, const std::string &id,
+                            const std::vector<TraceAttribute> &attributes);
+tracingcore::Config toCore(const RecordingOptions &options);
+tracingcore::Outcome toCore(SpanOutcome outcome);
+TracePage toNative(const tracingcore::Page &page);
+RecordingStats toNative(const tracingcore::Stats &stats);
+uint64_t checkedInteger(double value, double maximum, const char *field);
+} // namespace margelo::nitro::nitrotracing

package/cpp/core/NativeSampler.cpp

@@ -0,0 +1,152 @@
+#include "NativeSampler.hpp"
+#include <algorithm>
+#include <cstdio>
+#include <sys/resource.h>
+#include <unistd.h>
+#if defined(__APPLE__)
+#include <mach/mach.h>
+#endif
+namespace margelo::nitro::tracingcore {
+namespace {
+// A frame taking 1.5x the display interval missed at least one deadline.
+constexpr double slowFactor = 1.5;
+// Android vitals and Sentry both treat >= 700 ms as a frozen frame.
+constexpr double frozenMs = 700;
+} // namespace
+
+FrameMonitor &FrameMonitor::instance() {
+  static FrameMonitor monitor;
+  return monitor;
+}
+void FrameMonitor::setToggle(std::function<void(bool)> toggle) {
+  std::lock_guard lock(mutex_);
+  toggle_ = std::move(toggle);
+}
+bool FrameMonitor::acquire() {
+  std::function<void(bool)> toggle;
+  {
+    std::lock_guard lock(mutex_);
+    if (!toggle_)
+      return false;
+    if (users_++ == 0) {
+      last_ = 0;
+      window_ = {};
+      toggle = toggle_;
+    }
+  }
+  if (toggle)
+    toggle(true);
+  return true;
+}
+void FrameMonitor::release() {
+  std::function<void(bool)> toggle;
+  {
+    std::lock_guard lock(mutex_);
+    if (users_ > 0 && --users_ == 0)
+      toggle = toggle_;
+  }
+  if (toggle)
+    toggle(false);
+}
+void FrameMonitor::onFrame(double timestamp, double expected) {
+  std::lock_guard lock(mutex_);
+  if (last_ > 0 && timestamp > last_) {
+    const double gapMs = (timestamp - last_) * 1000;
+    // Without a platform interval, the shortest recent gap approximates the vsync period.
+    if (expected <= 0)
+      minGap_ = minGap_ <= 0 ? gapMs : std::min(minGap_, gapMs);
+    const double intervalMs = expected > 0 ? expected * 1000 : minGap_;
+    ++window_.frames;
+    window_.intervalMs = intervalMs;
+    window_.maxGapMs = std::max(window_.maxGapMs, gapMs);
+    if (gapMs >= frozenMs)
+      ++window_.frozen;
+    else if (intervalMs > 0 && gapMs > intervalMs * slowFactor)
+      ++window_.slow;
+  }
+  last_ = timestamp;
+}
+FrameMonitor::Window FrameMonitor::take() {
+  std::lock_guard lock(mutex_);
+  const auto window = window_;
+  window_ = {};
+  return window;
+}
+
+double NativeSampler::processCpuMs() {
+  rusage usage{};
+  if (getrusage(RUSAGE_SELF, &usage) != 0)
+    return 0;
+  const auto ms = [](timeval t) { return t.tv_sec * 1000.0 + t.tv_usec / 1000.0; };
+  return ms(usage.ru_utime) + ms(usage.ru_stime);
+}
+double NativeSampler::processMemoryBytes() {
+#if defined(__APPLE__)
+  task_vm_info_data_t info{};
+  mach_msg_type_number_t count = TASK_VM_INFO_COUNT;
+  if (task_info(mach_task_self(), TASK_VM_INFO, reinterpret_cast<task_info_t>(&info), &count) == KERN_SUCCESS)
+    return static_cast<double>(info.phys_footprint);
+  return 0;
+#else
+  long pages = 0, resident = 0;
+  FILE *file = std::fopen("/proc/self/statm", "r");
+  if (!file)
+    return 0;
+  const bool read = std::fscanf(file, "%ld %ld", &pages, &resident) == 2;
+  std::fclose(file);
+  return read ? static_cast<double>(resident) * static_cast<double>(sysconf(_SC_PAGESIZE)) : 0;
+#endif
+}
+
+NativeSampler::NativeSampler(std::shared_ptr<Recorder> recorder, double intervalMs, bool frames)
+    : recorder_(std::move(recorder)), intervalMs_(intervalMs), frames_(frames && FrameMonitor::instance().acquire()),
+      thread_([this] { run(); }) {}
+NativeSampler::~NativeSampler() {
+  {
+    std::lock_guard lock(mutex_);
+    stopping_ = true;
+  }
+  wake_.notify_all();
+  thread_.join();
+  if (frames_)
+    FrameMonitor::instance().release();
+}
+void NativeSampler::run() {
+  double lastWall = Recorder::monotonicMilliseconds();
+  double lastCpu = processCpuMs();
+  if (frames_)
+    FrameMonitor::instance().take(); // Discard frames from before this window.
+  std::unique_lock lock(mutex_);
+  while (!wake_.wait_for(lock, std::chrono::duration<double, std::milli>(intervalMs_), [this] { return stopping_; })) {
+    lock.unlock();
+    const double wall = Recorder::monotonicMilliseconds();
+    const double cpu = processCpuMs();
+    const double windowMs = wall - lastWall;
+    const auto context = [&](const char *name) {
+      return Context{name, "", {{"source", "native"}, {"windowMs", std::to_string(static_cast<int>(windowMs))}}};
+    };
+    try {
+      if (windowMs > 0)
+        // Percent of one core: a busy multi-threaded process can exceed 100.
+        recorder_->metric(context("process.cpu"), std::max(0.0, (cpu - lastCpu) / windowMs * 100), "%");
+      if (const double memory = processMemoryBytes(); memory > 0)
+        recorder_->metric(context("process.memory"), memory / (1024 * 1024), "MB");
+      if (frames_) {
+        const auto w = FrameMonitor::instance().take();
+        // Paused display callbacks (background, locked screen) produce no frames: report nothing.
+        if (w.frames > 1 && windowMs > 0) {
+          recorder_->metric(context("ui.fps"), w.frames * 1000 / windowMs, "fps");
+          recorder_->metric(context("ui.frame_gap.max"), w.maxGapMs, "ms");
+          recorder_->metric(context("ui.frames.slow"), static_cast<double>(w.slow), "count");
+          recorder_->metric(context("ui.frames.frozen"), static_cast<double>(w.frozen), "count");
+        }
+      }
+    } catch (...) {
+      return; // Recording stopped or was cleared; the owner joins this thread.
+    }
+    lastWall = wall;
+    lastCpu = cpu;
+    lock.lock();
+  }
+}
+} // namespace margelo::nitro::tracingcore

package/cpp/core/NativeSampler.hpp

@@ -0,0 +1,56 @@
+#pragma once
+#include "Recorder.hpp"
+#include <condition_variable>
+#include <functional>
+#include <memory>
+#include <mutex>
+#include <thread>
+namespace margelo::nitro::tracingcore {
+/** Aggregates main-thread frame callbacks between sampler windows. Process-wide. */
+class FrameMonitor final {
+public:
+  struct Window {
+    uint64_t frames = 0, slow = 0, frozen = 0;
+    double maxGapMs = 0, intervalMs = 0;
+  };
+  static FrameMonitor &instance();
+  /** Platform layer: start/stop display callbacks on the main thread. */
+  void setToggle(std::function<void(bool)> toggle);
+  /** Reference-counted so concurrent recordings share one callback source. */
+  bool acquire();
+  void release();
+  /** Seconds on a monotonic clock; expected frame interval, or 0 to infer it. */
+  void onFrame(double timestampSeconds, double expectedIntervalSeconds);
+  Window take();
+
+private:
+  std::mutex mutex_;
+  std::function<void(bool)> toggle_;
+  int users_ = 0;
+  double last_ = 0, minGap_ = 0;
+  Window window_;
+};
+
+/** Background thread writing CPU, memory and frame windows into a recorder. */
+class NativeSampler final {
+public:
+  NativeSampler(std::shared_ptr<Recorder> recorder, double intervalMs, bool frames);
+  ~NativeSampler();
+  NativeSampler(const NativeSampler &) = delete;
+  NativeSampler &operator=(const NativeSampler &) = delete;
+  /** CPU time used by this process across all threads, in milliseconds. */
+  static double processCpuMs();
+  /** iOS physical footprint or Android/Linux resident set, in bytes; 0 when unavailable. */
+  static double processMemoryBytes();
+
+private:
+  void run();
+  std::shared_ptr<Recorder> recorder_;
+  double intervalMs_;
+  bool frames_;
+  std::mutex mutex_;
+  std::condition_variable wake_;
+  bool stopping_ = false;
+  std::thread thread_;
+};
+} // namespace margelo::nitro::tracingcore

package/cpp/core/Recorder.cpp

@@ -0,0 +1,218 @@
+#include "Recorder.hpp"
+#include "Retention.hpp"
+#include <algorithm>
+#include <atomic>
+#include <chrono>
+#include <cmath>
+#include <stdexcept>
+namespace margelo::nitro::tracingcore {
+namespace {
+std::atomic<uint64_t> nextSession{0};
+}
+double Recorder::monotonicMilliseconds() {
+  return std::chrono::duration<double, std::milli>(std::chrono::steady_clock::now().time_since_epoch()).count();
+}
+Recorder::Recorder(Config c, Clock clock)
+    : config_(c), clock_(std::move(clock)), origin_(clock_()),
+      wallOrigin_(
+          std::chrono::duration<double, std::milli>(std::chrono::system_clock::now().time_since_epoch()).count()),
+      sessionId_(std::to_string(static_cast<uint64_t>(wallOrigin_)) + "-" + std::to_string(++nextSession)) {
+  if (c.maxEvents < 1 || c.maxEvents > 100000 || c.maxBytes < 1024 || c.maxBytes > 67108864 || c.maxActiveSpans < 1 ||
+      c.maxActiveSpans > 10000 || !std::isfinite(c.spanTimeoutMs) || c.spanTimeoutMs < 1)
+    throw std::invalid_argument("Invalid recording limits: events 1..100000, bytes 1024..67108864, active spans "
+                                "1..10000, finite timeout >=1ms");
+}
+double Recorder::now() const { return clock_() - origin_; }
+void Recorder::requireRecording() const {
+  if (!recording_)
+    throw std::runtime_error("Recording has stopped");
+}
+std::string Recorder::spanId(uint64_t token) const {
+  return token == 0 ? "" : sessionId_ + ":" + std::to_string(token);
+}
+namespace {
+bool isMetric(const Event &e) { return std::holds_alternative<MetricData>(e.data); }
+} // namespace
+void Recorder::drop(const Event &e) {
+  ++dropped_;
+  if (std::holds_alternative<SpanData>(e.data))
+    ++droppedSpans_;
+  else if (std::holds_alternative<MarkData>(e.data))
+    ++droppedMarks_;
+  else
+    ++droppedMetrics_;
+}
+void Recorder::evict() {
+  metrics_ -= isMetric(events_.front());
+  bytes_ -= eventBytes(events_.front());
+  drop(events_.front());
+  events_.pop_front();
+}
+bool Recorder::reserve(size_t bytes) {
+  while (!events_.empty() && bytes_ + bytes > config_.maxBytes)
+    evict();
+  return bytes_ + bytes <= config_.maxBytes;
+}
+void Recorder::append(Event e) {
+  e.sequence = ++sequence_;
+  const auto size = eventBytes(e);
+  if (size > config_.maxBytes) {
+    drop(e);
+    return;
+  }
+  // Periodic samples may fill at most half the buffer, so they replace older samples
+  // instead of evicting spans and marks from long sessions. Metric series are rolling
+  // windows by design, so replacing a sample does not count as lost history.
+  if (isMetric(e) && metrics_ >= std::max<size_t>(1, config_.maxEvents / 2)) {
+    const auto oldest = std::find_if(events_.begin(), events_.end(), isMetric);
+    bytes_ -= eventBytes(*oldest);
+    events_.erase(oldest);
+    --metrics_;
+  }
+  while (!events_.empty() && events_.size() >= config_.maxEvents)
+    evict();
+  if (!reserve(size)) {
+    drop(e);
+    return;
+  }
+  bytes_ += size;
+  metrics_ += isMetric(e);
+  events_.push_back(std::move(e));
+}
+uint64_t Recorder::startSpan(Context c, std::string parent) {
+  validateContext(c);
+  if (parent.size() > sessionId_.size() + 8 + 128 || (!parent.empty() && parent.rfind(sessionId_ + ":", 0) != 0))
+    throw std::invalid_argument("Parent span must belong to this recording");
+  std::lock_guard lock(mutex_);
+  requireRecording();
+  const double time = now();
+  expire(time);
+  const size_t size = sizeof(Active) + contextBytes(c) + parent.capacity() + 64;
+  if (active_.size() >= config_.maxActiveSpans || size > config_.maxBytes || !reserve(size)) {
+    ++dropped_;
+    ++droppedSpans_;
+    return 0;
+  }
+  const auto token = ++token_;
+  active_.emplace(token, Active{time, std::move(c), std::move(parent), size});
+  bytes_ += size;
+  return token;
+}
+void Recorder::finish(std::map<uint64_t, Active>::iterator it, Outcome outcome, double time) {
+  auto active = std::move(it->second);
+  const auto token = it->first;
+  bytes_ -= active.bytes;
+  active_.erase(it);
+  append(Event{0, active.start, std::move(active.context),
+               SpanData{spanId(token), std::move(active.parent), time - active.start, outcome}});
+}
+void Recorder::expire(double time) {
+  while (!active_.empty() && time - active_.begin()->second.start >= config_.spanTimeoutMs)
+    finish(active_.begin(), Outcome::Interrupted, active_.begin()->second.start + config_.spanTimeoutMs);
+}
+std::string Recorder::recordSpan(Context c, std::string parent, double start, double duration, Outcome outcome,
+                                 std::string sourceId, std::string sourceParent) {
+  validateContext(c);
+  if (!std::isfinite(start) || start < 0 || !std::isfinite(duration) || duration < 0 ||
+      !std::isfinite(start + duration))
+    throw std::invalid_argument("Imported span requires finite nonnegative start and duration");
+  if (parent.size() > sessionId_.size() + 8 + 128 || (!parent.empty() && parent.rfind(sessionId_ + ":", 0) != 0))
+    throw std::invalid_argument("Parent span must belong to this recording");
+  std::lock_guard lock(mutex_);
+  requireRecording();
+  expire(now());
+  if (sourceId.size() > 128 || sourceParent.size() > 128 || (!sourceParent.empty() && sourceId.empty()))
+    throw std::invalid_argument("Source span IDs must be <=128 bytes and a source parent requires a source ID");
+  const auto id = sourceId.empty() ? spanId(++token_) : sessionId_ + ":source:" + sourceId;
+  if (!sourceParent.empty())
+    parent = sessionId_ + ":source:" + sourceParent;
+  append(Event{0, start, std::move(c), SpanData{id, std::move(parent), duration, outcome}});
+  return id;
+}
+void Recorder::endSpan(uint64_t token, Outcome outcome) {
+  if (token == 0)
+    return;
+  std::lock_guard lock(mutex_);
+  const double time = now();
+  expire(time);
+  auto it = active_.find(token);
+  if (it != active_.end())
+    finish(it, outcome, time);
+}
+void Recorder::mark(Context c, std::optional<double> timestamp) {
+  if (timestamp && (!std::isfinite(*timestamp) || *timestamp < 0))
+    throw std::invalid_argument("Mark timestamp must be finite and nonnegative");
+  validateContext(c);
+  std::lock_guard lock(mutex_);
+  requireRecording();
+  const double time = now();
+  expire(time);
+  append(Event{0, timestamp.value_or(time), std::move(c), MarkData{}});
+}
+void Recorder::metric(Context c, double value, std::string unit, std::optional<double> timestamp) {
+  if (timestamp && (!std::isfinite(*timestamp) || *timestamp < 0))
+    throw std::invalid_argument("Metric timestamp must be finite and nonnegative");
+  validateContext(c);
+  if (!std::isfinite(value) || unit.empty() || unit.size() > 64)
+    throw std::invalid_argument("Metric needs finite value and a 1-64 byte unit");
+  std::lock_guard lock(mutex_);
+  requireRecording();
+  const double time = now();
+  expire(time);
+  append(Event{0, timestamp.value_or(time), std::move(c), MetricData{value, std::move(unit)}});
+}
+Page Recorder::read(uint64_t after, size_t limit) {
+  if (limit < 1 || limit > 1000)
+    throw std::invalid_argument("Page limit must be 1..1000");
+  std::lock_guard lock(mutex_);
+  expire(now());
+  Page p{{}, after, events_.empty() ? sequence_ + 1 : events_.front().sequence, dropped_};
+  auto it = std::upper_bound(events_.begin(), events_.end(), after,
+                             [](uint64_t seq, const Event &event) { return seq < event.sequence; });
+  for (; it != events_.end() && p.events.size() < limit; ++it) {
+    p.events.push_back(*it);
+    p.nextSequence = it->sequence;
+  }
+  return p;
+}
+Stats Recorder::statsAt(double time) const {
+  return {sessionId_, wallOrigin_,    time,          recording_,    events_.size(), bytes_,
+          dropped_,   active_.size(), droppedSpans_, droppedMarks_, droppedMetrics_};
+}
+Stats Recorder::stats() {
+  std::lock_guard lock(mutex_);
+  const auto time = now();
+  expire(time);
+  return statsAt(time);
+}
+Snapshot Recorder::snapshot() {
+  std::lock_guard lock(mutex_);
+  const auto time = now();
+  expire(time);
+  return {statsAt(time),
+          {std::vector<Event>(events_.begin(), events_.end()), sequence_,
+           events_.empty() ? sequence_ + 1 : events_.front().sequence, dropped_}};
+}
+void Recorder::stop() {
+  std::lock_guard lock(mutex_);
+  if (!recording_)
+    return;
+  const auto time = now();
+  expire(time);
+  recording_ = false;
+  while (!active_.empty())
+    finish(active_.begin(), Outcome::Interrupted, time);
+}
+void Recorder::clear() {
+  std::lock_guard lock(mutex_);
+  recording_ = false;
+  active_.clear();
+  events_.clear();
+  bytes_ = 0;
+  metrics_ = 0;
+}
+size_t Recorder::memorySize() const {
+  std::lock_guard lock(mutex_);
+  return sizeof(Recorder) + bytes_;
+}
+} // namespace margelo::nitro::tracingcore