Opentelemetry Req

https://hexdocs.pm/opentelemetry_req/
Admin
Opentelemetry Req is an Elixir plugin for the Req HTTP client that provides OpenTelemetry...
Tokens:2,149
Snippets:24
Trust Score:9
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install opentelemetry_req dependency

Source: https://hexdocs.pm/opentelemetry_req/readme.html

Add the opentelemetry_req package to your project's dependencies in the mix.exs file.

```elixir
def deps do
  [
    {:opentelemetry_req, "~> 1.0.0-beta.1"}
  ]
end
```

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

### Attach with opt-in URL template attribute

Source: https://hexdocs.pm/opentelemetry_req/OpentelemetryReq.html

Shows how to attach OpentelemetryReq with the opt-in `url_template` attribute, which is required for span names to include the `{target}` portion. The `path_params` option must be set along with a templated path using `:colon` style.

```elixir
client =
  Req.new()
  |> OpentelemetryReq.attach(
    opt_in_attrs: [SemConv.URLAttributes.url_template()]
  )

client
|> Req.get(
  url: "/api/users/:user_id",
  path_params: [user_id: user_id]
)
```

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

### Propagate trace headers with attach option

Source: https://hexdocs.pm/opentelemetry_req/OpentelemetryReq.html

Shows how to enable trace header propagation by setting `propagate_trace_headers: true` when attaching. This is one of two options; the other is manually using `:otel_propagator_text_map.inject/1`.

```elixir
client =
  Req.new()
  |> OpentelemetryReq.attach(propagate_trace_headers: true)

# or

client =
  Req.new()
  |> OpentelemetryReq.attach()

Req.get(client, "/", propagate_trace_headers: true)
```

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

### Configure Opt-in Semantic Convention Attributes

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

Use the opt_in_attrs option to enable specific semantic convention attributes. Ensure the path_params option is set when using URL templates.

```elixir
client =
  Req.new()
  |>
  OpentelemetryReq.attach(
    opt_in_attrs: [SemConv.URLAttributes.url_template()]
  )

client
|>
Req.get(
  url: "/api/users/:user_id",
  path_params: [user_id: user_id]
)
```

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

### Enable Trace Header Propagation

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

Trace propagation headers can be enabled globally during attachment or per-request.

```elixir
client =
  Req.new()
  |>
  OpentelemetryReq.attach(propagate_trace_headers: true)

# or

client =
  Req.new()
  |>
  OpentelemetryReq.attach()

Req.get(client, "/", propagate_trace_headers: true)
```

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

### Define options Type

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

The options type defines the configuration keys available for OpentelemetryReq.

```elixir
@type options() :: [
  opt_in_attrs: opt_in_attrs(),
  propagate_trace_headers: boolean(),
  request_header_attrs: [binary()],
  response_header_attrs: [binary()],
  span_name: atom() | nil | binary()
]
```

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

### attach(request, options \\ [])

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

Attaches OpenTelemetry instrumentation to a Req request, wrapping it in a span that is created when the request completes or errors. This function is the primary entry point for integrating OpenTelemetry with Req.

```APIDOC
## attach(request, options \\ [])

### Description
Attaches OpenTelemetry instrumentation to a Req request, wrapping it in a span that is created when the request completes or errors. This function is the primary entry point for integrating OpenTelemetry with Req.

### Parameters
- **request** (Req.Request.t()) - Required - The Req request to instrument.
- **options** (options()) - Optional - Configuration options for the instrumentation, including opt-in attributes, trace header propagation, header attributes, and span name override.

### Options
- **opt_in_attrs** (opt_in_attrs()) - Optional - List of opt-in semantic convention attributes to enable. Use the SemConv library for compatibility.
- **propagate_trace_headers** (boolean()) - Optional - If true, injects trace propagation headers into the request. Defaults to false.
- **request_header_attrs** ([binary()]) - Optional - List of request header names (lower-case) to capture as span attributes.
- **response_header_attrs** ([binary()]) - Optional - List of response header names (lower-case) to capture as span attributes.
- **span_name** (atom() | nil | binary()) - Optional - Overrides the span name. Options passed in the request take precedence over those in attach.

### Returns
- **Req.Request.t()** - The modified Req request with OpenTelemetry instrumentation attached.

### Example
```
client =
  Req.new()
  |> OpentelemetryReq.attach(
    opt_in_attrs: [SemConv.URLAttributes.url_template()]
  )

client
|> Req.get(
  url: "/api/users/:user_id",
  path_params: [user_id: user_id]
)
```
```

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

### Attach Function Specification

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

The attach function specification for integrating with a Req request.

```elixir
@spec attach(Req.Request.t(), options()) :: Req.Request.t()
```

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

### Define opt_in_attrs Type

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

The opt_in_attrs type is a list of opt_in_attr values.

```elixir
@type opt_in_attrs() :: [opt_in_attr()]
```

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

### Define opt_in_attr Type

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

The opt_in_attr type defines the allowed semantic convention attributes.

```elixir
@type opt_in_attr() ::
  :"http.request.body.size"
  | :"http.response.body.size"
  | :"network.transport"
  | :"url.scheme"
  | :"url.template"
  | :"user_agent.original"
```

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

### Override Span Name

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

Set the span_name option in the request call to override the default span name.

```elixir
client =
  Req.new()
  |>
  OpentelemetryReq.attach()

Req.get(client, "/", span_name: "custom")
```
Tokens:
Raw