react-native-nitro-tracing 0.6.0

package/cpp/core/Recorder.hpp

@@ -0,0 +1,60 @@
+#pragma once
+#include "TraceTypes.hpp"
+#include <deque>
+#include <functional>
+#include <map>
+#include <mutex>
+#include <optional>
+namespace margelo::nitro::tracingcore {
+// A native API independent of JSI; native workers may share this recorder directly.
+class Recorder final {
+public:
+  using Clock = std::function<double()>;
+  explicit Recorder(Config config, Clock clock = monotonicMilliseconds);
+  uint64_t startSpan(Context context, std::string parentSpanId = {});
+  std::string recordSpan(Context context, std::string parent, double start, double duration, Outcome outcome,
+                         std::string sourceId = {}, std::string sourceParent = {});
+  void endSpan(uint64_t token, Outcome outcome);
+  void mark(Context context, std::optional<double> timestamp = {});
+  void metric(Context context, double value, std::string unit, std::optional<double> timestamp = {});
+  Page read(uint64_t afterSequence, size_t limit);
+  Stats stats();
+  Snapshot snapshot();
+  void stop();
+  void clear();
+  std::string spanId(uint64_t token) const;
+  size_t memorySize() const;
+  static double monotonicMilliseconds();
+
+private:
+  struct Active {
+    double start;
+    Context context;
+    std::string parent;
+    size_t bytes;
+  };
+  Config config_;
+  Clock clock_;
+  double origin_;
+  double wallOrigin_;
+  std::string sessionId_;
+  // Protects mutable state shared by JS calls, native producers and snapshot workers.
+  mutable std::mutex mutex_;
+  std::map<uint64_t, Active> active_;
+  std::deque<Event> events_;
+  size_t bytes_ = 0;
+  size_t metrics_ = 0;
+  uint64_t token_ = 0, sequence_ = 0, dropped_ = 0;
+  uint64_t droppedSpans_ = 0, droppedMarks_ = 0, droppedMetrics_ = 0;
+  void drop(const Event &e);
+  bool recording_ = true;
+  double now() const;
+  void requireRecording() const;
+  void expire(double time);
+  void finish(std::map<uint64_t, Active>::iterator it, Outcome outcome, double time);
+  void append(Event event);
+  bool reserve(size_t bytes);
+  void evict();
+  Stats statsAt(double time) const;
+};
+} // namespace margelo::nitro::tracingcore

package/cpp/core/Retention.cpp

@@ -0,0 +1,26 @@
+#include "Retention.hpp"
+#include <stdexcept>
+namespace margelo::nitro::tracingcore {
+void validateContext(const Context &c) {
+  if (c.name.empty() || c.name.size() > 256 || c.correlationId.size() > 256 || c.attributes.size() > 32)
+    throw std::invalid_argument("Trace name must be 1-256 bytes, correlationId <=256 bytes, attributes <=32");
+  for (const auto &a : c.attributes)
+    if (a.key.empty() || a.key.size() > 64 || a.value.size() > 1024)
+      throw std::invalid_argument("Trace attribute key must be 1-64 bytes and value <=1024 bytes");
+}
+size_t contextBytes(const Context &c) {
+  size_t n =
+      sizeof(Context) + c.name.capacity() + c.correlationId.capacity() + c.attributes.capacity() * sizeof(Attribute);
+  for (const auto &a : c.attributes)
+    n += a.key.capacity() + a.value.capacity();
+  return n;
+}
+size_t eventBytes(const Event &e) {
+  size_t n = sizeof(Event) + contextBytes(e.context);
+  if (const auto *s = std::get_if<SpanData>(&e.data))
+    n += s->spanId.capacity() + s->parentSpanId.capacity();
+  if (const auto *m = std::get_if<MetricData>(&e.data))
+    n += m->unit.capacity();
+  return n;
+}
+} // namespace margelo::nitro::tracingcore

package/cpp/core/Retention.hpp

@@ -0,0 +1,7 @@
+#pragma once
+#include "TraceTypes.hpp"
+namespace margelo::nitro::tracingcore {
+void validateContext(const Context &context);
+size_t contextBytes(const Context &context);
+size_t eventBytes(const Event &event);
+} // namespace margelo::nitro::tracingcore

package/cpp/core/TraceJson.cpp

