You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+80-62Lines changed: 80 additions & 62 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,82 +4,81 @@ OpenTelemetry
4
4
[](https://github.com/erlef/eef-observability-wg)
We hold weekly meetings. See details at [community page](https://github.com/open-telemetry/community#special-interest-groups).
14
27
15
-
We use [GitHub Discussions](https://github.com/open-telemetry/opentelemetry-erlang/discussions) for support or general questions. Feel free to drop us a line.
for support or general questions. Feel free to drop us a line.
16
31
17
32
We are also present in the #otel-erlang-elixir channel in the [CNCF
18
33
slack](https://slack.cncf.io/). Please join us for more informal discussions.
19
34
20
-
You can also find us in the #opentelemetry channel on [Elixir Slack](https://elixir-slackin.herokuapp.com/).
35
+
You can also find us in the #opentelemetry channel on [Elixir
36
+
Slack](https://elixir-slackin.herokuapp.com/).
21
37
22
38
## Design
23
39
24
-
The [OpenTelemetry specification](https://github.com/open-telemetry/opentelemetry-specification) defines a language library as having 2 components, the API and the SDK. The API must not only define the interfaces of any implementation in that language but also be able to function as a noop implementation of the tracer. The SDK is the default implementation of the API that must be optional.
found in directory `apps/opentelemetry_api` of this repo which is published as
29
50
the hex package [opentelemetry_api](https://hex.pm/packages/opentelemetry_api).
30
51
31
-
This repository is the Erlang's SDK implementation and should be included in the final release and configured to setup the sampler, span processors and span exporters.
52
+
The SDK implementation, found under `apps/opentelemetry` and hex package
53
+
[opentelemetry](https://hex.pm/packages/opentelemetry), should be included in an
54
+
OTP Release along with an exporter.
32
55
33
-
## Usage
34
-
35
-
### Hex Dependencies
36
-
37
-
It is recommended to use the versions published on hex.pm for [OpenTelemetry
The `override: true` is required because the SDK Application, `opentelemetry`, has
125
+
the API in its `deps` list of its `rebar.config` as a hex dependency and this will
126
+
clash when `mix` tries to resolve the dependencies and fail without the
127
+
override. `override: true` is also used on the SDK because the
128
+
`opentelemetry_exporter` application depends on it and the API as hex deps so if
129
+
it is included the override is necessary.
130
+
113
131
## Benchmarks
114
132
115
133
Running benchmarks is done with [benchee](https://github.com/bencheeorg/benchee). Benchmark functions are in modules under `samples/`. To run them open a rebar3 shell in the `bench` profile:
Copy file name to clipboardExpand all lines: apps/opentelemetry_api/README.md
+19-35Lines changed: 19 additions & 35 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -3,34 +3,14 @@
3
3
[](https://github.com/erlef/eef-observability-wg)
This is the API portion of [OpenTelemetry](https://opentelemetry.io/) for Erlang and Elixir Applications.
6
+
This is the API portion of [OpenTelemetry](https://opentelemetry.io/) for Erlang
7
+
and Elixir Applications, implementing the API portion of [the specification](https://github.com/open-telemetry/opentelemetry-specification).
7
8
8
-
This is a library, it does not start any processes, and should be the only OpenTelemetry dependency of Erlang/Elixir Applications.
9
-
10
-
The end user of your Application can then choose to include the [OpenTelemetry implementation](https://github.com/open-telemetry/opentelemetry-erlang) Application. If the implementation Application is not in the final release the OpenTelemetry instrumentation will all be no-ops. This means no processes started, no ETS tables created and nothing added to the process dictionary.
11
-
12
-
This separation is done so you should feel comfortable instrumenting your Erlang/Elixir Application with OpenTelemetry and not worry that a complicated dependency is being forced on your users.
9
+
This is a library, it does not start any processes, and should be the only
10
+
OpenTelemetry dependency of Erlang/Elixir Applications.
13
11
14
12
## Use
15
13
16
-
When instrumenting an Application to be used as a dependency of other projects it is best practice to register a `Tracer` with a name and a version using the Application's name and version. This should be the name and version of the Application that has the `opentelemetry` calls being written in it, not the name of the Application it might be being used to instrument. For example, an [Elli](https://github.com/elli-lib/elli) middleware to add tracing to the Elli HTTP server would *not* be named `elli`, it would be the name of the middleware Application, like `opentelemetry_elli`.
17
-
18
-
Registration is done through a single process and uses a [persistent_term](https://erlang.org/doc/man/persistent_term.html), so should be done only once per-Application. Updating a registration is allowed, so updating the version on a release upgrade can, and should, be done, but will involve the performance penalty of updating a [persistent_term](https://erlang.org/doc/man/persistent_term.html).
19
-
20
-
Naming the `Tracers` provides additional metadata on spans and allows the user of your Application to disable the traces from the dependency if it is needed.
21
-
22
-
### Dependency in Elixir
23
-
24
-
```elixir
25
-
defdepsdo
26
-
[
27
-
{:opentelemetry_api, "~> 0.6.0"}
28
-
]
29
-
end
30
-
```
31
-
32
-
### Helper Macros for Application Tracers
33
-
34
14
There are both Erlang and Elixir macros that make use of the current module's
35
15
name to lookup a Named Tracer -- a Named Tracer is created for each Application
36
16
loaded in the system at start time -- for you and can be used for Trace and Span
@@ -63,24 +43,28 @@ end
63
43
64
44
### IncludingtheOpenTelemetrySDK
65
45
66
-
Fortracestoactuallybetracked, propagatedandexported, the [opentelemetry](https://github.com/open-telemetry/opentelemetry-erlang) Applicationmustbeincludedasadependencyofyourproject, likelyaspartofa [Release](https://erlang.org/doc/design_principles/release_structure.html) andnotasadependencyofanindividualApplicationwithintheRelease.
67
-
68
-
Seethe [Usingsection](https://github.com/open-telemetry/opentelemetry-erlang#using) of the [OpenTelemetry-Erlang](https://github.com/open-telemetry/opentelemetry-erlang) repository for details.
[Release](https://erlang.org/doc/design_principles/release_structure.html) and
51
+
notasadependencyofanyindividualApplication.
69
52
70
53
### Exporters
71
54
72
-
Exporters can be found as separate Applications on Github under the [OpenTelemetry Beam Organization](https://github.com/opentelemetry-beam).
Alternatively the `opentelemetry_exporter` Application can be configured itself.
54
+
Available configuration keys:
55
+
51
56
-`otlp_endpoint`: The URL to send traces and metrics to, for traces the path `v1/traces` is appended to the path in the URL.
52
57
-`otlp_traces_endpoint`: URL to send only traces to. This takes precedence for exporting traces and the path of the URL is kept as is, no suffix is appended.
53
58
-`otlp_headers`: List of additional headers (`[{unicode:chardata(), unicode:chardata()}]`) to add to export requests.
The default SSL options for HTTPS requests are set using
81
85
[tls_certificate_check](https://hex.pm/packages/tls_certificate_check). This
82
86
package also provides the [CA certificates from Mozilla](https://curl.se/docs/caextract.html).
@@ -91,6 +95,9 @@ for more information on securing HTTP requests in Erlang.
91
95
92
96
### OS Environment
93
97
98
+
Lastly, configuring the exporter can be done with OS environment variables,
99
+
which take precedence:
100
+
94
101
-`OTEL_EXPORTER_OTLP_ENDPOINT`: The URL to send traces and metrics to, for traces the path `v1/traces` is appended to the path in the URL.
95
102
-`OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`: URL to send only traces to. This takes precedence for exporting traces and the path of the URL is kept as is, no suffix is appended.
96
103
-`OTEL_EXPORTER_OTLP_HEADERS`: List of additional headers to add to export requests.
0 commit comments