OpenTelemetry API v0.3.1 OpenTelemetry

An OpenTelemetry Trace consists of 1 or more Spans that either have a parent/child relationship or are linked together through a Link. Each Span has a TraceId (trace_id/0), SpanId (span_id/0), and a start and end time in nanoseconds.

This module provides declaration of the types used throughout the library, as well as functions for building the additional pieces of a span that are optional. Each item can be attached to individual Span using the functions in OpenTelemetry.Span module.

Example

require OpenTelemetry.Tracer
require OpenTelemetry.Span

OpenTelemetry.register_application_tracer(:this_otp_app)

Tracer.start_span("some-span")
...
ecto_event = OpenTelemetry.event("ecto.query", [{"query", query}, {"total_time", total_time}])
OpenTelemetry.Span.add_event(ecto_event)
...
Tracer.end_span()

Link to this section Summary

Types

Attributes are a collection of key/value pairs. The value can be a string, an integer, a double or the boolean values true or false. Note, global attributes like server name can be set using the resource API.

An Event is a time-stamped annotation of the span, consisting of user-supplied text description and key-value pairs.

A Link is a pointer from the current span to another span in the same trace or in a different trace. For example, this can be used in batching operations, where a single batch handler processes multiple requests from different traces or when the handler receives a request from a different project.

Span represents a single operation within a trace. Spans can be nested to form a trace tree. Spans may also be linked to other spans from the same or different trace and form graphs. Often, a trace contains a root span that describes the end-to-end latency, and one or more subspans for its sub-operations. A trace can also contain multiple root spans, or none at all. Spans do not need to be contiguous - there may be gaps or overlaps between spans in a trace.

A SpanContext represents the portion of a Span which must be as well as being serialized and propagated along side of a distributed context.

SpanId is a unique identifier for a span within a trace, assigned when the span is created. The ID is an 8-byte array. An ID with all zeroes is considered invalid.

An optional final status for this span. Semantically when Status wasn't set it means span ended without errors and assume Ok.

TraceId is a unique identifier for a trace. All spans from the same trace share the same trace_id. The ID is a 16-byte array. An ID with all zeroes is considered invalid.

Tracestate represents tracing-system specific context in a list of key-value pairs. Tracestate allows different vendors propagate additional information and inter-operate with their legacy Id formats.

Functions

Creates a list of event/0 items.

Creates a list of link/0 from a list of 3-tuples.

See :opentelemetry.register_application_meter/1.

Current time in UNIX Epoch time, nanoseconds since 00:00:00 UTC on 1 January 1970.

Creates a Status.

See :opentelemetry.timestamp/0.

Link to this section Types

Link to this type

attribute_key()

attribute_key() :: String.t()
Link to this type

attribute_value()

attribute_value() :: String.t() | integer() | float() | boolean()
Link to this type

attributes()

attributes() :: [{attribute_key(), attribute_value()}]

Attributes are a collection of key/value pairs. The value can be a string, an integer, a double or the boolean values true or false. Note, global attributes like server name can be set using the resource API.

Examples of attributes:

[{"/http/user_agent" "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/71.0.3578.98 Safari/537.36"}
 {"/http/server_latency", 300}
 {"abc.com/myattribute", True}
 {"abc.com/score", 10.239}]
Link to this type

event()

event() :: :opentelemetry.event()

An Event is a time-stamped annotation of the span, consisting of user-supplied text description and key-value pairs.

Link to this type

link()

link() :: :opentelemetry.link()

A Link is a pointer from the current span to another span in the same trace or in a different trace. For example, this can be used in batching operations, where a single batch handler processes multiple requests from different traces or when the handler receives a request from a different project.

Link to this type

span()

span() :: :opentelemetry.span()

Span represents a single operation within a trace. Spans can be nested to form a trace tree. Spans may also be linked to other spans from the same or different trace and form graphs. Often, a trace contains a root span that describes the end-to-end latency, and one or more subspans for its sub-operations. A trace can also contain multiple root spans, or none at all. Spans do not need to be contiguous - there may be gaps or overlaps between spans in a trace.

Link to this type

span_ctx()

span_ctx() :: :opentelemetry.span_ctx()

A SpanContext represents the portion of a Span which must be as well as being serialized and propagated along side of a distributed context.

Link to this type

span_id()

span_id() :: non_neg_integer()

SpanId is a unique identifier for a span within a trace, assigned when the span is created. The ID is an 8-byte array. An ID with all zeroes is considered invalid.

Link to this type

status()

status() :: :opentelemetry.status()

An optional final status for this span. Semantically when Status wasn't set it means span ended without errors and assume Ok.

Link to this type

trace_id()

trace_id() :: non_neg_integer()

TraceId is a unique identifier for a trace. All spans from the same trace share the same trace_id. The ID is a 16-byte array. An ID with all zeroes is considered invalid.

Link to this type

tracestate()

tracestate() :: [{String.t(), String.t()}]

Tracestate represents tracing-system specific context in a list of key-value pairs. Tracestate allows different vendors propagate additional information and inter-operate with their legacy Id formats.

It is a tracestate in the w3c-trace-context format. See also https://github.com/w3c/distributed-tracing for more details about this field.

Link to this section Functions

Link to this function

event(name, attributes)

event(String.t(), attributes()) :: event()

Creates a event/0.

Link to this function

event(timestamp, name, attributes)

event(integer(), String.t(), attributes()) :: event()

Creates a event/0.

Link to this function

events(event_list)

events(list()) :: [event()]

Creates a list of event/0 items.

Link to this function

link(trace_id, span_id, attributes, tracestate)

link(trace_id(), span_id(), attributes(), tracestate()) :: link()

Creates a link/0.

Link to this function

links(link_list)

links([{integer(), integer(), list(), list()}]) :: [link()]

Creates a list of link/0 from a list of 3-tuples.

Link to this function

register_application_meter(name)

See :opentelemetry.register_application_meter/1.

Link to this function

register_application_tracer(otp_app)

register_application_tracer(atom()) :: boolean()

Current time in UNIX Epoch time, nanoseconds since 00:00:00 UTC on 1 January 1970.

Link to this function

status(code, message)

status(atom(), String.t()) :: status()

Creates a Status.

Link to this function

timestamp()

timestamp() :: integer()

See :opentelemetry.timestamp/0.