RUN-636: Add call context instruction counter (#185)

spec/_attachments/interface-spec-changelog.md

@@ -7,6 +7,7 @@
 * Add a system API method to burn cycles of the canister that calls this method.
 * Add a check that a canister receiving an ingress message is Running before the ingress message is marked as Received.
 * Increase the maximum number of globals in a canister's WASM.
+* Add per-call context performance counter.
 
 ### 0.21.0 (2023-09-18) {#0_21_0}
 * Canister cycle balance cannot decrease below the freezing limit after executing `install_code` on the management canister.

spec/index.md

@@ -1793,19 +1793,21 @@ Passing zero as an argument to the function deactivates the timer and thus preve
 
 ### Performance counter {#system-api-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 one of the "performance counters", which is a deterministic monotonically increasing integer approximating the amount of work the canister has done. Developers might use this data 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 [Message execution](#rule-message-execution).
 
-In the future, we might expose more performance counters.
+-   1 : call context instruction counter.
 
-The system resets the counter at the beginning of each [Entry points](#entry-points) invocation.
+    - For replicated message execution, it is the number of WebAssembly instructions the canister has executed within the call context of the current [Message execution](#rule-message-execution) since [Call context creation](#call-context-creation). The counter monotonically increases across all [message executions](#rule-message-execution) in the call context until the corresponding [call context is removed](#call-context-removal).
 
-The main purpose of this counter is to facilitate in-canister performance profiling.
+    - For non-replicated message execution, it is the number of WebAssembly instructions the canister has executed within the corresponding `composite_query_helper` in [Query call](#query-call). The counter monotonically increases across the executions of the composite query method and the composite query callbacks until the corresponding `composite_query_helper` returns (ignoring WebAssembly instructions executed within any further downstream calls of `composite_query_helper`).
+
+In the future, the IC might expose more performance counters.
 
 ### Replicated execution check {#system-api-replicated-execution-check}
 
@@ -3248,7 +3250,7 @@ messages = Older_messages · Younger_messages  ·
 
 ```
 
-#### Call context creation
+#### 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. For these invocations the canister must be running (so not stopped or stopping). Additionally, these invocations only happen for "real" canisters, not the IC management canister.
 
@@ -3631,7 +3633,7 @@ S with
 
 ```
 
-#### Call context removal
+#### 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.
 
@@ -5094,7 +5096,7 @@ S with
 
 ```
 
-#### Query call
+#### Query call {#query-call}
 
 Canister query calls to `/api/v2/canister/<ECID>/query` can be executed directly. They can only be executed against non-empty canisters which have a status of `Running` and are also not frozen.