instrument_test (instrument v1.0.0)

View Source

Test helpers for validating instrumentation in EUnit and Common Test.

This module provides collector exporters and assertion helpers for testing spans, metrics, and logs in your instrumented code.

Quick Start

  my_test() ->
      instrument_test:setup(),
      try
          %% Your instrumented code
          instrument_tracer:with_span(<<"my_op">>, fun() ->
              do_work()
          end),
 
          %% Assert span was created
          instrument_test:assert_span_exists(<<"my_op">>)
      after
          instrument_test:cleanup()
      end.

Common Test Setup

  init_per_testcase(_TestCase, Config) ->
      instrument_test:setup(),
      Config.
 
  end_per_testcase(_TestCase, _Config) ->
      instrument_test:cleanup(),
      ok.

Summary

Functions

add_test_log(Log_record)

Adds a log record directly for testing purposes. Ensures the log table exists before inserting.

assert_counter(Name, ExpectedValue)

Asserts a counter has the expected value.

assert_counter(Name, ExpectedValue, Attrs)

Asserts a counter has the expected value with specific attributes.

assert_gauge(Name, ExpectedValue)

Asserts a gauge has the expected value.

assert_gauge(Name, ExpectedValue, Attrs)

Asserts a gauge has the expected value with specific attributes.

assert_histogram_count(Name, ExpectedCount)

Asserts a histogram has the expected observation count.

assert_histogram_sum(Name, ExpectedSum)

Asserts a histogram has the expected sum.

assert_log(BodyPattern, Expected)

Asserts a log record with expected properties. Expected can contain: body, severity_text, severity_number, attributes

assert_log_exists(BodyPattern)

Asserts that a log with the given body pattern exists.

assert_log_trace_context(BodyPattern)

Asserts that a log has trace context (trace_id and span_id).

assert_no_span(Name)

Asserts that no span with the given name exists.

assert_parent_child(ParentName, ChildName)

Asserts that ParentName is the parent of ChildName.

assert_span(Name, Expected)

Asserts a span with expected properties. Expected can contain: attributes, status, kind, parent

assert_span_attribute(SpanName, Key, ExpectedValue)

Asserts a specific attribute value on a span.

assert_span_event(SpanName, EventName)

Asserts that a span has an event with the given name.

assert_span_exists(Name)

Asserts that a span with the given name exists.

assert_span_status(SpanName, ExpectedStatus)

Asserts the status of a span.

cleanup()

Cleans up the test environment. Stops collectors and clears all state.

clear_logs()

Clears all captured logs.

clear_metrics()

Clears collected metrics.

clear_spans()

Clears all captured spans.

collect_metrics()

Triggers metrics collection and returns the results.

get_logs()

Returns all captured logs.

get_metrics()

Returns all collected metrics.

get_span(Name)

Returns a span by name.

get_spans()

Returns all captured spans.

reset()

Resets collectors between test cases without full cleanup. Use this when you want to keep the application running but clear collected data. Also ensures all collector tables exist.

setup()

Sets up the test environment. Starts the instrument application and all collectors.

start_log_collector()

Starts the log collector.

start_metrics_collector()

Starts the metrics collector.

start_span_collector()

Starts the span collector. Registers an ETS-based exporter that captures all completed spans.

stop_log_collector()

Stops the log collector.

stop_metrics_collector()

Stops the metrics collector.

stop_span_collector()

Stops the span collector.

wait_for_logs(Count, Timeout)

Waits for a specific number of logs with timeout.

wait_for_spans(Count, Timeout)

Waits for a specific number of spans with timeout.

Functions

add_test_log(Log_record)

-spec add_test_log(#log_record{timestamp :: integer() | undefined,
                               observed_timestamp :: integer() | undefined,
                               severity_number :: integer() | undefined,
                               severity_text :: binary() | undefined,
                               body :: term(),
                               attributes :: map(),
                               trace_id :: <<_:128>> | undefined,
                               span_id :: <<_:64>> | undefined,
                               trace_flags :: 0 | 1 | undefined,
                               resource ::
                                   #resource{attributes :: map(), schema_url :: binary() | undefined} |
                                   undefined,
                               scope ::
                                   #scope{name :: binary(),
                                          version :: binary() | undefined,
                                          attributes :: map(),
                                          schema_url :: binary() | undefined} |
                                   undefined}) ->
                      ok.

Adds a log record directly for testing purposes. Ensures the log table exists before inserting.

assert_counter(Name, ExpectedValue)

-spec assert_counter(binary() | atom(), number()) -> ok.

