diff --git a/content/en/docs/languages/erlang/_index.md b/content/en/docs/languages/erlang/_index.md index 1f3d6fcb7f4f..5435eb39a8c2 100644 --- a/content/en/docs/languages/erlang/_index.md +++ b/content/en/docs/languages/erlang/_index.md @@ -13,6 +13,7 @@ cascade: otelExporter: 1.6 otelPhoenix: 1.1 otelCowboy: 0.2 + otelEcto: 1.2 --- {{% docs/languages/index-intro erlang %}} diff --git a/content/en/docs/languages/erlang/exporters.md b/content/en/docs/languages/erlang/exporters.md index de6543af9474..95ffa61dec12 100644 --- a/content/en/docs/languages/erlang/exporters.md +++ b/content/en/docs/languages/erlang/exporters.md @@ -16,10 +16,64 @@ collector, which can then export Spans to a self-hosted service like Zipkin or Jaeger, as well as commercial services. For a full list of available exporters, see the [registry](/ecosystem/registry/?component=exporter). -For testing purposes the `opentelemetry-erlang` repository has a Collector -configuration, -[config/otel-collector-config.yaml](https://github.com/open-telemetry/opentelemetry-erlang/blob/main/config/otel-collector-config.yaml) -that can be used as a starting point. This configuration is used in +## Setting up the Collector +For testing purposes, you can start with the following Collector configuration at the root of your project: +```yaml +# otel-collector-config.yaml + +# OpenTelemetry Collector config that receives OTLP and exports to Jager +receivers: + otlp: + protocols: + grpc: + endpoint: "0.0.0.0:4317" + http: + endpoint: "0.0.0.0:4318" +processors: + batch: + send_batch_size: 1024 + timeout: 5s +exporters: + otlp/jaeger: + endpoint: jaeger-all-in-one:4317 + tls: + insecure: true +service: + pipelines: + traces: + receivers: [otlp] + processors: [batch] + exporters: [logging, otlp/jaeger] +``` +For a more detailed example, you can view the [config](https://github.com/open-telemetry/opentelemetry-erlang/blob/main/config/otel-collector-config.yaml) +that `opentelemetry-erlang` uses for testing. + +For the purposes of this tutorial, we'll start the Collector as a docker image along side our app. +For this tutorial, we'll continue along with the Dice Roll example from the [Getting Started](/docs/languages/erlang/getting-started) guide + + +Add this docker-compose file to the root of your app: +```yaml +# docker-compose.yml +version: "3" +services: + otel: + image: otel/opentelemetry-collector-contrib:0.98.0 + command: ["--config=/conf/otel-collector-config.yaml"] + ports: + - 4317:4317 + - 4318:4318 + volumes: + - ./otel-collector-config.yaml:/conf/otel-collector-config.yaml + links: + - jaeger-all-in-one + + jaeger-all-in-one: + image: jaegertracing/all-in-one:latest + ports: + - "16686:16686" +``` +This configuration is used in [docker-compose.yml](https://github.com/open-telemetry/opentelemetry-erlang/blob/main/docker-compose.yml) to start the Collector with receivers for both HTTP and gRPC that then export to Zipkin also run by [docker-compose](https://docs.docker.com/compose/). @@ -90,9 +144,10 @@ end 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`. +the HTTP protocol with endpoint of `localhost` on port `4318`. Note: +- If using `grpc` for the `otlp_protocol` the endpoint should be changed to +`http://localhost:4317`. +- If you're using the docker compose file from above, you should replace `localhost` with `otel`. {{< tabpane text=true >}} {{% tab Erlang %}} @@ -123,3 +178,8 @@ config :opentelemetry_exporter, ``` {{% /tab %}} {{< /tabpane >}} + +## Gotchas +Some environments do not allow containers to execute as root users. If you +work in an environment like this, you can add `user: "1001"` as a top-level key/value +to the `otel` service in the `docker-compose.yml` file used in this tutorial. diff --git a/content/en/docs/languages/erlang/getting-started.md b/content/en/docs/languages/erlang/getting-started.md index 85b40f720b6a..37199e1da279 100644 --- a/content/en/docs/languages/erlang/getting-started.md +++ b/content/en/docs/languages/erlang/getting-started.md @@ -29,7 +29,7 @@ get set up with everything you need. The following example uses a basic [Phoenix](https://www.phoenixframework.org/) web application. For reference, a complete example of the code you will build can be found here: -[opentelemetry-erlang-contrib/examples/dice_game](https://github.com/open-telemetry/opentelemetry-erlang-contrib/tree/main/examples/dice_game). +[opentelemetry-erlang-contrib/examples/dice_game](https://github.com/open-telemetry/opentelemetry-erlang-contrib/tree/main/examples/roll_dice). You can git clone that project or just follow along in your browser. Additional examples can be found [here](/docs/languages/erlang/examples/). @@ -60,11 +60,12 @@ def deps do {:opentelemetry_exporter, "~> {{% param versions.otelExporter %}}"}, {:opentelemetry_phoenix, "~> {{% param versions.otelPhoenix %}}"}, {:opentelemetry_cowboy, "~> {{% param versions.otelCowboy %}}"}, + {:opentelemetry_ecto, "~> {{% param versions.otelEcto %}}"}, # if using ecto ] end ``` -The last two also need to be setup when your application starts: +The last three also need to be setup when your application starts: ```elixir # application.ex @@ -72,11 +73,15 @@ The last two also need to be setup when your application starts: def start(_type, _args) do :opentelemetry_cowboy.setup() OpentelemetryPhoenix.setup(adapter: :cowboy2) + OpentelemetryEcto.setup([:dice_game, :repo]) # if using ecto end ``` -If you're using ecto, you'll also want to add -`OpentelemetryEcto.setup([:dice_game, :repo])`. +Also, make sure your `endpoint.ex` file contains the following line: +```elixir +# endpoint.ex +plug Plug.Telemetry, event_prefix: [:phoenix, :endpoint] +``` We also need to configure the `opentelemetry` application as temporary by adding a `releases` section to your project configuration. This will ensure that if it diff --git a/content/en/docs/languages/erlang/instrumentation.md b/content/en/docs/languages/erlang/instrumentation.md index 7f0c714c0ada..e29c1f746a12 100644 --- a/content/en/docs/languages/erlang/instrumentation.md +++ b/content/en/docs/languages/erlang/instrumentation.md @@ -17,12 +17,18 @@ Add the following dependencies to your project: - `opentelemetry`: contains the SDK that implements the interfaces defined in the API. Without it, all the functions in the API are no-ops. +Optionally, you may choose to include the `open_telemetry_decorator` library. +Note that this library is not officially supported by the opentelemetry project, +but it's handy for wrapping fuctions up in spans. + ```elixir # mix.exs def deps do [ {:opentelemetry, "~> 1.3"}, {:opentelemetry_api, "~> 1.2"}, + # optionally + {:open_telemetry_decorator, "~> 1.4"} ] end ``` @@ -139,6 +145,9 @@ def child_function() do end ``` +If you are using `OpenTelemetryDecorator`, see its [usage docs](https://hexdocs.pm/open_telemetry_decorator/OpenTelemetryDecorator.html) +for examples of how it can be used. + {{% /tab %}} {{< /tabpane >}} ### Spans in Separate Processes