From d023f030392662fd95111542c7b9e783cdfe212e Mon Sep 17 00:00:00 2001 From: Simon Cruanes Date: Tue, 9 Jan 2024 12:10:42 -0500 Subject: [PATCH] prepare for 0.6 --- CHANGES.md | 10 ++++++++++ README.md | 12 +++++++----- dune-project | 4 ++-- ppx_trace.opam | 4 ++-- trace-fuchsia.opam | 2 +- trace-tef.opam | 2 +- trace.opam | 2 +- 7 files changed, 24 insertions(+), 12 deletions(-) diff --git a/CHANGES.md b/CHANGES.md index 77a4dd0..1e39398 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -1,4 +1,14 @@ +# 0.6 + +- add `ppx_trace` for easier instrumentation. + * `let%trace span = "foo" in …` will enter a scope `span` named "foo" + * `let%trace () = "foo" in …` will enter a scope named "foo" with a hidden name +- add `trace-fuchsia` backend, which produces traces in the binary format + of [fuchsia](https://fuchsia.dev/fuchsia-src/reference/tracing/trace-format). + These traces are reasonably efficient to produce (~60ns per span on my machines) + and reasonably compact on disk, at least compared to the TEF backend. + # 0.5 - perf: reduce overhead in trace-tef diff --git a/README.md b/README.md index 8657920..a7e030d 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ This small library provides basic types that can be used to instrument a library or application, either by hand or via a ppx. -### Features +## Features - [x] spans - [x] messages @@ -14,7 +14,7 @@ a library or application, either by hand or via a ppx. - [ ] other metrics? - [x] ppx to help instrumentation -### Usage +## Usage To instrument your code, you can simply add `trace` to your dune/opam files, and then write code like such: @@ -138,13 +138,15 @@ In your `library` or `executable` stanza, add: `(preprocess (pps ppx_trace))`. The dependency on `trace.core` is automatically added. You still need to configure a backend to actually do collection. -### Backends +## Backends Concrete tracing or observability formats such as: -- [ ] Fuchsia (see [tracing](https://github.com/janestreet/tracing)) +- [x] Fuchsia (see [the spec](https://fuchsia.dev/fuchsia-src/reference/tracing/trace-format) and [tracing](https://github.com/janestreet/tracing). + Can be opened in https://ui.perfetto.dev) - Catapult - * [x] light bindings here with `trace-tef` + * [x] light bindings here with `trace-tef`. + (Can be opened in https://ui.perfetto.dev) * [ ] richer bindings with [ocaml-catapult](https://github.com/imandra-ai/catapult), with multi-process backends, etc. - [x] Tracy (see [ocaml-tracy](https://github.com/imandra-ai/ocaml-tracy), more specifically `tracy-client.trace`) diff --git a/dune-project b/dune-project index f4113b3..93ba786 100644 --- a/dune-project +++ b/dune-project @@ -2,7 +2,7 @@ (name trace) (generate_opam_files true) -(version 0.5) +(version 0.6) (source (github c-cube/ocaml-trace)) @@ -25,7 +25,7 @@ (package (name ppx_trace) - (synopsis "ppx-based instrumentation for trace") + (synopsis "A ppx-based preprocessor for trace") (depends (ocaml (>= 4.12)) ; we use __FUNCTION__ ppxlib diff --git a/ppx_trace.opam b/ppx_trace.opam index b00d78c..e2a07ca 100644 --- a/ppx_trace.opam +++ b/ppx_trace.opam @@ -1,7 +1,7 @@ # This file is generated by dune, edit dune-project instead opam-version: "2.0" -version: "0.5" -synopsis: "ppx-based instrumentation for trace" +version: "0.6" +synopsis: "A ppx-based preprocessor for trace" maintainer: ["Simon Cruanes"] authors: ["Simon Cruanes"] license: "MIT" diff --git a/trace-fuchsia.opam b/trace-fuchsia.opam index 476cfba..4e9845e 100644 --- a/trace-fuchsia.opam +++ b/trace-fuchsia.opam @@ -1,6 +1,6 @@ # This file is generated by dune, edit dune-project instead opam-version: "2.0" -version: "0.5" +version: "0.6" synopsis: "A high-performance backend for trace, emitting a Fuchsia trace into a file" maintainer: ["Simon Cruanes"] diff --git a/trace-tef.opam b/trace-tef.opam index d984efa..cb35b41 100644 --- a/trace-tef.opam +++ b/trace-tef.opam @@ -1,6 +1,6 @@ # This file is generated by dune, edit dune-project instead opam-version: "2.0" -version: "0.5" +version: "0.6" synopsis: "A simple backend for trace, emitting Catapult/TEF JSON into a file" maintainer: ["Simon Cruanes"] diff --git a/trace.opam b/trace.opam index fbacc24..bd0315a 100644 --- a/trace.opam +++ b/trace.opam @@ -1,6 +1,6 @@ # This file is generated by dune, edit dune-project instead opam-version: "2.0" -version: "0.5" +version: "0.6" synopsis: "A stub for tracing/observability, agnostic in how data is collected" maintainer: ["Simon Cruanes"]