opentelemetry-erlang-contrib/examples/roll_dice/README.md

85 lines
2.9 KiB
Markdown
Raw Normal View History

# RollDice
The following example uses a basic [Phoenix](https://www.phoenixframework.org/)
web application. For more elaborate examples, see [examples](/docs/instrumentation/erlang/examples/).
To start your Phoenix server:
* Run `mix setup` to install and setup dependencies
* Start the opentelemetry collector and Jaeger front-end with `docker-compose up -d`
* Set your service name `export OTEL_SERVICE_NAME="roll_dice"`
* Start Phoenix endpoint with `mix phx.server` or inside IEx with `iex -S mix phx.server`
To generate and view traces:
* Visit the new API endpoint with `curl http://localhost:4000/api/rolldice` or in your browser
* Visit [`localhost:16686`](http://localhost:16686) to see the traces in Jaeger
For more information on the OpenTelemetry instrumentation in this example, check out the guide for getting started with [OpenTelemetry](https://opentelemetry.io/docs/instrumentation/erlang/getting-started/)
## How did we get here?
To begin, use the `phx` generator to create a new project. To keep things simple we'll leave out the database and html for now with the `--no-ecto` and `--no-html` flags.
In a real app, you'll probably want to include ecto configured for your preferred database with the `--database` flag (`postgres` by default).
```shell
mix phx.new --no-ecto --no-html roll_dice
```
### Rolling The Dice
Now we'll add an API endpoint that will let us roll the dice and return a random
number between 1 and 6.
To start, we'll add a route to the `/api` scope in your router
```elixir
# lib/roll_dice_web/router.ex
scope "/api", DiceGameWeb do
pipe_through :api
get "/rolldice", DiceController, :roll
end
```
Then we'll create a new file in the controllers folder for that module. We told
the router that we will define a roll function, so we'll do that. It will return
a `200` response code and the result of a `dice_roll` function, which we will
emit a span for. We also want to set the value of the generated roll as an
attribute on the span.
```elixir
# lib/roll_dice_web/controllers/dice_controller.ex
defmodule DiceGameWeb.DiceController do
use DiceGameWeb, :controller
require OpenTelemetry.Tracer, as: Tracer
def roll(conn, _params) do
send_resp(conn, 200, roll_dice())
end
defp roll_dice do
Tracer.with_span("roll_dice") do
roll = Enum.random(1..6)
Tracer.set_attribute("roll.value", roll)
to_string(roll)
end
end
end
```
If you point your browser/curl/etc. to [`localhost:4000/api/rolldice`](http://localhost:4000/api/rolldice) you should get a random number in response.
Ready to run in production? Please [check our deployment guides](https://hexdocs.pm/phoenix/deployment.html).
## Learn more
* Official website: https://www.phoenixframework.org/
* Guides: https://hexdocs.pm/phoenix/overview.html
* Docs: https://hexdocs.pm/phoenix
* Forum: https://elixirforum.com/c/phoenix-forum
* Source: https://github.com/phoenixframework/phoenix