update readme

README.md

@@ -1,6 +1,7 @@
 # Catapult [![build](https://github.com/imandra-ai/catapult/actions/workflows/main.yml/badge.svg)](https://github.com/imandra-ai/catapult/actions/workflows/main.yml)
 
-This is a tracing library for OCaml, based on the
+This is a collection of tracing _backends_ for
+[ocaml-trace](https://github.com/c-cube/ocaml-trace/), ultimately producing
 [Catapult/TEF](https://docs.google.com/document/d/1CvAClvFfyA5R-PhYUmn5OOQtYMH4h6I0nSsKchNAySU/)
 trace format.
 
@@ -12,12 +13,46 @@ The traces are `.json` files (or compressed `.json.gz`). They can be viewed in:
 
 ## Usage
 
-The core library is `catapult`. It's a small set of probes that can be
-inserted in your code, by hand (with meaningful messages if needed).
+Instrument your code using [ocaml-trace](https://github.com/c-cube/ocaml-trace/).
+In the program's entry point, use one of the Catapult libraries
+backend to forward events from [Trace] into the place of your choice.
+
+An example can be found in 'examples/heavy/heavy.ml'
+
+## sqlite
+
+To collect data directly into a local Sqlite database, use something like:
+
+```ocaml
+let main () =̵
+  …
+  let@ writer = Catapult_sqlite.Writer.with_ ~file:!db ~sync:!sync () in
+  Trace.setup_collector (Catapult_sqlite.trace_collector_of_writer writer);
+
+  …
+  (* do the actual work here *)
+```
+
+(assuming this is in scope:
+```ocaml
+let (let@) = (@@)
+```
+)
+
+
+## network client
+
+The library `catapult-client` provides a tracing backend that forwards all events
+(messages, traces, metrics) to a network daemon. The daemon is in the
+`catapult-daemon` package.
+
+The traces can be listed and retrieved using the `catapult-conv` program that
+comes with `catapult-sqlite`.
 
 ## Systemd
 
-An example systemd service file can be found in `src/data/catapult-daemon.service`.
+An example systemd service file for this daemon can
+be found in `src/data/catapult-daemon.service`.
 
 ```systemd
 [Unit]
@@ -36,29 +71,30 @@ RestartSec=10
 WantedBy=default.target
 ```
 
-### Example: "basic"
+## Example: "basic"
 
 A very stupid example (in `examples/basic/basic.ml`), is:
 
 ```ocaml
-module Tr = Catapult.Tracing
+let (let@) = (@@)
 let spf = Printf.sprintf
 
 let rec fake_trace depth =
   if depth>=3 then ()
   else (
     (* the probe is here *)
-    Tr.with_ "step" @@ fun () ->
+    let@ _sp = Trace.with_span ~__FILE__ ~__LINE__ "step" in
     Thread.delay 0.1;
     Printf.printf "fake (depth=%d)\n%!" depth;
     fake_trace (depth+1);
     Thread.delay 0.2;
-    Tr.instant "iteration.done" ~args:["depth", `Int depth];
+    Trace.message "iteration.done" ~data:(fun () -> ["depth", `Int depth]);
   )
 
 let () =
-  (* this just logs into a file. It's not thread safe nor multiprocess-safe. *)
-  Catapult_file.with_setup @@ fun () ->
+  (* address of daemon *)
+  let addr = Catapult_client.addr_of_string_exn "tcp://localhost:1234" in
+  let@() = Catapult_client.with_ ~addr () in
   let n = try int_of_string (Sys.getenv "N") with _ -> 10 in
   Printf.printf "run %d iterations\n%!" n;
 
@@ -67,14 +103,10 @@ let () =
   done
 ```
 
-If run with the `TRACE=1` environment variable set, this will just produce a
-basic trace in the file "trace.json" (otherwise probes will do nothing and keep
-a minimal overhead).
-
 Once opened in chrome://tracing, the trace looks like this:
 ![viewer screenshot](media/viewer1.png)
 
-### Example: "heavy"
+## Example: "heavy"
 
 A more heavy example (used to benchmark a bit the tracing), is in `examples/heavy`.
 
@@ -87,7 +119,7 @@ $ ./daemon.sh
 Then in another terminal:
 
 ```
-$ ./heavy.sh -n=1 --mode=net -j 2
+$ ./heavy.sh -n=1 --mode=net -j 2 --trace-id=mytrace
 use net client tcp://127.0.0.1:6981
 run 1 iterations
 iteration 1
@@ -96,12 +128,12 @@ run 1 iterations
 iteration 1
 
 # list traces
-$ catapult-conv
-…
-catapult-2022-2-16-16-36-18-pid-3229175.dbo
+$ catapult-conv -l
+[…]
+mytrace.db
 
-# convert last trace into a json.gz file
-$ catapult-conv catapult-2022-2-16-16-36-18-pid-3229175.db
+# convert last trace into a file (trace.json.gz)
+$ catapult-conv mytrace.db
 
 $ ls -lh trace.json.gz 
 -rw-r--r-- 1 simon simon 374K Feb 16 11:38 trace.json.gz