diff --git a/.prettierignore b/.prettierignore index 1c03162a5f7b..69b2f550e290 100644 --- a/.prettierignore +++ b/.prettierignore @@ -20,8 +20,7 @@ package-lock.json /content/en/blog/2022 /content/en/docs/concepts /content/en/docs/demo -content/en/docs/instrumentation/erlang -content/en/docs/instrumentation/go +/content/en/docs/instrumentation/go /data /resources /scripts diff --git a/content/en/docs/instrumentation/erlang/_index.md b/content/en/docs/instrumentation/erlang/_index.md index b2cf5d9e15c6..efef5d8cf8d7 100644 --- a/content/en/docs/instrumentation/erlang/_index.md +++ b/content/en/docs/instrumentation/erlang/_index.md @@ -2,16 +2,17 @@ title: Erlang/Elixir weight: 14 description: > - Erlang/Elixir - A language-specific implementation of OpenTelemetry in Erlang/Elixir. + Erlang/Elixir A language-specific implementation of OpenTelemetry + in Erlang/Elixir. --- {{% lang_instrumentation_index_head "erlang" %}} - Packages of the API, SDK and OTLP exporter are published to - [hex.pm](https://hex.pm) as - [opentelemetry_api](https://hex.pm/packages/opentelemetry_api), - [opentelemetry](https://hex.pm/packages/opentelemetry) and - [opentelemetry_exporter](https://hex.pm/packages/opentelemetry_exporter). -{{% /lang_instrumentation_index_head %}} \ No newline at end of file + +Packages of the API, SDK and OTLP exporter are published to +[hex.pm](https://hex.pm) as +[opentelemetry_api](https://hex.pm/packages/opentelemetry_api), +[opentelemetry](https://hex.pm/packages/opentelemetry) and +[opentelemetry_exporter](https://hex.pm/packages/opentelemetry_exporter). + +{{% /lang_instrumentation_index_head %}} diff --git a/content/en/docs/instrumentation/erlang/getting-started.md b/content/en/docs/instrumentation/erlang/getting-started.md index 0b28950fafc5..09383377d96c 100644 --- a/content/en/docs/instrumentation/erlang/getting-started.md +++ b/content/en/docs/instrumentation/erlang/getting-started.md @@ -4,8 +4,8 @@ weight: 20 --- Welcome to the OpenTelemetry for Erlang/Elixir getting started guide! This guide -will walk you through the basic steps in installing, configuring, and exporting data -from OpenTelemetry. +will walk you through the basic steps in installing, configuring, and exporting +data from OpenTelemetry. ## Installation @@ -15,41 +15,45 @@ depending on what you are trying to accomplish. ### `opentelemetry_api` -If you are developing a library or OTP Application that someone else would include -into their deployed code and you want to provide OpenTelemetry instrumentation -for them, you'll want to add the dependency `opentelemetry_api`. This package contains -only the API of OpenTelemetry. It will not start any processes and all API calls -(such as starting a span) will be a no-op that creates no data, unless the -`opentelemetry` SDK package is also installed. +If you are developing a library or OTP Application that someone else would +include into their deployed code and you want to provide OpenTelemetry +instrumentation for them, you'll want to add the dependency `opentelemetry_api`. +This package contains only the API of OpenTelemetry. It will not start any +processes and all API calls (such as starting a span) will be a no-op that +creates no data, unless the `opentelemetry` SDK package is also installed. ### `opentelemetry` If you are developing an Application that will actually be deployed and export OpenTelemetry data, whether from instrumented dependencies or your code itself, -you'll want to add the `opentelemetry` package. This is the implementation of the -API and will start a Supervision tree, handling the necessary components for recording -and exporting OpenTelemetry signals. This is the package where you would configure -the destination(s) for your OpenTelemetry data, whether it be to an OpenTelemetry -Collector instance, or directly to a vendor's data ingestion API. +you'll want to add the `opentelemetry` package. This is the implementation of +the API and will start a Supervision tree, handling the necessary components for +recording and exporting OpenTelemetry signals. This is the package where you +would configure the destination(s) for your OpenTelemetry data, whether it be to +an OpenTelemetry Collector instance, or directly to a vendor's data ingestion +API. To get started with this guide, create a new project with `rebar3` or `mix`: + {{< ot-tabs Erlang Elixir >}} -{{< ot-tab >}} -$ rebar3 new release otel_getting_started +{{< ot-tab lang="sh" >}} +rebar3 new release otel_getting_started {{< /ot-tab >}} -{{< ot-tab >}} -$ mix new --sup otel_getting_started +{{< ot-tab lang="sh" >}} +mix new --sup otel_getting_started {{< /ot-tab >}} {{< /ot-tabs >}} + Then, in the project you just created, add both `opentelemetry_api` and `opentelemetry` as dependencies. We add both because this is a project we will run as a Release and export spans from. + {{< ot-tabs Erlang Elixir >}} {{< ot-tab >}} @@ -67,11 +71,13 @@ end {{< /ot-tab >}} {{< /ot-tabs >}} + In the case of Erlang, the Applications will also need to be added to -`src/otel_getting_started.app.src`. In an Elixir project, a `releases` -section needs to be added to `mix.exs`: +`src/otel_getting_started.app.src`. In an Elixir project, a `releases` section +needs to be added to `mix.exs`: + {{< ot-tabs Erlang Elixir >}} {{< ot-tab >}} @@ -93,16 +99,18 @@ releases: [ {{< /ot-tab >}} {{< /ot-tabs >}} + ## Initialization and Configuration -Configuration is done through the [Application -environment](https://erlang.org/doc/design_principles/applications.html#configuring-an-application) -or [OS Environment Variables]({{< relref "/docs/reference/specification/sdk-environment-variables" >}}). The -`opentelemetry` Application uses the configuration to initialize a [Tracer -Provider](https://hexdocs.pm/opentelemetry_api/otel_tracer_provider.html), its -[Span Processors](https://hexdocs.pm/opentelemetry/otel_span_processor.html) and -the [Exporter](https://hexdocs.pm/opentelemetry/otel_exporter.html). +Configuration is done through the +[Application environment](https://erlang.org/doc/design_principles/applications.html#configuring-an-application) +or +[OS Environment Variables](/docs/reference/specification/sdk-environment-variables/). +The `opentelemetry` Application uses the configuration to initialize a +[Tracer Provider](https://hexdocs.pm/opentelemetry_api/otel_tracer_provider.html), +its [Span Processors](https://hexdocs.pm/opentelemetry/otel_span_processor.html) +and the [Exporter](https://hexdocs.pm/opentelemetry/otel_exporter.html). ### Using the Console Exporter @@ -113,10 +121,11 @@ variety of exporters through its ecosystem, including popular open-source tools like Jaeger and Zipkin. To configure OpenTelemetry to use a particular exporter, in this case -`otel_exporter_stdout`, the Application environment for `opentelemetry` must -set the `exporter` for the span processor `otel_batch_processor`, a type -of span processor that batches up multiple spans over a period of time: +`otel_exporter_stdout`, the Application environment for `opentelemetry` must set +the `exporter` for the span processor `otel_batch_processor`, a type of span +processor that batches up multiple spans over a period of time: + {{< ot-tabs Erlang Elixir >}} {{< ot-tab >}} @@ -136,12 +145,14 @@ config :opentelemetry, {{< /ot-tab >}} {{< /ot-tabs >}} + ## Working with Spans -Now that the dependencies and configuration are set up, we can create a module with -a function `hello/0` that starts some spans: +Now that the dependencies and configuration are set up, we can create a module +with a function `hello/0` that starts some spans: + {{< ot-tabs Erlang Elixir >}} {{< ot-tab >}} @@ -188,30 +199,32 @@ end {{< /ot-tab >}} {{< /ot-tabs >}} + -In this example, we're using macros that use the process dictionary for -context propagation and for getting the tracer. +In this example, we're using macros that use the process dictionary for context +propagation and for getting the tracer. Inside our function, we're creating a new span named `operation` with the `with_span` macro. The macro sets the new span as `active` in the current -context -- stored in the process dictionary, since we aren't passing a -context as a variable. +context -- stored in the process dictionary, since we aren't passing a context +as a variable. Spans can have attributes and events, which are metadata and log statements that -help you interpret traces after-the-fact. The first span has an event `Nice -operation!`, with attributes on the event, as well as an attribute set on the -span itself. +help you interpret traces after-the-fact. The first span has an event +`Nice operation!`, with attributes on the event, as well as an attribute set on +the span itself. Finally, in this code snippet, we can see an example of creating a child span of the currently-active span. When the `with_span` macro starts a new span, it uses -the active span of the current context as the parent. So when you run this program, -you'll see that the `Sub operation...` span has been created as a child of the -`operation` span. +the active span of the current context as the parent. So when you run this +program, you'll see that the `Sub operation...` span has been created as a child +of the `operation` span. -To test out this project and see the spans created, you can run with `rebar3 -shell` or `iex -S mix`, each will pick up the corresponding configuration for -the release, resulting in the tracer and exporter to started. +To test out this project and see the spans created, you can run with +`rebar3 shell` or `iex -S mix`, each will pick up the corresponding +configuration for the release, resulting in the tracer and exporter to started. + {{< ot-tabs Erlang Elixir >}} {{< ot-tab >}} @@ -263,6 +276,7 @@ iex(2)> {{< /ot-tab >}} {{< /ot-tabs >}} + ## Exporting to the OpenTelemetry Collector @@ -285,6 +299,7 @@ Zipkin also run by [docker-compose](https://docs.docker.com/compose/). To export to the running Collector the `opentelemetry_exporter` package must be added to the project's dependencies: + {{< ot-tabs Erlang Elixir >}} {{< ot-tab >}} @@ -304,14 +319,16 @@ end {{< /ot-tab >}} {{< /ot-tabs >}} + -It should then be added to the configuration of the Release, it should be before the SDK -Application to ensure the exporter's dependencies are started before the SDK -attempts to initialize and use the exporter. +It should then be added to the configuration of the Release, it should be before +the SDK Application to ensure the exporter's dependencies are started before the +SDK attempts to initialize and use the exporter. -Example of Release configuration in `rebar.config` and for [mix's Release -task](https://hexdocs.pm/mix/Mix.Tasks.Release.html): +Example of Release configuration in `rebar.config` and for +[mix's Release task](https://hexdocs.pm/mix/Mix.Tasks.Release.html): + {{< ot-tabs Erlang Elixir >}} {{< ot-tab >}} @@ -340,13 +357,16 @@ end {{< /ot-tab >}} {{< /ot-tabs >}} + Finally, the runtime configuration of the `opentelemetry` and `opentelemetry_exporter` Applications are set to export to the Collector. The configurations below show the defaults that are used if none are set, which are the HTTP protocol with endpoint of `localhost` on port `4318`. If using `grpc` -for the `otlp_protocol` the endpoint should be changed to `http://localhost:4317`. +for the `otlp_protocol` the endpoint should be changed to +`http://localhost:4317`. + {{< ot-tabs Erlang Elixir >}} {{< ot-tab >}} @@ -374,3 +394,4 @@ config :opentelemetry_exporter, {{< /ot-tab >}} {{< /ot-tabs >}} + diff --git a/content/en/docs/instrumentation/erlang/instrumentation.md b/content/en/docs/instrumentation/erlang/instrumentation.md index 05cdb238429a..2ce5dd39f173 100644 --- a/content/en/docs/instrumentation/erlang/instrumentation.md +++ b/content/en/docs/instrumentation/erlang/instrumentation.md @@ -3,10 +3,10 @@ title: Instrumentation weight: 30 --- -Instrumentation is the act of adding observability code to your -application. This can be done with direct calls to the OpenTelemetry API within -your code or including a dependency which calls the API and hooks into your -project, like a middleware for an HTTP server. +Instrumentation is the act of adding observability code to your application. +This can be done with direct calls to the OpenTelemetry API within your code or +including a dependency which calls the API and hooks into your project, like a +middleware for an HTTP server. ## TracerProvider and Tracers @@ -25,6 +25,7 @@ variable `create_application_tracers` to `false`. If you want a more specific name for a `Tracer` you can create a `Tracer` with a name and version and pass it manually to `otel_tracer` or `OpenTelemetry.Tracer`. Examples: + {{< ot-tabs Erlang Elixir >}} {{< ot-tab >}} @@ -42,6 +43,7 @@ OpenTelemetry.Tracer.end_span(span_ctx) {{< /ot-tab >}} {{< /ot-tabs >}} + In most cases you will not need to manually create a `Tracer`. Simply use the macros provided, which are covered in the following section, and the `Tracer` @@ -54,7 +56,7 @@ out to be generating too many or in some way problematic spans and it is desired to disable their generation. Additionally, the name and version of the `Tracer` are exported as the -[`InstrumentationLibrary`]({{< relref "/docs/reference/specification/glossary#instrumentation-library" >}}) +[`InstrumentationLibrary`](/docs/reference/specification/glossary/#instrumentation-library) component of spans. This allows users to group and search spans by the Application they came from. @@ -69,8 +71,8 @@ the `Context` as an argument not only to the OpenTelemetry functions but to any function you need to propagate the `context` so that spans started in those functions have the proper parent. -For implicit context propagation across functions within a process the [process -dictionary](https://erlang.org/doc/reference_manual/processes.html#process-dictionary) +For implicit context propagation across functions within a process the +[process dictionary](https://erlang.org/doc/reference_manual/processes.html#process-dictionary) is used to store the context. When you start a span with the macro `with_span` the context in the process dictionary is updated to make the newly started span the currently active span and this span will be end'ed when the block or @@ -79,6 +81,7 @@ function completes. Additionally, starting a new span within the body of parent is again the active span when the child's block or function body completes: + {{< ot-tabs Erlang Elixir >}} {{< ot-tab >}} @@ -114,6 +117,7 @@ end {{< /ot-tab >}} {{< /ot-tabs >}} + ### Cross Process Propagation @@ -121,7 +125,8 @@ The examples in the previous section were spans with a child-parent relationship within the same process where the parent is available in the process dictionary when creating a child span. Using the process dictionary this way isn't possible when crossing processes, either by spawning a new process or sending a message -to an existing process. Instead, the context must be manually passed as a variable. +to an existing process. Instead, the context must be manually passed as a +variable. #### Creating Spans for New Processes @@ -130,11 +135,12 @@ particular process. This can be done with the macro `start_span`. Unlike `with_span`, the `start_span` macro does not set the new span as the currently active span in the context of the process dictionary. -Connecting a span as a parent to a child in a new process can be done by attaching -the context and setting the new span as currently active in the process. The -whole context should be attached in order to not lose other telemetry data like -[baggage]({{< relref "/docs/reference/specification/baggage/api" >}}). +Connecting a span as a parent to a child in a new process can be done by +attaching the context and setting the new span as currently active in the +process. The whole context should be attached in order to not lose other +telemetry data like [baggage](/docs/reference/specification/baggage/api/). + {{< ot-tabs Erlang Elixir >}} {{< ot-tab >}} @@ -168,16 +174,18 @@ _ = Task.await(task) {{< /ot-tab >}} {{< /ot-tabs >}} + #### Linking the New Span If the work being done by the other process is better represented as a `link` -- -see [the `link` definition in the -specification]({{< relref "/docs/reference/specification/overview#links-between-spans" >}}) -for more on when that is appropriate --- then the `SpanCtx` returned by `start_span` is passed to `link/1` to create -a `link` that can be passed to `with_span` or `start_span`: +see +[the `link` definition in the specification](/docs/reference/specification/overview/#links-between-spans) +for more on when that is appropriate -- then the `SpanCtx` returned by +`start_span` is passed to `link/1` to create a `link` that can be passed to +`with_span` or `start_span`: + {{< ot-tabs Erlang Elixir >}} {{< ot-tab >}} @@ -204,6 +212,7 @@ task = Task.async(fn -> {{< /ot-tab >}} {{< /ot-tabs >}} + ### Attributes @@ -221,6 +230,7 @@ The following example shows the two ways of setting attributes on a span by both setting an attribute in the start options and then again with `set_attributes` in the body of the span operation: + {{< ot-tabs Erlang Elixir >}} {{< ot-tab >}} @@ -239,14 +249,15 @@ end {{< /ot-tab >}} {{< /ot-tabs >}} + #### Semantic Attributes Semantic Attributes are attributes that are defined by the [OpenTelemetry -Specification][] in order to provide a shared set of attribute keys across multiple -languages, frameworks, and runtimes for common concepts like HTTP methods, -status codes, user agents, and more. These attribute keys and values are -available in the header `opentelemetry_api/include/otel_resource.hrl`. +Specification][] in order to provide a shared set of attribute keys across +multiple languages, frameworks, and runtimes for common concepts like HTTP +methods, status codes, user agents, and more. These attribute keys and values +are available in the header `opentelemetry_api/include/otel_resource.hrl`. For details, see [Trace semantic conventions][]. @@ -258,6 +269,7 @@ exclusive access to a resource like a database connection from a pool. An event could be created at two points - once, when the connection is checked out from the pool, and another when it is checked in. + {{< ot-tabs Erlang Elixir >}} {{< ot-tab >}} @@ -282,6 +294,7 @@ end {{< /ot-tab >}} {{< /ot-tabs >}} + A useful characteristic of events is that their timestamps are displayed as offsets from the beginning of the span, allowing you to easily see how much time @@ -289,6 +302,7 @@ elapsed between them. Additionally, events can also have attributes of their own: + {{< ot-tabs Erlang Elixir >}} {{< ot-tab >}} @@ -300,19 +314,21 @@ Span.add_event("Process exited with reason", pid: pid, reason: Reason) {{< /ot-tab >}} {{< /ot-tabs >}} + ## Cross Service Propagators Distributed traces extend beyond a single service, meaning some context must be propagated across services to create the parent-child relationship between -spans. This requires cross service [_context -propagation_]({{< relref "/docs/reference/specification/overview#context-propagation" >}}), +spans. This requires cross service +[_context propagation_](/docs/reference/specification/overview/#context-propagation), a mechanism where identifiers for a trace are sent to remote processes. In order to propagate trace context over the wire, a propagator must be registered with OpenTelemetry. This can be done through configuration of the `opentelemetry` application: + {{< ot-tabs Erlang Elixir >}} {{< ot-tab >}} @@ -331,10 +347,11 @@ text_map_propagators: [:baggage, :trace_context], {{< /ot-tab >}} {{< /ot-tabs >}} + -If you instead need to use the [B3 -specification](https://github.com/openzipkin/b3-propagation), originally from -the [Zipkin project](https://zipkin.io/), then replace `trace_context` and +If you instead need to use the +[B3 specification](https://github.com/openzipkin/b3-propagation), originally +from the [Zipkin project](https://zipkin.io/), then replace `trace_context` and `:trace_context` with `b3` and `:b3` for Erlang or Elixir respectively. ## Library Instrumentation @@ -343,15 +360,16 @@ Library instrumentations, broadly speaking, refers to instrumentation code that you didn't write but instead include through another library. OpenTelemetry for Erlang/Elixir supports this process through wrappers and helper functions around many popular frameworks and libraries. You can find in the -[opentelemetry-erlang-contrib -repo](https://github.com/open-telemetry/opentelemetry-erlang-contrib/), -published to [hex.pm](https://hex.pm) under the [OpenTelemetry -Organization](https://hex.pm/orgs/opentelemetry) and the [registry](/ecosystem/registry/). +[opentelemetry-erlang-contrib repo](https://github.com/open-telemetry/opentelemetry-erlang-contrib/), +published to [hex.pm](https://hex.pm) under the +[OpenTelemetry Organization](https://hex.pm/orgs/opentelemetry) and the +[registry](/ecosystem/registry/). ## Creating Metrics The metrics API, found in `apps/opentelemetry-experimental-api` of the `opentelemetry-erlang` repository, is currently unstable, documentation TBA. -[OpenTelemetry Specification]: /docs/reference/specification -[Trace semantic conventions]: /docs/reference/specification/trace/semantic_conventions +[opentelemetry specification]: /docs/reference/specification/ +[trace semantic conventions]: + /docs/reference/specification/trace/semantic_conventions/ diff --git a/content/en/docs/instrumentation/erlang/testing.md b/content/en/docs/instrumentation/erlang/testing.md index c0025031e2dc..779a784c6e12 100644 --- a/content/en/docs/instrumentation/erlang/testing.md +++ b/content/en/docs/instrumentation/erlang/testing.md @@ -1,5 +1,5 @@ --- -title: "Testing" +title: Testing weight: 40 --- @@ -14,6 +14,7 @@ validation. Only the `opentelemetry` and `opentelemetry_api` libraries are required for testing in Elixir/Erlang: + {{< ot-tabs Erlang Elixir >}} {{< ot-tab >}} @@ -31,11 +32,13 @@ end {{< /ot-tab >}} {{< /ot-tabs >}} + -Set your `exporter` to `:none` and the span processor to `:otel_simple_processor`. -This ensure that your tests don't actually export data to a destination, and that -spans can be analyzed after they are processed. +Set your `exporter` to `:none` and the span processor to +`:otel_simple_processor`. This ensure that your tests don't actually export data +to a destination, and that spans can be analyzed after they are processed. + {{< ot-tabs Erlang Elixir >}} {{< ot-tab >}} @@ -59,11 +62,13 @@ config :opentelemetry, :processors, [ {{< /ot-tab >}} {{< /ot-tabs >}} + A modified version of the `hello` function from the [Getting Started](/docs/instrumentation/erlang/getting-started/) guide will serve as our test case: + {{< ot-tabs Erlang Elixir >}} {{< ot-tab >}} @@ -98,9 +103,11 @@ end {{< /ot-tab >}} {{< /ot-tabs >}} + ## Testing + {{< ot-tabs Erlang Elixir >}} {{< ot-tab >}} @@ -190,3 +197,4 @@ end {{< /ot-tab >}} {{< /ot-tabs >}} +