feat: complete benchmark metrics — bug fixes, extended metrics, logging, stats, and tests

Fix reviewer-flagged bugs: add error_code field to timing struct, set t6/error_code
on all error paths, capture prompt tokens from backend, fix JNI local ref leak.

Add extended metrics provider interface, JSON/CSV/log serialization, statistical
analysis with percentiles and outlier detection. All 29 unit tests passing.

>

Author: AmanSwar

sdk/runanywhere-commons/CMakeLists.txt

@@ -276,6 +276,9 @@ set(RAC_CORE_SOURCES
     src/core/rac_error.cpp
     src/core/rac_time.cpp
     src/core/rac_benchmark.cpp
+    src/core/rac_benchmark_metrics.cpp
+    src/core/rac_benchmark_log.cpp
+    src/core/rac_benchmark_stats.cpp
     src/core/rac_memory.cpp
     src/core/rac_logger.cpp
     src/core/rac_audio_utils.cpp

sdk/runanywhere-commons/include/rac/core/rac_benchmark.h

@@ -76,6 +76,13 @@ typedef struct rac_benchmark_timing {
      */
     int32_t status;
 
+    /**
+     * Specific error code when status is not RAC_BENCHMARK_STATUS_SUCCESS.
+     * Uses rac_result_t error codes (e.g., RAC_ERROR_NOT_SUPPORTED).
+     * Set to RAC_SUCCESS (0) when status is RAC_BENCHMARK_STATUS_SUCCESS.
+     */
+    rac_result_t error_code;
+
 } rac_benchmark_timing_t;
 
 // =============================================================================

sdk/runanywhere-commons/include/rac/core/rac_benchmark_log.h

@@ -0,0 +1,87 @@
+/**
+ * @file rac_benchmark_log.h
+ * @brief RunAnywhere Commons - Benchmark Logging and Serialization
+ *
+ * Provides functions to serialize benchmark timing data as JSON or CSV,
+ * and to log benchmark results via the RAC logging system.
+ *
+ * Usage:
+ *   // Log timing summary
+ *   rac_benchmark_timing_log(&timing, "inference_run_1");
+ *
+ *   // Export as JSON
+ *   char* json = rac_benchmark_timing_to_json(&timing);
+ *   // ... use json ...
+ *   free(json);
+ *
+ *   // Export as CSV
+ *   char* header = rac_benchmark_timing_to_csv(NULL, RAC_TRUE);
+ *   char* row = rac_benchmark_timing_to_csv(&timing, RAC_FALSE);
+ *   free(header);
+ *   free(row);
+ */
+
+#ifndef RAC_BENCHMARK_LOG_H
+#define RAC_BENCHMARK_LOG_H
+
+#include "rac/core/rac_benchmark.h"
+#include "rac/core/rac_types.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+// =============================================================================
+// JSON SERIALIZATION
+// =============================================================================
+
+/**
+ * Serializes a benchmark timing struct as a JSON string.
+ *
+ * Includes all timing fields plus derived metrics:
+ * - ttft_ms: Time to first token (t4 - t0)
+ * - prefill_ms: Prefill duration (t3 - t2)
+ * - decode_ms: Decode duration (t5 - t3)
+ * - e2e_ms: End-to-end latency (t6 - t0)
+ * - decode_tps: Decode throughput (output_tokens / decode_ms * 1000)
+ *
+ * @param timing Timing struct to serialize (NULL returns NULL)
+ * @return Heap-allocated JSON string (caller must free()), or NULL on error
+ */
+RAC_API char* rac_benchmark_timing_to_json(const rac_benchmark_timing_t* timing);
+
+// =============================================================================
+// CSV SERIALIZATION
+// =============================================================================
+
+/**
+ * Serializes a benchmark timing struct as a CSV row.
+ *
+ * @param timing Timing struct to serialize (ignored when header is RAC_TRUE)
+ * @param header If RAC_TRUE, returns the CSV header row instead of data
+ * @return Heap-allocated CSV string (caller must free()), or NULL on error
+ */
+RAC_API char* rac_benchmark_timing_to_csv(const rac_benchmark_timing_t* timing, rac_bool_t header);
+
+// =============================================================================
+// LOGGING
+// =============================================================================
+
+/**
+ * Logs a benchmark timing summary via the RAC logging system.
+ *
+ * Outputs key metrics at INFO level under the "Benchmark" category:
+ * - TTFT, prefill time, decode time, E2E latency
+ * - Token counts and throughput
+ * - Status and error code
+ *
+ * @param timing Timing struct to log (NULL is a no-op)
+ * @param label Optional label for this benchmark run (can be NULL)
+ */
+RAC_API void rac_benchmark_timing_log(const rac_benchmark_timing_t* timing, const char* label);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* RAC_BENCHMARK_LOG_H */

sdk/runanywhere-commons/include/rac/core/rac_benchmark_metrics.h

@@ -0,0 +1,119 @@
+/**
+ * @file rac_benchmark_metrics.h
+ * @brief RunAnywhere Commons - Extended Benchmark Metrics
+ *
+ * Defines extended device/platform metrics captured alongside benchmark timing.
+ * Actual metric collection is platform-specific (iOS/Android) and provided
+ * via a callback provider pattern. The C++ layer defines interfaces only.
+ *
+ * Usage:
+ *   // Platform SDK registers a provider during init:
+ *   rac_benchmark_set_metrics_provider(my_provider_fn, my_context);
+ *
+ *   // Commons layer captures metrics at t0 and t6:
+ *   rac_benchmark_extended_metrics_t metrics;
+ *   rac_benchmark_capture_metrics(&metrics);
+ */
+
+#ifndef RAC_BENCHMARK_METRICS_H
+#define RAC_BENCHMARK_METRICS_H
+
+#include "rac/core/rac_types.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+// =============================================================================
+// EXTENDED METRICS STRUCT
+// =============================================================================
+
+/**
+ * Extended device/platform metrics captured during benchmark.
+ *
+ * All fields default to -1 (unavailable) unless the platform provider
+ * populates them. This allows partial metric support across platforms.
+ */
+typedef struct rac_benchmark_extended_metrics {
+    /** Resident memory usage in bytes at capture time (-1 if unavailable) */
+    int64_t memory_usage_bytes;
+
+    /** Peak memory usage in bytes during request (-1 if unavailable) */
+    int64_t memory_peak_bytes;
+
+    /** CPU temperature in Celsius (-1.0 if unavailable) */
+    float cpu_temperature_celsius;
+
+    /** Battery level 0.0-1.0 (-1.0 if unavailable) */
+    float battery_level;
+
+    /** GPU utilization 0-100% (-1.0 if unavailable) */
+    float gpu_utilization_percent;
+
+    /**
+     * Thermal state of the device.
+     *  0 = nominal
+     *  1 = fair
+     *  2 = serious
+     *  3 = critical
+     * -1 = unavailable
+     */
+    int32_t thermal_state;
+
+} rac_benchmark_extended_metrics_t;
+
+// =============================================================================
+// METRICS PROVIDER CALLBACK
+// =============================================================================
+
+/**
+ * Callback type for platform-specific metrics collection.
+ *
+ * The platform SDK (Swift/Kotlin) implements this to fill in
+ * whatever device metrics are available on that platform.
+ *
+ * @param out Metrics struct to populate (pre-initialized to unavailable values)
+ * @param user_data Platform context passed during registration
+ */
+typedef void (*rac_benchmark_metrics_provider_fn)(rac_benchmark_extended_metrics_t* out,
+                                                   void* user_data);
+
+// =============================================================================
+// METRICS API
+// =============================================================================
+
+/**
+ * Registers a platform-specific metrics provider.
+ *
+ * Call this during SDK initialization. Only one provider can be active.
+ * Setting a new provider replaces the previous one.
+ * Pass NULL to unregister.
+ *
+ * @param provider Metrics provider callback (NULL to unregister)
+ * @param user_data Platform context passed to provider calls
+ */
+RAC_API void rac_benchmark_set_metrics_provider(rac_benchmark_metrics_provider_fn provider,
+                                                 void* user_data);
+
+/**
+ * Captures current device metrics using the registered provider.
+ *
+ * If no provider is registered, all fields are set to unavailable (-1).
+ * Thread-safe: can be called from any thread.
+ *
+ * @param out Metrics struct to populate (must not be NULL)
+ */
+RAC_API void rac_benchmark_capture_metrics(rac_benchmark_extended_metrics_t* out);
+
+/**
+ * Initializes an extended metrics struct to unavailable values.
+ *
+ * @param metrics Metrics struct to initialize (must not be NULL)
+ */
+RAC_API void rac_benchmark_extended_metrics_init(rac_benchmark_extended_metrics_t* metrics);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* RAC_BENCHMARK_METRICS_H */

sdk/runanywhere-commons/include/rac/core/rac_benchmark_stats.h

@@ -0,0 +1,157 @@
+/**
+ * @file rac_benchmark_stats.h
+ * @brief RunAnywhere Commons - Benchmark Statistical Analysis
+ *
+ * Collects benchmark timing observations and computes statistical summaries
+ * including percentiles (P50/P95/P99), mean, stddev, and outlier detection.
+ *
+ * Usage:
+ *   rac_benchmark_stats_handle_t stats;
+ *   rac_benchmark_stats_create(&stats);
+ *
+ *   // Record observations
+ *   rac_benchmark_stats_record(stats, &timing1);
+ *   rac_benchmark_stats_record(stats, &timing2);
+ *
+ *   // Get summary
+ *   rac_benchmark_summary_t summary;
+ *   rac_benchmark_stats_get_summary(stats, &summary);
+ *
+ *   // Export as JSON
+ *   char* json = rac_benchmark_stats_summary_to_json(&summary);
+ *   free(json);
+ *
+ *   rac_benchmark_stats_destroy(stats);
+ */
+
+#ifndef RAC_BENCHMARK_STATS_H
+#define RAC_BENCHMARK_STATS_H
+
+#include "rac/core/rac_benchmark.h"
+#include "rac/core/rac_types.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+// =============================================================================
+// STATS HANDLE (OPAQUE)
+// =============================================================================
+
+/** Opaque handle for a benchmark stats collector */
+typedef void* rac_benchmark_stats_handle_t;
+
+// =============================================================================
+// SUMMARY STRUCT
+// =============================================================================
+
+/**
+ * Statistical summary of collected benchmark observations.
+ *
+ * All time values are in milliseconds. Throughput is in tokens/second.
+ * Fields are 0 if no valid observations were recorded for that metric.
+ */
+typedef struct rac_benchmark_summary {
+    /** Number of observations recorded */
+    int32_t count;
+
+    // Time to First Token stats (t4 - t0)
+    double ttft_p50_ms;
+    double ttft_p95_ms;
+    double ttft_p99_ms;
+    double ttft_min_ms;
+    double ttft_max_ms;
+    double ttft_mean_ms;
+    double ttft_stddev_ms;
+
+    // Prefill duration stats (t3 - t2)
+    double prefill_p50_ms;
+    double prefill_p95_ms;
+    double prefill_p99_ms;
+
+    // Decode throughput stats (output_tokens / (t5 - t3) * 1000)
+    double decode_tps_p50;
+    double decode_tps_p95;
+    double decode_tps_p99;
+
+    // End-to-end latency stats (t6 - t0)
+    double e2e_p50_ms;
+    double e2e_p95_ms;
+    double e2e_p99_ms;
+
+    /** Number of observations where E2E > mean + 2*stddev */
+    int32_t outlier_count;
+
+} rac_benchmark_summary_t;
+
+// =============================================================================
+// STATS COLLECTOR API
+// =============================================================================
+
+/**
+ * Creates a new benchmark stats collector.
+ *
+ * @param out_handle Output: collector handle
+ * @return RAC_SUCCESS or RAC_ERROR_NULL_POINTER
+ */
+RAC_API rac_result_t rac_benchmark_stats_create(rac_benchmark_stats_handle_t* out_handle);
+
+/**
+ * Destroys a stats collector and frees all associated memory.
+ *
+ * @param handle Collector handle (NULL is a no-op)
+ */
+RAC_API void rac_benchmark_stats_destroy(rac_benchmark_stats_handle_t handle);
+
+/**
+ * Records a benchmark timing observation.
+ *
+ * Only observations with status == RAC_BENCHMARK_STATUS_SUCCESS are recorded.
+ * Derived metrics (TTFT, prefill, decode TPS, E2E) are extracted and stored.
+ *
+ * Thread-safe: can be called from any thread.
+ *
+ * @param handle Collector handle
+ * @param timing Timing struct to record
+ */
+RAC_API void rac_benchmark_stats_record(rac_benchmark_stats_handle_t handle,
+                                         const rac_benchmark_timing_t* timing);
+
+/**
+ * Resets the collector, discarding all recorded observations.
+ *
+ * @param handle Collector handle
+ */
+RAC_API void rac_benchmark_stats_reset(rac_benchmark_stats_handle_t handle);
+
+/**
+ * Returns the number of recorded observations.
+ *
+ * @param handle Collector handle
+ * @return Observation count (0 if handle is NULL)
+ */
+RAC_API int32_t rac_benchmark_stats_count(rac_benchmark_stats_handle_t handle);
+
+/**
+ * Computes a statistical summary of all recorded observations.
+ *
+ * @param handle Collector handle
+ * @param out_summary Output: summary struct
+ * @return RAC_SUCCESS, RAC_ERROR_NULL_POINTER, or RAC_ERROR_INVALID_STATE (no data)
+ */
+RAC_API rac_result_t rac_benchmark_stats_get_summary(rac_benchmark_stats_handle_t handle,
+                                                      rac_benchmark_summary_t* out_summary);
+
+/**
+ * Serializes a summary struct as a JSON string.
+ *
+ * @param summary Summary struct to serialize (NULL returns NULL)
+ * @return Heap-allocated JSON string (caller must free()), or NULL on error
+ */
+RAC_API char* rac_benchmark_stats_summary_to_json(const rac_benchmark_summary_t* summary);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* RAC_BENCHMARK_STATS_H */