@@ -0,0 +1,214 @@
+#include "TraceJson.hpp"
+#include <algorithm>
+#include <iomanip>
+#include <locale>
+#include <map>
+#include <sstream>
+#include <vector>
+namespace margelo::nitro::tracingcore {
+namespace {
+void quote(std::ostream &o, const std::string &s) {
+  constexpr char hex[] = "0123456789abcdef";
+  o << '"';
+  for (unsigned char c : s) {
+    if (c == '"' || c == '\\')
+      o << '\\' << c;
+    else if (c < 32)
+      o << "\\u00" << hex[c >> 4] << hex[c & 15];
+    else
+      o << c;
+  }
+  o << '"';
+}
+const char *outcomeName(Outcome o) {
+  switch (o) {
+  case Outcome::Success:
+    return "success";
+  case Outcome::Error:
+    return "error";
+  case Outcome::Cancelled:
+    return "cancelled";
+  case Outcome::Interrupted:
+    return "interrupted";
+  }
+  return "unknown";
+}
+void eventJson(std::ostream &o, const Event &e) {
+  o << "{\"sequence\":" << e.sequence << ",\"timestampMs\":" << e.timestampMs << ",\"name\":";
+  quote(o, e.context.name);
+  o << ",\"correlationId\":";
+  quote(o, e.context.correlationId);
+  o << ",\"attributes\":[";
+  bool comma = false;
+  for (const auto &a : e.context.attributes) {
+    if (comma)
+      o << ',';
+    comma = true;
+    o << "{\"key\":";
+    quote(o, a.key);
+    o << ",\"value\":";
+    quote(o, a.value);
+    o << '}';
+  }
+  o << ']';
+  if (const auto *s = std::get_if<SpanData>(&e.data)) {
+    o << ",\"kind\":\"span\",\"spanId\":";
+    quote(o, s->spanId);
+    o << ",\"parentSpanId\":";
+    quote(o, s->parentSpanId);
+    o << ",\"durationMs\":" << s->durationMs << ",\"outcome\":";
+    quote(o, outcomeName(s->outcome));
+  } else if (const auto *m = std::get_if<MetricData>(&e.data)) {
+    o << ",\"kind\":\"metric\",\"value\":" << m->value << ",\"unit\":";
+    quote(o, m->unit);
+  } else
+    o << ",\"kind\":\"mark\"";
+  o << '}';
+}
+const std::string &sourceOf(const Event &e) {
+  static const std::string fallback = "app";
+  for (const auto &a : e.context.attributes)
+    if (a.key == "source" && !a.value.empty())
+      return a.value;
+  return fallback;
+}
+void argsJson(std::ostream &o, const Event &e) {
+  o << "\"args\":{\"correlationId\":";
+  quote(o, e.context.correlationId);
+  for (const auto &a : e.context.attributes) {
+    o << ',';
+    quote(o, a.key);
+    o << ':';
+    quote(o, a.value);
+  }
+  if (const auto *s = std::get_if<SpanData>(&e.data)) {
+    o << ",\"outcome\":";
+    quote(o, outcomeName(s->outcome));
+    o << ",\"spanId\":";
+    quote(o, s->spanId);
+    o << ",\"parentSpanId\":";
+    quote(o, s->parentSpanId);
+  }
+  o << '}';
+}
+/**
+ * Lanes per source where spans either nest or follow each other. Perfetto requires strict
+ * nesting of complete events on one thread, so overlapping siblings get another lane.
+ */
+class Lanes {
+public:
+  int place(const std::string &source, double start, double end) {
+    auto &lanes = bySource_[source];
+    for (auto &lane : lanes) {
+      while (!lane.open.empty() && lane.open.back() <= start)
+        lane.open.pop_back();
+      if (lane.open.empty() || end <= lane.open.back()) {
+        lane.open.push_back(end);
+        return lane.tid;
+      }
+    }
+    lanes.push_back({next_++, {end}});
+    names_.emplace_back(lanes.back().tid, lanes.size() == 1 ? source : source + " #" + std::to_string(lanes.size()));
+    return lanes.back().tid;
+  }
+  int first(const std::string &source) {
+    auto &lanes = bySource_[source];
+    if (lanes.empty()) {
+      lanes.push_back({next_++, {}});
+      names_.emplace_back(lanes.back().tid, source);
+    }
+    return lanes.front().tid;
+  }
+  const std::vector<std::pair<int, std::string>> &names() const { return names_; }
+
+private:
+  struct Lane {
+    int tid;
+    std::vector<double> open;
+  };
+  std::map<std::string, std::vector<Lane>> bySource_;
+  std::vector<std::pair<int, std::string>> names_;
+  int next_ = 1;
+};
+} // namespace
+std::string exportTraceEvents(const Snapshot &s) {
+  std::vector<const Event *> events;
+  for (const auto &e : s.page.events)
+    events.push_back(&e);
+  const auto duration = [](const Event *e) {
+    const auto *span = std::get_if<SpanData>(&e->data);
+    return span ? span->durationMs : 0;
+  };
+  // Parents before children: earlier start first, longer span first on ties.
+  std::stable_sort(events.begin(), events.end(), [&](const Event *a, const Event *b) {
+    return a->timestampMs != b->timestampMs ? a->timestampMs < b->timestampMs : duration(a) > duration(b);
+  });
+  std::ostringstream body;
+  body.imbue(std::locale::classic());
+  body << std::setprecision(17);
+  Lanes lanes;
+  for (const auto *e : events) {
+    const auto &source = sourceOf(*e);
+    const double ts = e->timestampMs * 1000; // Trace Event timestamps are microseconds.
+    body << ",{\"pid\":1,\"name\":";
+    if (const auto *span = std::get_if<SpanData>(&e->data)) {
+      quote(body, e->context.name);
+      body << ",\"cat\":";
+      quote(body, source);
+      body << ",\"ph\":\"X\",\"ts\":" << ts << ",\"dur\":" << span->durationMs * 1000
+           << ",\"tid\":" << lanes.place(source, e->timestampMs, e->timestampMs + span->durationMs) << ',';
+    } else if (const auto *metric = std::get_if<MetricData>(&e->data)) {
+      // Counter tracks are keyed by name, so the unit is part of it.
+      quote(body, e->context.name + " (" + metric->unit + ")");
+      body << ",\"cat\":";
+      quote(body, source);
+      body << ",\"ph\":\"C\",\"ts\":" << ts << ",\"args\":{\"value\":" << metric->value << "}}";
+      continue;
+    } else {
+      quote(body, e->context.name);
+      body << ",\"cat\":";
+      quote(body, source);
+      body << ",\"ph\":\"i\",\"s\":\"t\",\"ts\":" << ts << ",\"tid\":" << lanes.first(source) << ',';
+    }
+    argsJson(body, *e);
+    body << '}';
+  }
+  std::ostringstream o;
+  o.imbue(std::locale::classic());
+  o << std::setprecision(17);
+  o << "{\"displayTimeUnit\":\"ms\",\"otherData\":{\"generator\":\"react-native-nitro-tracing\",\"sessionId\":";
+  quote(o, s.stats.sessionId);
+  o << ",\"startedAtUnixMs\":" << s.stats.startedAtUnixMs << ",\"droppedEvents\":" << s.stats.droppedEvents
+    << ",\"droppedSpans\":" << s.stats.droppedSpans << ",\"droppedMarks\":" << s.stats.droppedMarks
+    << "},\"traceEvents\":[{\"pid\":1,\"ph\":\"M\",\"name\":\"process_name\",\"args\":{\"name\":\"React Native app\"}}";
+  for (const auto &[tid, name] : lanes.names()) {
+    o << ",{\"pid\":1,\"tid\":" << tid << ",\"ph\":\"M\",\"name\":\"thread_name\",\"args\":{\"name\":";
+    quote(o, name);
+    o << "}},{\"pid\":1,\"tid\":" << tid
+      << ",\"ph\":\"M\",\"name\":\"thread_sort_index\",\"args\":{\"sort_index\":" << tid << "}}";
+  }
+  o << body.str() << "]}";
+  return o.str();
+}
+std::string exportJson(const Snapshot &s) {
+  std::ostringstream o;
+  o.imbue(std::locale::classic());
+  o << std::setprecision(17);
+  o << "{\"schemaVersion\":1,\"sessionId\":";
+  quote(o, s.stats.sessionId);
+  o << ",\"startedAtUnixMs\":" << s.stats.startedAtUnixMs << ",\"recording\":" << (s.stats.recording ? "true" : "false")
+    << ",\"activeSpans\":" << s.stats.activeSpans << ",\"droppedEvents\":" << s.stats.droppedEvents
+    << ",\"droppedSpans\":" << s.stats.droppedSpans << ",\"droppedMarks\":" << s.stats.droppedMarks
+    << ",\"droppedMetrics\":" << s.stats.droppedMetrics << ",\"earliestSequence\":" << s.page.earliestSequence
+    << ",\"events\":[";
+  bool comma = false;
+  for (const auto &e : s.page.events) {
+    if (comma)
+      o << ',';
+    comma = true;
+    eventJson(o, e);
+  }
+  o << "]}";
+  return o.str();
+}
+} // namespace margelo::nitro::tracingcore

