RUN-636: Add per-call context instruction counter

spec/changelog.adoc

@@ -4,6 +4,7 @@
 [#unreleased]
 === ∞ (unreleased)
 * Spec: User delegations include a principal scope
+* Spec: Add per-call context performance counter
 
 [#0_18_9]
 === 0.18.9 (2022-12-06)

spec/index.adoc

@@ -1461,19 +1461,17 @@ Passing zero as an argument to the function deactivates the timer and thus preve
 [#system-api-performance-counter]
 === Performance counter
 
-The canister can query the "performance counter", which is a deterministic monotonically increasing integer approximating the amount of work the canister has done since the beginning of the current execution.
+The canister can query the "performance counter" to get deterministic integer approximations of canister activities. Developers might use these counters to profile and optimize the canister performance.
 
 `+ic0.performance_counter : (counter_type : i32) -> i64+`
 
 The argument `type` decides which performance counter to return:
 
-* 0 : instruction counter. The number of WebAssembly instructions the system has determined that the canister has executed.
+* 0 : current execution instruction counter. The number of WebAssembly instructions the canister has executed since the beginning of the current execution. The system resets this counter at the beginning of each <<rule-message-execution>>.
 
-In the future, we might expose more performance counters.
+* 1 : per-call context instruction counter. The number of WebAssembly instructions the canister has executed since the creation of the current call context. The system sets this counter to zero at the <<call-context-creation>>. The counter is monotonically increasing across a few <<rule-message-execution>>, until the <<call-context-removal>>.
 
-The system resets the counter at the beginning of each <<entry-points>> invocation.
-
-The main purpose of this counter is to facilitate in-canister performance profiling.
+In the future, the IC might expose more performance counters.
 
 [#system-api-controller-check]
 === Controller check
@@ -2857,6 +2855,7 @@ State after::
 ....
 
 
+[#call-context-creation]
 ==== Call context creation
 
 Before invoking a heartbeat, a global timer, or a message to a public entry point, a call context is created for bookkeeping purposes.
@@ -3169,6 +3168,7 @@ S with
       }
 ....
 
+[#call-context-removal]
 ==== Call context removal
 
 If there is no call, downstream call context, or response that references a call context, and the call context does not need to respond (because it has already responded or its origin is a system task that does not await a response), then the call context can be removed.