mirror of
https://github.com/ocaml-tracing/ocaml-opentelemetry.git
synced 2026-03-07 18:37:56 -05:00
a44c50581b
- Regenerate proto bindings with yojson support - Add JSON encoding path in Resource_signal.Encode - Pass protocol from config to generic_http_consumer - Set Content-Type/Accept headers based on protocol - Remove hardcoded protobuf headers from all HTTP client implementations - Add yojson dependency
139 lines
4.9 KiB
Markdown
139 lines
4.9 KiB
Markdown
|
|
# Opentelemetry [](https://github.com/imandra-ai/ocaml-opentelemetry/actions/workflows/main.yml)
|
|
|
|
This project provides an API for instrumenting server software
|
|
using [opentelemetry](https://opentelemetry.io/docs), as well as
|
|
connectors to talk to opentelemetry software such as [jaeger](https://www.jaegertracing.io/).
|
|
|
|
- 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.) using cURL bindings;
|
|
- library `opentelemetry-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 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 vendored `ambient-context`, see `opentelemetry.ambient-context`)
|
|
|
|
## Use
|
|
|
|
For now, instrument traces/spans, logs, and metrics manually:
|
|
|
|
```ocaml
|
|
module Otel = Opentelemetry
|
|
let (let@) = (@@)
|
|
|
|
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. optionally configure [ambient-context][] with the appropriate storage for your environment — TLS, Lwt, Eio…;
|
|
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:
|
|
|
|
```ocaml
|
|
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 ();
|
|
(* … *)
|
|
```
|
|
|
|
[`service_name`]: <https://v3.ocaml.org/p/opentelemetry/0.5/doc/Opentelemetry/Globals/index.html#val-service_name>
|
|
[`Collector`]: <https://v3.ocaml.org/p/opentelemetry/0.5/doc/Opentelemetry/Collector/index.html>
|
|
[ambient-context]: now vendored as `opentelemetry.ambient-context`, formerly <https://v3.ocaml.org/p/ambient-context>
|
|
|
|
## Configuration
|
|
|
|
### Environment Variables
|
|
|
|
The library supports standard OpenTelemetry environment variables:
|
|
|
|
**General:**
|
|
- `OTEL_SDK_DISABLED` - disable the SDK (default: false)
|
|
- `OTEL_SERVICE_NAME` - service name
|
|
- `OTEL_RESOURCE_ATTRIBUTES` - comma-separated key=value resource attributes
|
|
- `OTEL_OCAML_DEBUG=1` - print debug messages from the opentelemetry library
|
|
|
|
**Exporter endpoints:**
|
|
- `OTEL_EXPORTER_OTLP_ENDPOINT` - base endpoint (default: http://localhost:4318)
|
|
- `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` - traces endpoint
|
|
- `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` - metrics endpoint
|
|
- `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` - logs endpoint
|
|
|
|
**Exporter configuration:**
|
|
- `OTEL_EXPORTER_OTLP_PROTOCOL` - protocol: http/protobuf or http/json (default: http/protobuf)
|
|
|
|
**Headers:**
|
|
- `OTEL_EXPORTER_OTLP_HEADERS` - headers as comma-separated key=value pairs
|
|
- `OTEL_EXPORTER_OTLP_TRACES_HEADERS` - traces-specific headers
|
|
- `OTEL_EXPORTER_OTLP_METRICS_HEADERS` - metrics-specific headers
|
|
- `OTEL_EXPORTER_OTLP_LOGS_HEADERS` - logs-specific headers
|
|
|
|
|
|
## 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 of `fork` on some Unixy systems.
|
|
See [#68](https://github.com/imandra-ai/ocaml-opentelemetry/issues/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 a `Lwt_main.run` scope.
|
|
|
|
## Opentelemetry-trace
|
|
|
|
The optional library `opentelemetry.trace`, present if [trace](https://github.com/c-cube/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.
|
|
|
|
- [ ] [metrics](https://opentelemetry.io/docs/reference/specification/metrics/semantic_conventions/)
|
|
- [ ] [traces](https://opentelemetry.io/docs/reference/specification/trace/semantic_conventions/)
|
|
- [ ] [resources](https://opentelemetry.io/docs/reference/specification/resource/semantic_conventions/)
|