Asserts a counter has the expected value.

assert_counter(Name, ExpectedValue, Attrs)

-spec assert_counter(binary() | atom(), number(), map()) -> ok.

Asserts a counter has the expected value with specific attributes.

assert_gauge(Name, ExpectedValue)

-spec assert_gauge(binary() | atom(), number()) -> ok.

Asserts a gauge has the expected value.

assert_gauge(Name, ExpectedValue, Attrs)

-spec assert_gauge(binary() | atom(), number(), map()) -> ok.

Asserts a gauge has the expected value with specific attributes.

assert_histogram_count(Name, ExpectedCount)

-spec assert_histogram_count(binary() | atom(), non_neg_integer()) -> ok.

Asserts a histogram has the expected observation count.

assert_histogram_sum(Name, ExpectedSum)

-spec assert_histogram_sum(binary() | atom(), number()) -> ok.

Asserts a histogram has the expected sum.

assert_log(BodyPattern, Expected)

-spec assert_log(term(), map()) -> ok.

Asserts a log record with expected properties. Expected can contain: body, severity_text, severity_number, attributes

assert_log_exists(BodyPattern)

-spec assert_log_exists(term()) -> ok.

Asserts that a log with the given body pattern exists.

assert_log_trace_context(BodyPattern)

-spec assert_log_trace_context(term()) -> ok.

Asserts that a log has trace context (trace_id and span_id).

assert_no_span(Name)

-spec assert_no_span(binary() | atom()) -> ok.

Asserts that no span with the given name exists.

assert_parent_child(ParentName, ChildName)

-spec assert_parent_child(binary() | atom(), binary() | atom()) -> ok.

Asserts that ParentName is the parent of ChildName.

assert_span(Name, Expected)

-spec assert_span(binary() | atom(), map()) -> ok.

Asserts a span with expected properties. Expected can contain: attributes, status, kind, parent

assert_span_attribute(SpanName, Key, ExpectedValue)

-spec assert_span_attribute(binary() | atom(), term(), term()) -> ok.

Asserts a specific attribute value on a span.

assert_span_event(SpanName, EventName)

-spec assert_span_event(binary() | atom(), binary()) -> ok.

Asserts that a span has an event with the given name.

assert_span_exists(Name)

-spec assert_span_exists(binary() | atom()) -> ok.

Asserts that a span with the given name exists.

assert_span_status(SpanName, ExpectedStatus)

-spec assert_span_status(binary() | atom(), ok | unset | {error, binary()}) -> ok.

Asserts the status of a span.

cleanup()

-spec cleanup() -> ok.

Cleans up the test environment. Stops collectors and clears all state.

clear_logs()

-spec clear_logs() -> ok.

Clears all captured logs.

clear_metrics()

-spec clear_metrics() -> ok.

Clears collected metrics.

clear_spans()

-spec clear_spans() -> ok.

Clears all captured spans.

collect_metrics()

-spec collect_metrics() -> [map()].

Triggers metrics collection and returns the results.

get_logs()

-spec get_logs() ->
                  [#log_record{timestamp :: integer() | undefined,
                               observed_timestamp :: integer() | undefined,
                               severity_number :: integer() | undefined,
                               severity_text :: binary() | undefined,
                               body :: term(),
                               attributes :: map(),
                               trace_id :: <<_:128>> | undefined,
                               span_id :: <<_:64>> | undefined,
                               trace_flags :: 0 | 1 | undefined,
                               resource ::
                                   #resource{attributes :: map(), schema_url :: binary() | undefined} |
                                   undefined,
                               scope ::
                                   #scope{name :: binary(),
                                          version :: binary() | undefined,
                                          attributes :: map(),
                                          schema_url :: binary() | undefined} |
                                   undefined}].

Returns all captured logs.

get_metrics()

-spec get_metrics() -> [map()].

Returns all collected metrics.

get_span(Name)

