OpenTelemetry Test Processor

https://hexdocs.pm/opentelemetry_test_processor/
Admin
OpenTelemetry Test Processor is a test span processor that behaves like Mox for OpenTelemetry traces...
Tokens:4,370
Snippets:46
Trust Score:9
Update:1 month ago
Show doc for...
Tokens:
Raw
### Example usage of start/1

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

Example showing how to start tracking spans in a test.

```elixir
test "my test" do
  OpenTelemetryTestProcessor.start()
  # ... test code that generates spans
  assert_receive {:trace_span, span}
end
```

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

### Example usage of set_from_context/1

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

Example showing how to use set_from_context in a setup block.

```elixir
setup :set_from_context
```

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

### Example usage of set_private/1

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

Example showing how to use set_private in a setup block.

```elixir
setup :set_private
```

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

### Example usage of set_global/1

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

Example showing how to use set_global in a setup block.

```elixir
setup :set_global
```

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

### Example usage of allow/2

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

Example showing how to explicitly allow a spawned process to send spans to the test process.

```elixir
test "with explicit allow" do
  OpenTelemetryTestProcessor.start()

  spawn(fn ->
    OpenTelemetryTestProcessor.allow(self(), other_pid)
    MyApp.do_something_traced()
  end)

  assert_receive {:trace_span, span}
end
```

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

### start_link(config)

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

Starts the processor linked to the current process. This function is typically used in supervision trees or test setup.

```APIDOC
## start_link(config)

### Description
Starts the processor linked to the current process. This function is typically used in supervision trees or test setup.

### Parameters
- **config** - Required - Configuration for the processor.

### Returns
- The result of starting the processor.
```

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

### Specification for start/1

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

The function specification for starting span tracking for a process.

```elixir
@spec start(pid_or_name()) :: :ok | {:error, term()}
```

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

### start(owner_pid \\ self())

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

Starts tracking spans for the given process. The process will receive all spans that are ended by itself or any of its child processes via `send(pid, {:trace_span, span})`.

```APIDOC
## start(owner_pid \\ self())

### Description
Starts tracking spans for the given process. The process will receive all spans that are ended by itself or any of its child processes via `send(pid, {:trace_span, span})`.

### Spec
@spec start(pid_or_name()) :: :ok | {:error, term()}

### Parameters
- **owner_pid** (pid_or_name()) - Optional - The process that will receive the spans. Defaults to `self()`.

### Returns
- :ok | {:error, term()}

### Example
```elixir
test "my test" do
  OpenTelemetryTestProcessor.start()
  # ... test code that generates spans
  assert_receive {:trace_span, span}
end
```
```

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

### start_link(config)

Source: https://hexdocs.pm/opentelemetry_test_processor/OpenTelemetryTestProcessor.html

Starts the processor linked to the current process. This function is used internally by the OpenTelemetry configuration.

```APIDOC
## start_link(config)

### Description
Starts the processor linked to the current process. This function is used internally by the OpenTelemetry configuration.

### Function Signature
`start_link(config)`

### Parameters
- **config** (term()) - Required - The configuration for the processor.

### Returns
- The result of starting the processor (likely `{:ok, pid}` or `{:error, term()}`).
```

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

### Receive spans in tests

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

Start the processor and use assert_receive to verify generated spans.

```elixir
test "receives spans" do
  OpenTelemetryTestProcessor.start()

  # Your code that generates spans
  MyApp.do_something_traced()

  # Assert on received spans
  assert_receive {:trace_span, span}
end
```

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

### Test receiving a span with OpentelemetryTestProcessor

Source: https://hexdocs.pm/opentelemetry_test_processor/OpenTelemetryTestProcessor.Span.html

Use this in an ExUnit test to start the test processor, create a span with the Tracer, and assert on the received span struct. The span is received as a {:trace_span, span} message and converted to the OpenTelemetryTestProcessor.Span struct.

```elixir
test "receive span" do
  OpentelemetryTestProcessor.start()

  Tracer.with_span "my span" do
    Tracer.set_status(:ok)
    Tracer.set_attributes(%{"key" => "value"})
    Tracer.add_event("my event", %{"event_key" => "event_value"})
  end

  assert_receive {:trace_span, span}
  assert %OpentelemetryTestProcessor.Span{} = span
  assert span.name == "my span"
  assert span.status == %{status: :ok, message: ""}
  assert span.attributes == %{"key" => "value"}
  assert [%{type: "my event", attributes: %{"event_key" => "event_value"}}] = span.events
end
```

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

### Configure OpenTelemetryTestProcessor with timeout

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

Optionally configure the timeout in milliseconds for the NimbleOwnership server.

```elixir
config :opentelemetry,
  traces_exporter: :none,
  processors: [
    {OpenTelemetryTestProcessor, %{timeout: 10_000}}
  ]
```

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

