opentelemetry-erlang-contrib/instrumentation/opentelemetry_phoenix/README.md

# OpentelemetryPhoenix

[![EEF Observability WG project](https://img.shields.io/badge/EEF-Observability-black)](https://github.com/erlef/eef-observability-wg)
[![Hex.pm](https://img.shields.io/hexpm/v/opentelemetry_phoenix)](https://hex.pm/packages/opentelemetry_phoenix)
![Build Status](https://github.com/opentelemetry-beam/opentelemetry_phoenix/workflows/Tests/badge.svg)

Telemetry handler that creates Opentelemetry spans from Phoenix events.

After installing, setup the handler in your application behaviour before your
top-level supervisor starts.

```elixir
OpentelemetryPhoenix.setup()
```

See the documentation for `OpentelemetryPhoenix.setup/1` for additional options that
may be supplied.


## Installation

```elixir
def deps do
  [
    {:opentelemetry_phoenix, "~> 1.1"}
  ]
end
```

## Compatibility Matrix

| OpentelemetryPhoenix Version | Otel Version | Notes |
| :--------------------------- | :----------- | :---- |
|                              |              |       |
| v0.1.0                       | <= v.0.5.0   |       |
| v1.0.0-rc.3                  | v1.0.0-rc.1  |       |
|                              | v1.0.0-rc.2  |       |
| v1.0.0-rc.4                  | v1.0.0-rc.2  | Otel rc.3 will be a breaking change |
| v1.0.0-rc.5                  | v1.0.0-rc.3  |       |
| v1.0.0-rc.6                  | v1.0.0-rc.4  |       |
| v1.0                         | v1.0         |       |

## Note on phoenix integration

`OpentelemetryPhoenix` requires phoenix to use `Plug.Telemetry` in order to correctly trace endpoint calls.

The `endpoint.ex` file should look like:
```Elixir
defmodule MyApp.Endpoint do
  use Phoenix.Endpoint, otp_app: :my_app
  ...
  plug Plug.Telemetry, event_prefix: [:phoenix, :endpoint]
  ...
end
```
The [Phoenix endpoint.ex template](https://github.com/phoenixframework/phoenix/blob/v1.6.0/installer/templates/phx_web/endpoint.ex#L39) can be used as a reference