README

Opentelemetry

This project provides an API for instrumenting server software usingopentelemetry, as well as connectors to talk to opentelemetry software such asjaeger.

• libraryopentelemetry should be used to instrument your code and possibly libraries. It doesn't communicate with anything except a backend (default: dummy backend);

• libraryopentelemetry-client-ocurl is a backend that communicates via http+protobuf with some collector (otelcol, datadog-agent, etc.) using cURL bindings;

• libraryopentelemetry-client-cohttp-lwt is a backend that communicates via http+protobuf with some collector using cohttp.

License

MIT

Features

• [x] basic traces

• [x] basic metrics

• [x] basic logs

• [ ] nice API

• [x] interface withlwt

• [x] sync collector relying on ocurl

  • [x] batching, perf, etc.

• [ ] async collector relying on ocurl-multi

• [ ] interface withlogs (carry context around)

• [x] implicit scope (via [ambient-context][])

Use

For now, instrument traces/spans, logs, and metrics manually:

module Otel = Opentelemetrylet (let@) f x = f xlet foo () =  let@ scope = Otel.Trace.with_  "foo"      ~attrs:["hello", `String "world"] in  do_work();  Otel.Metrics.(    emit [      gauge ~name:"foo.x" [int 42];    ]);  do_more_work();  ()

Setup

If you're writing a top-level application, you need to perform some initial configuration.

1. Set theservice_name;

2. optionally configure [ambient-context][] with the appropriate storage for your environment — TLS, Lwt, Eio…;

3. and install aCollector (usually by calling your collector'swith_setup function.)

For example, if your application is using Lwt, and you're usingocurl as your collector, you might do something like this:

let main () =  Otel.Globals.service_name := "my_service";  Otel.GC_metrics.basic_setup();  Opentelemetry_ambient_context.set_storage_provider (Opentelemetry_ambient_context_lwt.storage ());  Opentelemetry_client_ocurl.with_setup () @@ fun () ->  (* … *)  foo ();  (* … *)

[ambient-context]: now vendored asopentelemetry.ambient-context, formerlyhttps://v3.ocaml.org/p/ambient-context

Configuration

The library is configurable viaOpentelemetry.Config, via the standard opentelemetry env variables, or with some custom environment variables.

• OTEL_EXPORTER_OTLP_ENDPOINT sets the http endpoint to send signals to

• OTEL_OCAML_DEBUG=1 to print some debug messages from the opentelemetry library ide

• OTEL_RESOURCE_ATTRIBUTES sets a comma separated list of custom resource attributes

Collector opentelemetry-client-ocurl

This is a synchronous collector that uses the http+protobuf format to send signals (metrics, traces, logs) to some other collector (eg.otelcol or the datadog agent).

Do note that this backend uses a thread pool and is incompatible with uses offork on some Unixy systems. See#68 for a possible workaround.

Collector opentelemetry-client-cohttp-lwt

This is a Lwt-friendly collector that uses cohttp to send signals to some other collector (e.g.otelcol). It must be run inside aLwt_main.run scope.

Opentelemetry-trace

The optional libraryopentelemetry.trace, present iftrace is installed, provides a collector fortrace. This collector forwards and translates events fromtrace intoopentelemetry. It's only useful if there also is also a OTEL collector.

License

MIT

Semantic Conventions

Not supported yet.

• [ ]metrics

• [ ]traces

• [ ]resources

1. lwt_ppx>= "2.0"
2. lwt>= "5.3"
3. opentelemetry= version
4. ocaml>= "4.08"
5. dune>= "2.9"

1. alcotestwith-test
2. odocwith-doc
3. cohttp-lwt-unixwith-test

1. opentelemetry-cohttp-lwt>= "0.11.1"

None