Open Gleametry

Basic usage:

import opengleametry/span

{
  use ctx <- span.with("example span", [])
  todo
}

Serious work

The example above makes a noop trace, since there is no more than the opentelemetry_api.

See example/ for the simplest example app that will emit a trace; it contains all of the instructions of this section. Be sure to run it with the instructions of the next section.

Your gleam application needs to depend on opengleametry, and also on opentelemetry sdk and opentelemetry_exporter or another exporter.

For the mentioned exporter, you best wait 1 second before launching your application - early spans are lost… You also should have your app run at least 5 seconds (demo effect), otherwise that exporter will not even initialise completely. Use the gleam logging package with its default logging.configure() for the “INFO” to show up.

It is a good idea to set up inets as extra application (also to get rid of an error when booting), in your gleam.toml, like this:

[erlang]
extra_applications = ["inets"]

Gleam will pick up the opentelemetry_exporter and opentelemetry applications automatically. Unfortunately there is an odd ordering dependency in those two, which will now result in the following message while booting:

OTLP exporter failed to initialize with exception throw:{application_either_not_started_or_not_ready,
                                                         tls_certificate_check}

because gleam orders alphabetically, and that should not matter, except it does. Apparently. Things should still work, but I have not pointed to a collector over https, yet. Lemme know when it does not work.

Collecting

With all that set, the exporter still does not do anything: you need to point it to a collector, and set another value or two when running your gleam application, e.g::

For bash:

export OTEL_SERVICE_NAME="your_application"
export OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4318"
export OTEL_EXPORTER_OTLP_HEADERS="x-service-api-key=12345"
gleam run

For zsh, fish:

set -x OTEL_SERVICE_NAME "your_application"
set -x OTEL_EXPORTER_OTLP_ENDPOINT "http://localhost:4318"
set -x OTEL_EXPORTER_OTLP_HEADERS "x-service-api-key=12345"
gleam run

and you need to run a collector, e.g. jaeger all-in-one docker image:

docker run --rm --name jaeger \
  -p 16686:16686 \
  -p 4317:4317 \
  -p 4318:4318 \
  -p 5778:5778 \
  -p 9411:9411 \
  cr.jaegertracing.io/jaegertracing/jaeger:2.10.0

jaeger all-in-one serves a [UI[(http://localhost:16686) for your browser.

Asynchronous work

When passing a link to a process or an actor (for example in this simple way), a span can be connected to its source.

// a link needs a current context; we create one here
use ctx <- span.with("Main", [])
let link = span.link()
let _pid = process.spawn(fn() {
  use ctx <- span.with_links("nested", [link], [])
  echo ctx
})

To Do

A lot

• Enable basic OTEL instrumentation use ctx <- span.with("name", [])
• This package will not force libraries to depend on exporters (this means that applications that do not include sdk and exporter, will have noop traces)
• Enable persistent links by exposing the opentelemetry Link type
• Provide values from opentelemetry semantic conventions (sidestep the erlang package, as wrapping atoms makes no sense).

Other

There are no tests, since we are only manipuating typed ffi data.