define ExperimentalInternetComputer.performanceCounter : Nat32 -> Nat64;

src/ExperimentalInternetComputer.mo

@@ -55,6 +55,31 @@ module {
     // performance_counter costs around 200 extra instructions, we perform an empty measurement to decide the overhead
     let overhead = pre - init;
     post - pre - overhead
-  }
+  };
+
+  /// Returns the current value of IC _performance counter_ `counter`.
+  ///
+  /// * Counter `0` is the _current execution instruction counter_, counting instructions only since the beginning of the current IC message.
+  ///   This counter is reset to value `0` on shared function entry and every `await`.
+  ///   It is therefore only suitable for measuring the cost of synchronous code.
+  ///
+  /// * Counter '1' is the call context instruction counter for the current call context.
+  ///   For replicated message executing, this excludes the cost of nested IC calls (even to the current canister).
+  ///   For non-replicated messages, such as composite queries, it includes the cost of nested calls.
+  ///   The current value of this counter is preserved across `awaits` (unlike counter `0`).
+  ///
+  /// * The function (currently) traps if 'counter' >= 2.
+  ///
+  /// Consult [Performance Counter](https://internetcomputer.org/docs/current/references/ic-interface-spec#system-api-performance-counter)) for details.
+  ///
+  /// Example:
+  /// ```motoko no-repl
+  /// import IC "mo:base/ExperimentalInternetComputer";
+  ///
+  /// let c1 = IC.performanceCounter(1);
+  /// work();
+  /// let diff : Nat64 = IC.performanceCounter(1) - c1;
+  /// ```
+  public let performanceCounter : (counter : Nat32) -> (value: Nat64) = Prim.performanceCounter;
 
 }