### set_from_context(context)

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

Chooses the processor mode based on context. When `async: true` is used, `set_private/1` is called, otherwise `set_global/1` is used.

```APIDOC
## set_from_context(context)

### Description
Chooses the processor mode based on context. When `async: true` is used, `set_private/1` is called, otherwise `set_global/1` is used.

### Spec
@spec set_from_context(term()) :: :ok

### Parameters
- **context** (term()) - Required - The test context.

### Returns
- :ok

### Example
```elixir
setup :set_from_context
```
```

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

### Specification for set_from_context/1

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

The function specification for setting the processor mode based on context.

```elixir
@spec set_from_context(term()) :: :ok
```

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

### event(args \\ [])

Source: https://hexdocs.pm/opentelemetry_test_processor/OpenTelemetryTestProcessor.Span.html

Macro to create an event map for testing purposes. It constructs an event with the given arguments, defaulting to an empty list.

```APIDOC
## event(args \\ [])

### Description
Macro to create an event map for testing purposes. It constructs an event with the given arguments, defaulting to an empty list.

### Method
Macro

### Parameters
- **args** (list) - Optional - Arguments for the event, default is []

### Returns
An event map.
```

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

### status(args \\ [])

Source: https://hexdocs.pm/opentelemetry_test_processor/OpenTelemetryTestProcessor.Span.html

Macro to create a status map for testing purposes. It constructs a status map with the given arguments, defaulting to an empty list.

```APIDOC
## status(args \\ [])

### Description
Macro to create a status map for testing purposes. It constructs a status map with the given arguments, defaulting to an empty list.

### Method
Macro

### Parameters
- **args** (list) - Optional - Arguments for the status, default is []

### Returns
A status map with keys :status and :message.
```

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

### Configure OpenTelemetryTestProcessor in test config

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

Add the processor to your OpenTelemetry configuration in the test environment.

```elixir
config :opentelemetry,
  traces_exporter: :none,
  processors: [
    {OpenTelemetryTestProcessor, %{}}
  ]
```

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

### set_private(context \\ %{})

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

Sets the processor to private mode. In private mode, processes must explicitly opt-in with `start/1` and can allow other processes with `allow/2`. This is the default mode and is safe for `async: true` tests.

```APIDOC
## set_private(context \\ %{})

### Description
Sets the processor to private mode. In private mode, processes must explicitly opt-in with `start/1` and can allow other processes with `allow/2`. This is the default mode and is safe for `async: true` tests.

### Spec
@spec set_private(term()) :: :ok

### Parameters
- **context** (term()) - Optional - The test context. Defaults to `%{}`.

### Returns
- :ok

### Example
```elixir
setup :set_private
```
```

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

### event(record, args)

Source: https://hexdocs.pm/opentelemetry_test_processor/OpenTelemetryTestProcessor.Span.html

Macro to create an event map from a record and arguments. It extracts event information from the given record.

```APIDOC
## event(record, args)

### Description
Macro to create an event map from a record and arguments. It extracts event information from the given record.

### Method
Macro

### Parameters
- **record** (record) - Required - The record to extract event information from
- **args** (list) - Required - Arguments for the event

### Returns
An event map.
```

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

### Specification for set_global/1

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

The function specification for setting the processor to global mode.

```elixir
@spec set_global(term()) :: :ok
```

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

### Allow spans from async tasks

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

Use allow/2 to permit non-child processes to participate in span tracking.

```elixir
test "with async task" do
  OpenTelemetryTestProcessor.start()

  task = Task.async(fn ->
    OpenTelemetryTestProcessor.allow(self(), task_pid)
    MyApp.do_something_traced()
  end)

  assert_receive {:trace_span, span}
end
```

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

### status(record, args)

Source: https://hexdocs.pm/opentelemetry_test_processor/OpenTelemetryTestProcessor.Span.html

Macro to create a status map from a record and arguments. It extracts status information from the given record.

```APIDOC
## status(record, args)

### Description
Macro to create a status map from a record and arguments. It extracts status information from the given record.

### Method
Macro

### Parameters
- **record** (record) - Required - The record to extract status information from
- **args** (list) - Required - Arguments for the status

### Returns
A status map with keys :status and :message.
```

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

### span(args \\ [])

Source: https://hexdocs.pm/opentelemetry_test_processor/OpenTelemetryTestProcessor.Span.html

Macro to create a span struct for testing purposes. It constructs a span with the given arguments, defaulting to an empty list.

```APIDOC
## span(args \\ [])

### Description
Macro to create a span struct for testing purposes. It constructs a span with the given arguments, defaulting to an empty list.

### Method
Macro

### Parameters
- **args** (list) - Optional - Arguments for the span, default is []

### Returns
An OpenTelemetryTestProcessor.Span struct.
```

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