-spec get_span(binary()) ->
                  {ok,
                   #span{name :: binary(),
                         ctx ::
                             #span_ctx{trace_id :: <<_:128>> | undefined,
                                       span_id :: <<_:64>> | undefined,
                                       trace_flags :: 0 | 1,
                                       trace_state :: [{binary(), binary()}],
                                       is_remote :: boolean()},
                         parent_ctx ::
                             #span_ctx{trace_id :: <<_:128>> | undefined,
                                       span_id :: <<_:64>> | undefined,
                                       trace_flags :: 0 | 1,
                                       trace_state :: [{binary(), binary()}],
                                       is_remote :: boolean()} |
                             undefined,
                         tracer ::
                             #tracer{name :: binary(),
                                     version :: binary() | undefined,
                                     schema_url :: binary() | undefined,
                                     resource ::
                                         #resource{attributes :: map(),
                                                   schema_url :: binary() | undefined} |
                                         undefined} |
                             undefined,
                         kind :: client | server | producer | consumer | internal,
                         start_time :: integer(),
                         end_time :: integer() | undefined,
                         attributes :: map(),
                         events ::
                             [#span_event{name :: binary(),
                                          timestamp :: integer(),
                                          attributes :: map(),
                                          dropped_attributes_count :: non_neg_integer()}],
                         links ::
                             [#span_link{ctx ::
                                             #span_ctx{trace_id :: <<_:128>> | undefined,
                                                       span_id :: <<_:64>> | undefined,
                                                       trace_flags :: 0 | 1,
                                                       trace_state :: [{binary(), binary()}],
                                                       is_remote :: boolean()},
                                         attributes :: map(),
                                         dropped_attributes_count :: non_neg_integer()}],
                         status :: unset | ok | {error, binary()},
                         is_recording :: boolean(),
                         dropped_attributes_count :: non_neg_integer(),
                         dropped_events_count :: non_neg_integer(),
                         dropped_links_count :: non_neg_integer()}} |
                  {error, not_found}.

Returns a span by name.

get_spans()

-spec get_spans() ->
                   [#span{name :: binary(),
                          ctx ::
                              #span_ctx{trace_id :: <<_:128>> | undefined,
                                        span_id :: <<_:64>> | undefined,
                                        trace_flags :: 0 | 1,
                                        trace_state :: [{binary(), binary()}],
                                        is_remote :: boolean()},
                          parent_ctx ::
                              #span_ctx{trace_id :: <<_:128>> | undefined,
                                        span_id :: <<_:64>> | undefined,
                                        trace_flags :: 0 | 1,
                                        trace_state :: [{binary(), binary()}],
                                        is_remote :: boolean()} |
                              undefined,
                          tracer ::
                              #tracer{name :: binary(),
                                      version :: binary() | undefined,
                                      schema_url :: binary() | undefined,
                                      resource ::
                                          #resource{attributes :: map(),
                                                    schema_url :: binary() | undefined} |
                                          undefined} |
                              undefined,
                          kind :: client | server | producer | consumer | internal,
                          start_time :: integer(),
                          end_time :: integer() | undefined,
                          attributes :: map(),
                          events ::
                              [#span_event{name :: binary(),
                                           timestamp :: integer(),
                                           attributes :: map(),
                                           dropped_attributes_count :: non_neg_integer()}],
                          links ::
                              [#span_link{ctx ::
                                              #span_ctx{trace_id :: <<_:128>> | undefined,
                                                        span_id :: <<_:64>> | undefined,
                                                        trace_flags :: 0 | 1,
                                                        trace_state :: [{binary(), binary()}],
                                                        is_remote :: boolean()},
                                          attributes :: map(),
                                          dropped_attributes_count :: non_neg_integer()}],
                          status :: unset | ok | {error, binary()},
                          is_recording :: boolean(),
                          dropped_attributes_count :: non_neg_integer(),
                          dropped_events_count :: non_neg_integer(),
                          dropped_links_count :: non_neg_integer()}].

Returns all captured spans.

reset()

-spec reset() -> ok.

Resets collectors between test cases without full cleanup. Use this when you want to keep the application running but clear collected data. Also ensures all collector tables exist.

setup()

-spec setup() -> ok.

Sets up the test environment. Starts the instrument application and all collectors.

start_log_collector()

-spec start_log_collector() -> ok.

Starts the log collector.

start_metrics_collector()

-spec start_metrics_collector() -> ok.

Starts the metrics collector.

start_span_collector()

-spec start_span_collector() -> ok.

Starts the span collector. Registers an ETS-based exporter that captures all completed spans.

stop_log_collector()

-spec stop_log_collector() -> ok.

Stops the log collector.

stop_metrics_collector()

-spec stop_metrics_collector() -> ok.

Stops the metrics collector.

stop_span_collector()

-spec stop_span_collector() -> ok.

Stops the span collector.

wait_for_logs(Count, Timeout)

-spec wait_for_logs(pos_integer(), pos_integer()) -> ok | {error, timeout}.

Waits for a specific number of logs with timeout.

wait_for_spans(Count, Timeout)

-spec wait_for_spans(pos_integer(), pos_integer()) -> ok | {error, timeout}.

Waits for a specific number of spans with timeout.