Extend diagnostic-timing-stats to optionally show counts (xapi-project#6703)

The Host.get_diagnostic_timing_stats API call shows mean and SD of time
spent. We would like to know how many samples were used to this but
can't simmply add this because it could break existing clients. Add an
optional flag to include them with a default that maintains the existing
behaviour.

The `n=xxx` is new and depends on the `counts=true` flag.

```
[root@eu1-dt034 ~]# xe  diagnostic-timing-stats counts=true | head
host-uuid                                                                      : 9eb655ef-3249-46fb-beab-d7d12c0acbaf
                                                                host-name-label: eu1-dt034
                                                         Stats reporting thread: 0.000136 [sd = 0.000000, n=1]
                                    Sync UEFI certificates on host with XAPI db: 0.012959 [sd = 0.000000, n=1]
                                                                   Db_gc: PGPUs: 0.000006 [sd = 0.000001, n=18]
                                                                Db_gc: Consoles: 0.000020 [sd = 0.000003, n=18]
                                       Cleanup attached pool_updates when start: 0.000003 [sd = 0.000000, n=1]
                                 Cancel_tasks.update_all_allowed_operations: SR: 0.000824 [sd = 0.000000, n=1]
                                                                   Db_gc: VTPMs: 0.000001 [sd = 0.000001, n=18]
                                               Initialise monitor configuration: 0.001076 [sd = 0.000000, n=1]

```

Author: lindig

ocaml/database/stats.ml

@@ -68,8 +68,12 @@ let sd (p : Normal_population.t) =
   in
   sqrt v
 
-let string_of (p : Normal_population.t) =
-  Printf.sprintf "%f [sd = %f]" (mean p) (sd p)
+let string_of ?(counts = false) (p : Normal_population.t) =
+  match counts with
+  | false ->
+      Printf.sprintf "%f [sd = %f]" (mean p) (sd p)
+  | true ->
+      Printf.sprintf "%f [sd = %f, n=%d]" (mean p) (sd p) p.n
 
 (** [sample thing t] records new time [t] for population named [thing] *)
 let sample (name : string) (x : float) : unit =
@@ -104,7 +108,7 @@ let time_this (name : string) f =
           name
   )
 
-let summarise () =
+let summarise ?(counts = false) () =
   with_lock timings_m (fun () ->
-      Hashtbl.fold (fun k v acc -> (k, string_of v) :: acc) timings []
+      Hashtbl.fold (fun k v acc -> (k, string_of ~counts v) :: acc) timings []
   )

ocaml/database/stats.mli

@@ -12,7 +12,7 @@
  * GNU Lesser General Public License for more details.
  *)
 
-val summarise : unit -> (string * string) list
+val summarise : ?counts:bool -> unit -> (string * string) list
 (** Produce a string name -> string mean, standard deviation summary for each population *)
 
 val time_this : string -> (unit -> 'a) -> 'a

ocaml/idl/datamodel_host.ml

@@ -940,9 +940,26 @@ let get_diagnostic_timing_stats =
       ]
     ~name:"get_diagnostic_timing_stats"
     ~doc:"Return timing statistics for diagnostic purposes"
-    ~params:[(Ref _host, "host", "The host to interrogate")]
     ~result:(Map (String, String), "population name to summary map")
-    ~hide_from_docs:true ~allowed_roles:_R_READ_ONLY ()
+    ~hide_from_docs:true ~allowed_roles:_R_READ_ONLY
+    ~versioned_params:
+      [
+        {
+          param_type= Ref _host
+        ; param_name= "host"
+        ; param_doc= "The host"
+        ; param_release= miami_release
+        ; param_default= None
+        }
+      ; {
+          param_type= Bool
+        ; param_name= "counts"
+        ; param_doc= "Include counts in the result"
+        ; param_release= numbered_release "25.33.0"
+        ; param_default= Some (VBool false)
+        }
+      ]
+    ()
 
 let create_new_blob =
   call ~name:"create_new_blob"

ocaml/xapi-cli-server/cli_operations.ml

@@ -195,14 +195,15 @@ let get_file_or_fail fd desc filename =
   | Some chunks ->
       chunks
 
-let diagnostic_timing_stats printer rpc session_id _params =
+let diagnostic_timing_stats printer rpc session_id params =
+  let counts = get_bool_param params "counts" in
   let table_of_host host =
     [
       ("host-uuid", Client.Host.get_uuid ~rpc ~session_id ~self:host)
     ; ("host-name-label", Client.Host.get_name_label ~rpc ~session_id ~self:host)
     ]
     @
-    try Client.Host.get_diagnostic_timing_stats ~rpc ~session_id ~host
+    try Client.Host.get_diagnostic_timing_stats ~rpc ~session_id ~host ~counts
     with e -> [("Error", Api_errors.to_string e)]
   in
   let all = List.map table_of_host (Client.Host.get_all ~rpc ~session_id) in

ocaml/xapi/xapi_host.ml

@@ -1365,8 +1365,8 @@ let get_thread_diagnostics ~__context ~host:_ =
 let sm_dp_destroy ~__context ~host:_ ~dp ~allow_leak =
   Storage_access.dp_destroy ~__context dp allow_leak
 
-let get_diagnostic_timing_stats ~__context ~host:_ =
-  Xapi_database.Stats.summarise ()
+let get_diagnostic_timing_stats ~__context ~host:_ ~counts =
+  Xapi_database.Stats.summarise ~counts ()
 
 (* CP-825: Serialize execution of host-enable-extauth and host-disable-extauth *)
 (* We need to protect against concurrent execution of the extauth-hook script and host.enable/disable extauth, *)

ocaml/xapi/xapi_host.mli

@@ -207,7 +207,7 @@ val get_system_status_capabilities :
   __context:Context.t -> host:API.ref_host -> string
 
 val get_diagnostic_timing_stats :
-  __context:Context.t -> host:'b -> (string * string) list
+  __context:Context.t -> host:'b -> counts:bool -> (string * string) list
 
 val set_hostname_live :
   __context:Context.t -> host:[`host] Ref.t -> hostname:string -> unit