95 lines
3.9 KiB
Markdown
95 lines
3.9 KiB
Markdown
# opentelemetry_elli
|
|
|
|
 [](https://gitter.im/open-telemetry/opentelemetry-erlang?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge)
|
|
|
|
Elli middleware for OpenTelemetry instrumentation.
|
|
|
|
## Setup and Configuration
|
|
|
|
``` erlang
|
|
{deps, [opentelemetry_elli]}.
|
|
```
|
|
|
|
While using the `elli_middleware` callback, place `oc_elli_middelware` as the first module to be called in the list of handlers:
|
|
|
|
``` erlang
|
|
[{callback, elli_middleware},
|
|
{callback_args, [{mods, [{otel_elli_middleware, []},
|
|
{<YOUR HANDLER>, []}]}]}]
|
|
```
|
|
|
|
|
|
|
|
OpenTelemetry's [HTTP Semantic Conventions](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/data-http.md#http-server) for a server details the attributes added to a Span automatically by using this middleware. One such attribute must be set in your `sys.config` under the `opentelemetry_elli` application like:
|
|
|
|
``` erlang
|
|
{opentelemetry_elli, [{server_name, <<"my-http-server">>}]}.
|
|
```
|
|
|
|
It is strongly recommended to set this environment variable so the attribute can be included:
|
|
|
|
> http.server_name has shown great value in practice, as bogus HTTP Host headers occur often in the wild. It is strongly recommended to set http.server_name to allow associating requests with some logical server entity.
|
|
|
|
## Use
|
|
|
|
### Including the Middleware and setting Span names
|
|
|
|
The middleware takes care of extracting the parent Span from the requests
|
|
headers, both the [W3C](https://w3c.github.io/trace-context/) and [B3](https://github.com/openzipkin/b3-propagation) formats are supported.
|
|
|
|
Because Elli has no router, there is no way to get a very descriptive Span
|
|
name automatically. See the OpenTelemetry docs [Semantic conventions for HTTP spans](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/data-http.md#name) for
|
|
why you don't want to set the Span name to the raw path of the request. Thus,
|
|
the Span has the name `"HTTP {METHOD_NAME}"`.
|
|
|
|
The macro `update_name` from `opentelemetry_api/include/otel_tracer.hrl` allows you
|
|
to update the name of the Span after it has started:
|
|
|
|
``` erlang
|
|
handle(Req, Args) ->
|
|
handle(Req#req.path, Req, Args).
|
|
|
|
handle([<<"hello">>, Who], Req, _Args) ->
|
|
?update_name(<<"/hello/{who}">>),
|
|
{ok, [], <<"Hello ", Who/binary>>}.
|
|
```
|
|
|
|
Attributes set by the middleware can be found in the OpenTelemetry docs [Semantic
|
|
conventions for HTTP spans](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/data-http.md).
|
|
|
|
Updating the Span name is not required. Another option is to create a child Span
|
|
with a more descriptive name, whose parent will be the Span named `"HTTP
|
|
{METHOD_NAME}"`.
|
|
|
|
### Excluding Paths
|
|
|
|
Not all paths are created equal. It is likely you don't want to Trace a health
|
|
check endpoint or `/metrics` if using Prometheus to scrape metrics. This
|
|
library offers two ways to exclude requests from potentially creating Spans by
|
|
filtering on the raw path in the URL.
|
|
|
|
An application environment variable is read in on Elli start, so the following can
|
|
be added to `sys.config` to exclude the URLs `/health` and `/metrics`:
|
|
|
|
``` erlang
|
|
|
|
{opentelemetry_elli, [{excluded_paths, ["/health", "/metrics"]}]}
|
|
```
|
|
|
|
An OS environment variable, `OTEL_ELLI_EXCLUDED_URLS`, is also read and is a
|
|
comma separated list of paths. Note that the URLs in the variable are split with
|
|
a simple `string:split` call, so commas are not support in any URL. No escaping
|
|
or quoting are recognized, if a comma in a URL's path is required it should be
|
|
percent encoded as `%2C`, this is how the URL it is compared against will appear
|
|
in Elli anyway.
|
|
|
|
The lists from both are merged.
|
|
|
|
## Testing
|
|
|
|
A Common Test suite which starts an Elli server and tests the exported Spans created by a test handle is found under `test/`. Run with:
|
|
|
|
``` erlang
|
|
$ rebar3 ct
|
|
```
|