package/cpp/core/TraceJson.hpp

@@ -0,0 +1,7 @@
+#pragma once
+#include "TraceTypes.hpp"
+namespace margelo::nitro::tracingcore {
+std::string exportJson(const Snapshot &snapshot);
+/** Chrome Trace Event JSON: opens in ui.perfetto.dev and chrome://tracing. */
+std::string exportTraceEvents(const Snapshot &snapshot);
+} // namespace margelo::nitro::tracingcore

package/cpp/core/TraceTypes.hpp

@@ -0,0 +1,62 @@
+#pragma once
+#include <cstdint>
+#include <string>
+#include <variant>
+#include <vector>
+namespace margelo::nitro::tracingcore {
+struct Attribute {
+  std::string key;
+  std::string value;
+};
+struct Context {
+  std::string name;
+  std::string correlationId;
+  std::vector<Attribute> attributes;
+};
+enum class Outcome { Success, Error, Cancelled, Interrupted };
+struct SpanData {
+  std::string spanId;
+  std::string parentSpanId;
+  double durationMs;
+  Outcome outcome;
+};
+struct MarkData {};
+struct MetricData {
+  double value;
+  std::string unit;
+};
+struct Event {
+  uint64_t sequence;
+  double timestampMs;
+  Context context;
+  std::variant<SpanData, MarkData, MetricData> data;
+};
+struct Config {
+  size_t maxEvents;
+  size_t maxBytes;
+  size_t maxActiveSpans;
+  double spanTimeoutMs;
+};
+struct Stats {
+  std::string sessionId;
+  double startedAtUnixMs;
+  double nowMs;
+  bool recording;
+  size_t eventCount;
+  size_t retainedBytes;
+  uint64_t droppedEvents;
+  size_t activeSpans;
+  /** droppedEvents by kind, so a UI can say what history is missing. */
+  uint64_t droppedSpans = 0, droppedMarks = 0, droppedMetrics = 0;
+};
+struct Page {
+  std::vector<Event> events;
+  uint64_t nextSequence;
+  uint64_t earliestSequence;
+  uint64_t droppedEvents;
+};
+struct Snapshot {
+  Stats stats;
+  Page page;
+};
+} // namespace margelo::nitro::tracingcore

