Spandex Phoenix

https://hexdocs.pm/spandex_phoenix/
Admin
Spandex Phoenix provides Phoenix and Plug integrations for the Spandex tracing library, enabling...
Tokens:3,466
Snippets:36
Trust Score:9
Update:1 month ago
Show doc for...
Tokens:
Raw
### install(opts \\ [])

Source: https://hexdocs.pm/spandex_phoenix/SpandexPhoenix.Telemetry.html

Installs `:telemetry` event handlers for Phoenix Telemetry events. Requires `Plug.Telemetry` to be included in your endpoint or router for traces to function properly.

```APIDOC
## install(opts \\ [])

### Description
Installs `:telemetry` event handlers for Phoenix Telemetry events. `Plug.Telemetry` must be included in your endpoint or router for traces to function properly. If you upgraded to Phoenix 1.5, you must add the plug yourself; the Phoenix 1.5 installer includes the plug in your endpoint automatically.

### Method
Function

### Endpoint
install(opts \\ [])

### Parameters
#### Options
- **`:tracer`** (Atom) - Optional - The tracing module to be used for traces in your Endpoint. Default: `Application.get_env(:spandex_phoenix, :tracer)`
- **`:endpoint_telemetry_prefix`** (Atom) - Optional - The telemetry prefix passed to `Plug.Telemetry` in the endpoint you want to trace. Default: `[:phoenix, :endpoint]`
- **`:filter_traces`** (fun((Plug.Conn.t()) -> boolean)) - Optional - A function that takes a conn and returns true if a trace should be created for that conn, and false if it should be ignored. Default: `&SpandexPhoenix.trace_all_requests/1`
- **`:span_name`** (String.t()) - Optional - The name for the span this module creates. Default: `"request"`
- **`:span_opts`** (Spandex.Tracer.opts()) - Optional - A list of span options to pass during the creation or continuation of the top level span. Default: `[type: :web]`
- **`:customize_metadata`** (fun((Plug.Conn.t()) -> Keyword.t())) - Optional - A function that takes a conn and returns a keyword list of metadata. Default: `&SpandexPhoenix.default_metadata/1`

### Response
No return value is documented.
```

--------------------------------

### Install SpandexPhoenix Telemetry

Source: https://hexdocs.pm/spandex_phoenix/index.html

Attach Spandex.Telemetry event handlers during application startup for Phoenix 1.5+.

```elixir
defmodule MyApp.Application do
  def start(_, _) do
    # ...
    SpandexPhoenix.Telemetry.install()
    # ...
  end
end
```

--------------------------------

### Customize metadata with customize_metadata option

Source: https://hexdocs.pm/spandex_phoenix/SpandexPhoenix.html

Use the `:customize_metadata` option to customize span metadata. The function takes a `Plug.Conn` and returns a `Keyword` of span options. It is evaluated just before the response is sent. The example shows how to replace a path parameter name with its value in the `resource` field.

```elixir
defmodule MyApp.Tracer do
  use Spandex.Tracer, otp_app: :my_app

  def customize_metadata(conn) do
    name = conn.path_params["name"] || ""

    conn
    |> SpandexPhoenix.default_metadata()
    |> Keyword.update(:resource, "", &String.replace(&1, ":name", name))
  end
end

defmodule MyAppWeb.Endpoint do
  use Phoenix.Endpoint, otp_app: :my_app
  use SpandexPhoenix, customize_metadata: &MyApp.Tracer.customize_metadata/1
  plug Router

end
```

--------------------------------

### Error message for redundant tracing

Source: https://hexdocs.pm/spandex_phoenix/index.html

This error message occurs if you attempt to start a trace over an existing one, which may happen if you use both Phoenix and Plug integrations incorrectly.

```text
[error] Tried to start a trace over top of another trace
```

--------------------------------

### Configure Spandex tracer

Source: https://hexdocs.pm/spandex_phoenix/index.html

Set the desired Spandex.Tracer module in your config.exs.

```elixir
config :spandex_phoenix, tracer: MyApp.Tracer
```

--------------------------------

### Plug integration with SpandexPhoenix

Source: https://hexdocs.pm/spandex_phoenix/SpandexPhoenix.html

Add `use SpandexPhoenix` to your Plug.Router module to trace all requests.

```elixir
defmodule MyApp.Router do
  use Plug.Router
  use SpandexPhoenix

  # ...
end
```

--------------------------------

### Add SpandexPhoenix dependency

Source: https://hexdocs.pm/spandex_phoenix/index.html

Add the :spandex_phoenix dependency to your mix.exs file.

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

--------------------------------

### Phoenix integration with SpandexPhoenix

Source: https://hexdocs.pm/spandex_phoenix/SpandexPhoenix.html

Add `use SpandexPhoenix` to your Phoenix Endpoint module to trace all requests. Place it last if combined with other wrapper plugs like `Plug.ErrorHandler`.

```elixir
defmodule MyAppWeb.Endpoint do
  use Phoenix.Endpoint, otp_app: :my_app
  use SpandexPhoenix

  # ...
end
```

--------------------------------

### Filter traces by HTTP method with filter_traces option

Source: https://hexdocs.pm/spandex_phoenix/SpandexPhoenix.html

Use the `:filter_traces` option to trace only specific requests. The function receives a `Plug.Conn` and returns `true` to trace. Note: use `&__MODULE__.function/1` instead of `&function/1` because the module is not yet compiled.

```elixir
defmodule MyAppWeb.Endpoint do
  use Phoenix.Endpoint, otp_app: :my_app
  use SpandexPhoenix, filter_traces: &__MODULE__.filter_traces/1

  def filter_traces(conn) do
    conn.method in ~w(DELETE GET POST PUT)
  end
end
```

--------------------------------

### Configure Phoenix Endpoint with SpandexPhoenix.Instrumenter

Source: https://hexdocs.pm/spandex_phoenix/SpandexPhoenix.Instrumenter.html

Add SpandexPhoenix.Instrumenter to the instrumenters list in your Phoenix Endpoint configuration to enable automatic span creation for Controller and View information.

```elixir
config :my_app, MyAppWeb.Endpoint,
  # ... existing config ...
  instrumenters: [SpandexPhoenix.Instrumenter]
```

--------------------------------

### trace_all_requests/1 spec

Source: https://hexdocs.pm/spandex_phoenix/SpandexPhoenix.html

Spec for the `trace_all_requests/1` function, which is the default implementation of the `filter_traces` function and always returns `true`.

```elixir
@spec trace_all_requests(Plug.Conn.t()) :: true
```

--------------------------------

### default_metadata/1 spec

Source: https://hexdocs.pm/spandex_phoenix/SpandexPhoenix.html

Spec for the `default_metadata/1` function, which returns a `Keyword` of default span metadata.

```elixir
@spec default_metadata(Plug.Conn.t()) :: Keyword.t()
```
Tokens:
Raw