### allow(owner_pid, allowed_pid)

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

Allows the given process to use spans from the owner process. When spans are ended by the allowed process, they are sent to the owner process. Useful for allowing non-child processes to participate in span tracking.

```APIDOC
## allow(owner_pid, allowed_pid)

### Description
Allows `allowed_pid` to use spans from `owner_pid`. When spans are ended by `allowed_pid`, they will be sent to `owner_pid`. This is useful for allowing non-child processes to participate in span tracking.

### Spec
@spec allow(pid_or_name(), pid_or_name()) :: :ok | {:error, term()}

### Parameters
- **owner_pid** (pid_or_name()) - Required - The process that will receive the spans.
- **allowed_pid** (pid_or_name()) - Required - The process that is allowed to send spans to the owner.

### Returns
- :ok | {:error, term()}

### Example
```elixir
test "with explicit allow" do
  OpenTelemetryTestProcessor.start()

  spawn(fn ->
    OpenTelemetryTestProcessor.allow(self(), other_pid)
    MyApp.do_something_traced()
  end)

  assert_receive {:trace_span, span}
end
```
```

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

### Specification for allow/2

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

The function specification for allowing a process to use spans from an owner.

```elixir
@spec allow(pid_or_name(), pid_or_name()) :: :ok | {:error, term()}
```

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

### span(record, args)

Source: https://hexdocs.pm/opentelemetry_test_processor/OpenTelemetryTestProcessor.Span.html

Macro to create a span struct from a record and arguments. It extracts span information from the given record.

```APIDOC
## span(record, args)

### Description
Macro to create a span struct from a record and arguments. It extracts span information from the given record.

### Method
Macro

### Parameters
- **record** (record) - Required - The record to extract span information from
- **args** (list) - Required - Arguments for the span

### Returns
An OpenTelemetryTestProcessor.Span struct.
```

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

### Define pid_or_name type

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

The type definition for a process identifier or name.

```elixir
@type pid_or_name() :: pid() | atom()
```

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

### set_global(arg1)

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

Sets the processor to global mode. In global mode, all spans are sent to the shared owner process. Tests using global mode cannot be `async: true`.

```APIDOC
## set_global(arg1)

### Description
Sets the processor to global mode. In global mode, all spans are sent to the shared owner process. Tests using global mode cannot be `async: true`.

### Spec
@spec set_global(term()) :: :ok

### Parameters
- **arg1** (term()) - Required - The test context.

### Returns
- :ok

### Example
```elixir
setup :set_global
```
```

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

### Specification for set_private/1

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

The function specification for setting the processor to private mode.

```elixir
@spec set_private(term()) :: :ok
```

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

### from_otel_span(otel_span)

Source: https://hexdocs.pm/opentelemetry_test_processor/OpenTelemetryTestProcessor.Span.html

Converts a raw OpenTelemetry span record into an OpenTelemetryTestProcessor.Span struct. This function is used internally to transform span data for testing.

```APIDOC
## from_otel_span(otel_span)

### Description
Converts a raw OpenTelemetry span record into an OpenTelemetryTestProcessor.Span struct. This function is used internally to transform span data for testing.

### Method
Function

### Parameters
- **otel_span** (record) - Required - The raw OpenTelemetry span record

### Returns
An OpenTelemetryTestProcessor.Span struct.
```

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

### Access original span with Span.span record

Source: https://hexdocs.pm/opentelemetry_test_processor/OpenTelemetryTestProcessor.Span.html

Use this to extract information from the raw OpenTelemetry span record via the :original_span field. Requires the OpenTelemetryTestProcessor.Span module and uses the span record macro.

```elixir
require OpenTelemetryTestProcessor.Span
Span.span(name: name) = span.original_span
```

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

### Type definition for status()

Source: https://hexdocs.pm/opentelemetry_test_processor/OpenTelemetryTestProcessor.Span.html

Defines the status type used in the Span struct, containing a status code and an optional message.

```elixir
@type status() :: %{status: OpenTelemetry.status_code(), message: String.t() | nil}
```

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

### Type definition for t()

Source: https://hexdocs.pm/opentelemetry_test_processor/OpenTelemetryTestProcessor.Span.html

Defines the full Span struct type with all fields including attributes, events, name, original_span, parent_span_id, span_id, status, and trace_id.

```elixir
@type t() :: %OpenTelemetryTestProcessor.Span{
  attributes: %{optional(String.t()) => any()},
  events: [map()],
  name: String.t(),
  original_span: any(),
  parent_span_id: non_neg_integer() | nil,
  span_id: non_neg_integer() | nil,
  status: status(),
  trace_id: non_neg_integer() | nil
}
```
Tokens:
Raw