package opentelemetry

  1. Overview
  2. Docs
Instrumentation for https://opentelemetry.io

Install

Dune Dependency

Authors

Maintainers

Sources

opentelemetry-0.7.tbz
sha256=a5de04aa33f5b66e4a63377fd868a839814a4ee229c98c84a04bd49926a38e1d
sha512=f0f9956cb6a605826018794a8fa866b5bda622d2aaa82c4cca5e10262ae163a99512ee22ed4ef0c3af0bb4eeabc7aee736fe7830c585879b029b5ef6d4ef2b05

Description

README

Opentelemetry

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

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

  • library opentelemetry-client-ocurl is a backend that communicates via http+protobuf with some collector (otelcol, datadog-agent, etc.)

License

MIT

Features

  • [x] basic traces

  • [x] basic metrics

  • [x] basic logs

  • [ ] nice API

  • [x] interface with lwt

  • [x] sync collector relying on ocurl

    • [x] batching, perf, etc.

  • [ ] async collector relying on ocurl-multi

  • [ ] interface with logs (carry context around)

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

Use

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

module Otel = Opentelemetry
let (let@) f x = f x

let 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 the service_name;

  2. configure our ambient-context dependency with the appropriate storage for your environment — TLS, Lwt, Eio ... (see their docs for more details);

  3. and install a Collector (usually by calling your collector's with_setup function.)

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

let main () =
  Otel.Globals.service_name := "my_service";
  Otel.GC_metrics.basic_setup();

  Ambient_context.with_storage_provider (Ambient_context_lwt.storage ()) @@ fun () ->
  Opentelemetry_client_ocurl.with_setup () @@ fun () ->
  (* … *)
  foo ();
  (* … *)

Configuration

The library is configurable via Opentelemetry.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).

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 a Lwt_main.run scope.

Opentelemetry-trace

The optional library opentelemetry.trace, present if trace is installed, provides a collector for trace. This collector forwards and translates events from trace into opentelemetry. It's only useful if there also is also a OTEL collector.

License

MIT

Semantic Conventions

Not supported yet.

Dependencies (5)

  1. pbrt >= "3.0" & < "4.0"
  2. ambient-context
  3. ptime
  4. ocaml >= "4.08"
  5. dune >= "2.9"

Dev Dependencies (4)

  1. ocamlformat with-dev-setup & >= "0.24" & < "0.25"
  2. ocaml-lsp-server with-dev-setup
  3. alcotest with-test
  4. odoc with-doc

Conflicts (1)

  1. trace < "0.4" | >= "0.7"