O11y (O11y v0.1.1)

A module to help with OpenTelemetry tracing.

Summary

Functions

This is the counterpart to get_distributed_trace_ctx/0. It is used to "extract" trace context information from http headers. This context information is stored in a string so it can be passed around by other means as well.

This function is typically used to "inject" trace context information into http headers such that the trace can be continued in another service. However, it can also be used to link span in cases where OpenTelemetry.Ctx.attach/1 will not work (such as when the parent span has already ended or been removed from the dictionary).

Records an exception and sets the status of the current span to error.

Sets the given attribute on the current span. If the value is not a valid OTLP type, it will be converted to a string with inspect.

Adds the given attributes as a list, map, or struct to the current span. If the value is a maps or struct, it will be converted to a list of key-value pairs. If the struct derives the O11y.SpanAttributes protocol, it will honor the except and only options.

Same as set_attributes/1, but with a prefix for all keys.

Sets the status of the current span to error

Sets the status of the current span to error, and sets an error attribute

Functions

Link to this function

attach_distributed_trace_ctx(dist_trace_ctx)

This is the counterpart to get_distributed_trace_ctx/0. It is used to "extract" trace context information from http headers. This context information is stored in a string so it can be passed around by other means as well.

Example:

iex> O11y.attach_distributed_trace_ctx([traceparent: "00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01"])
iex> O11y.attach_distributed_trace_ctx("00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01")
iex> O11y.attach_distributed_trace_ctx(nil)
Link to this function

get_distributed_trace_ctx()

This function is typically used to "inject" trace context information into http headers such that the trace can be continued in another service. However, it can also be used to link span in cases where OpenTelemetry.Ctx.attach/1 will not work (such as when the parent span has already ended or been removed from the dictionary).

Example:

iex> res = Tracer.with_span "some_span", do: O11y.get_distributed_trace_ctx()
iex> [{"traceparent", _}] = res
Link to this function

record_exception(exception)

Records an exception and sets the status of the current span to error.

Example:

iex> O11y.record_exception(%RuntimeError{message: "something went wrong"})
%RuntimeError{message: "something went wrong"}

Produces a span like:

{:span, 28221055821181380594370570739471883760, 5895012157721301439, [],
  :undefined, "checkout", :internal, -576460751313205167, -576460751311430083,
  {:attributes, 128, :infinity, 0, %{}},
  {:events, 128, 128, :infinity, 0,
  [
    {:event, -576460751311694042, "exception",
     {:attributes, 128, :infinity, 0,
      %{
        "exception.message": "something went wrong",
        "exception.stacktrace": "...",
        "exception.type": "Elixir.RuntimeError"
      }}}
  ]}, {:links, 128, 128, :infinity, 0, []}, {:status, :error, ""}, 1, false,
  :undefined}
Link to this function

set_attribute(key, value)

Sets the given attribute on the current span. If the value is not a valid OTLP type, it will be converted to a string with inspect.

This method does not support structs to maps, regardless of whether the struct implements the O11y.SpanAttributes protocol. You need to use set_attributes/1 for that.

Example:

iex> O11y.set_attribute("key", "value")
:ok

Produces span attributes like:

{:attributes, 128, :infinity, 0, %{key: "value"}}
Link to this function

set_attributes(values)

Adds the given attributes as a list, map, or struct to the current span. If the value is a maps or struct, it will be converted to a list of key-value pairs. If the struct derives the O11y.SpanAttributes protocol, it will honor the except and only options.

Example:

iex> O11y.set_attributes(%{id: 123, name: "Alice"})
%{id: 123, name: "Alice"}

Produces span attributes like:

{:attributes, 128, :infinity, 0, %{id: 123, name: "Alice"}}
Link to this function

set_attributes(prefix, values)

Same as set_attributes/1, but with a prefix for all keys.

Example:

iex> O11y.set_attributes("user", %{name: "Steve", age: 47})
%{name: "Steve", age: 47}

Produces span attributes like:

{:attributes, 128, :infinity, 0, %{"user.age" => 47, "user.name" => "Steve"}}

Sets the status of the current span to error

Link to this function

set_error(error)

Sets the status of the current span to error, and sets an error attribute