package/expo.ts

@@ -0,0 +1,2 @@
+export { createExpoTraceSharing, registerTraceDevMenu } from './src/expo'
+export type { ExpoSharingOptions } from './src/expo'

package/ios/NitroTracingFrameSource.mm

@@ -0,0 +1,35 @@
+#import <QuartzCore/QuartzCore.h>
+#import <UIKit/UIKit.h>
+#include "../cpp/core/NativeSampler.hpp"
+
+using margelo::nitro::tracingcore::FrameMonitor;
+
+/// Main run loop display callbacks. A callback delayed past its vsync means the main thread
+/// was busy; FrameMonitor turns those gaps into slow and frozen frame counts.
+@interface NitroTracingFrameSource : NSObject
+@property(nonatomic, strong) CADisplayLink *link;
+@end
+
+@implementation NitroTracingFrameSource
+- (void)tick:(CADisplayLink *)link {
+  // targetTimestamp - timestamp is the current frame interval, including ProMotion rates.
+  FrameMonitor::instance().onFrame(link.timestamp, link.targetTimestamp - link.timestamp);
+}
+@end
+
+static NitroTracingFrameSource *source;
+
+__attribute__((constructor)) static void NitroTracingRegisterFrameSource() {
+  FrameMonitor::instance().setToggle([](bool enabled) {
+    dispatch_async(dispatch_get_main_queue(), ^{
+      if (enabled && !source) {
+        source = [NitroTracingFrameSource new];
+        source.link = [CADisplayLink displayLinkWithTarget:source selector:@selector(tick:)];
+        [source.link addToRunLoop:NSRunLoop.mainRunLoop forMode:NSRunLoopCommonModes];
+      } else if (!enabled && source) {
+        [source.link invalidate];
+        source = nil;
+      }
+    });
+  });
+}