# Open Gleametry

Basic usage:

```gleam
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:
```toml
[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:

```txt
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:
```sh
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:
```sh
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:
```sh
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.

```gleam
// 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

- [x] Enable basic OTEL instrumentation `use ctx <- span.with("name", [])`
- [x] 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.


## Obtained by adding gen_statem as dep. Apparently it sets logging levels of some sort
20:28:26.317 [debug] OTLP exporter failed to initialize: exception throw: {application_either_not_started_or_not_ready,
                     tls_certificate_check}
  in function  tls_certificate_check_shared_state:latest_shared_state_key/0 (/home/kero/U-Bahn/opengleametry/example/build/dev/erlang/tls_certificate_check/src/tls_certificate_check_shared_state.erl, line 479)
  in call from tls_certificate_check_shared_state:get_latest_shared_state/0 (/home/kero/U-Bahn/opengleametry/example/build/dev/erlang/tls_certificate_check/src/tls_certificate_check_shared_state.erl, line 455)
  in call from tls_certificate_check_shared_state:authoritative_certificate_values/0 (/home/kero/U-Bahn/opengleametry/example/build/dev/erlang/tls_certificate_check/src/tls_certificate_check_shared_state.erl, line 139)
  in call from tls_certificate_check:options/1 (/home/kero/U-Bahn/opengleametry/example/build/dev/erlang/tls_certificate_check/src/tls_certificate_check.erl, line 84)
  in call from otel_exporter_otlp:parse_endpoint/2 (/home/kero/U-Bahn/opengleametry/example/build/dev/erlang/opentelemetry_exporter/src/otel_exporter_otlp.erl, line 278)
  in call from otel_exporter_otlp:endpoint/2 (/home/kero/U-Bahn/opengleametry/example/build/dev/erlang/opentelemetry_exporter/src/otel_exporter_otlp.erl, line 240)
  in call from lists:filtermap_1/2 (lists.erl, line 2279)
  in call from otel_exporter_otlp:init/1 (/home/kero/U-Bahn/opengleametry/example/build/dev/erlang/opentelemetry_exporter/src/otel_exporter_otlp.erl, line 127)