85 lines
2.9 KiB
Markdown
85 lines
2.9 KiB
Markdown
|
# 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
|