(core) New API to collect timing information from formula evaluation.

Summary:
- /timing/start endpoint to start collecting information
- /timing/stop endpoint to stop collecting
- /timing to retrive data gatherd so far

Timings are collected for all columns (including hidden/helpers/system)

Test Plan: Added new

Reviewers: paulfitz

Reviewed By: paulfitz

Differential Revision: https://phab.getgrist.com/D4230

app/common/ActiveDocAPI.ts

@@ -288,6 +288,48 @@ export interface RemoteShareInfo {
   key: string;
 }
 
+/**
+ * Metrics gathered during formula calculations.
+ */
+export interface TimingInfo {
+  /**
+   * Total time spend evaluating a formula.
+   */
+  total: number;
+  /**
+   * Number of times the formula was evaluated (for all rows).
+   */
+  count: number;
+  average: number;
+  max: number;
+}
+
+/**
+ * Metrics attached to a particular column in a table. Contains also marks if they were gathered.
+ * Currently we only mark the `OrderError` exception (so when formula calculation was restarted due to
+ * order dependency).
+ */
+export interface FormulaTimingInfo extends TimingInfo {
+  tableId: string;
+  colId: string;
+  marks?: Array<TimingInfo & {name: string}>;
+}
+
+/*
+ * Status of timing info collection. Contains intermediate results if engine is not busy at the moment.
+ */
+export interface TimingStatus {
+  /**
+   * If true, timing info is being collected.
+   */
+  status: boolean;
+  /**
+   * Will be undefined if we can't get the timing info (e.g. if the document is locked by other call).
+   * Otherwise, contains the intermediate results gathered so far.
+   */
+  timing?: FormulaTimingInfo[];
+}
+
 export interface ActiveDocAPI {
   /**
    * Closes a document, and unsubscribes from its userAction events.
@@ -449,5 +491,18 @@ export interface ActiveDocAPI {
    */
   getUsersForViewAs(): Promise<PermissionDataWithExtraUsers>;
 
-  getShare(linkId: string): Promise<RemoteShareInfo>;
+  /**
+   * Get a share info associated with the document.
+   */
+  getShare(linkId: string): Promise<RemoteShareInfo|null>;
+
+  /**
+   * Starts collecting timing information from formula evaluations.
+   */
+  startTiming(): Promise<void>;
+
+  /**
+   * Stops collecting timing information and returns the collected data.
+   */
+  stopTiming(): Promise<TimingInfo[]>;
 }

app/common/UserAPI.ts

@@ -507,6 +507,16 @@ export interface DocAPI {
   flushWebhook(webhookId: string): Promise<void>;
 
   getAssistance(params: AssistanceRequest): Promise<AssistanceResponse>;
+  /**
+   * Check if the document is currently in timing mode.
+   */
+  timing(): Promise<{status: boolean}>;
+  /**
+   * Starts recording timing information for the document. Throws exception if timing is already
+   * in progress or you don't have permission to start timing.
+   */
+  startTiming(): Promise<void>;
+  stopTiming(): Promise<void>;
 }
 
 // Operations that are supported by a doc worker.
@@ -1121,6 +1131,18 @@ export class DocAPIImpl extends BaseAPI implements DocAPI {
     });
   }
 
+  public async timing(): Promise<{status: boolean}> {
+    return this.requestJson(`${this._url}/timing`);
+  }
+
+  public async startTiming(): Promise<void> {
+    await this.request(`${this._url}/timing/start`, {method: 'POST'});
+  }
+
+  public async stopTiming(): Promise<void> {
+    await this.request(`${this._url}/timing/stop`, {method: 'POST'});
+  }
+
   private _getRecords(tableId: string, endpoint: 'data' | 'records', options?: GetRowsParams): Promise<any> {
     const url = new URL(`${this._url}/tables/${tableId}/${endpoint}`);
     if (options?.filters) {