sinal/span

Runs work inside a native telemetry span, which emits typed start, stop and exception events around it.

Use this module to time a unit of work and report how it ended. define names the span and gives sinal/fields codecs for its start metadata, its extra stop measurements and its stop metadata. run runs the work: [name.., start] is emitted before it, then [name.., stop] when it returns or [name.., exception] when it raises, and the exception is re-raised unchanged. events returns the three typed events, so handlers attach with sinal.observe or sinal.handler.

import sinal/fields
import sinal/span

let query =
  span.define(
    ["db", "query"],
    start_metadata: fields.string("sql"),
    stop_measurements: fields.empty(),
    stop_metadata: fields.int("rows"),
  )
let rows =
  span.run(query, "SELECT 1", fn() {
    let rows = select("SELECT 1")
    span.Completion(result: rows, measurements: Nil, metadata: list.length(rows))
  })

Native telemetry measures the timing fields; duration_in, system_time_in and monotonic_time_in read them in an explicit TimeUnit. A span runs in one process: it ignores forwarder routes, because its start and stop must share a process to measure duration.

Types

Completion

</>

What the work of a span returns: its result, and the stop event’s extra measurements and metadata.

pub type Completion(result, extra_measurements, stop_metadata) {
  Completion(
    result: result,
    measurements: extra_measurements,
    metadata: stop_metadata,
  )
}

Constructors

Completion(
  result: result,
  measurements: extra_measurements,
  metadata: stop_metadata,
)

ExceptionKind

</>

The class of the exception that ended a span.

pub type ExceptionKind {
  ExceptionError
  ExceptionExit
  ExceptionThrow
}

Constructors

```
ExceptionError
```
```
ExceptionExit
```
```
ExceptionThrow
```

ExceptionMeasurements

</>

Measurements of [name.., exception].

pub type ExceptionMeasurements {
  ExceptionMeasurements(
    duration: NativeDuration,
    monotonic_time: MonotonicTime,
  )
}

Constructors

ExceptionMeasurements(
  duration: NativeDuration,
  monotonic_time: MonotonicTime,
)

ExceptionMetadata

</>

Metadata of [name.., exception]: the start metadata and the exception.

pub type ExceptionMetadata(metadata) {
  ExceptionMetadata(
    metadata: metadata,
    context: SpanContext,
    kind: ExceptionKind,
    reason: ExceptionReason,
    stacktrace: ExceptionStacktrace,
  )
}

Constructors

ExceptionMetadata(
  metadata: metadata,
  context: SpanContext,
  kind: ExceptionKind,
  reason: ExceptionReason,
  stacktrace: ExceptionStacktrace,
)

ExceptionReason

opaque </>

The reason of the exception that ended a span.

pub opaque type ExceptionReason

ExceptionStacktrace

opaque </>

The stacktrace of the exception that ended a span.

pub opaque type ExceptionStacktrace

MonotonicTime

opaque </>

A monotonic timestamp in native time units.

pub opaque type MonotonicTime

NativeDuration

opaque </>

A span duration in native time units.

pub opaque type NativeDuration

Span

opaque </>

A typed span definition.

pub opaque type Span(start_metadata, extra_measurements, stop_metadata)

SpanContext

opaque </>

The telemetry_span_context that links one span’s events. Compare two with ==.

pub opaque type SpanContext

SpanEvents

</>

The span’s three events.

pub type SpanEvents(start_metadata, extra_measurements, stop_metadata) {
  SpanEvents(
    start: sinal.Event(
      StartMeasurements,
      StartMetadata(start_metadata),
    ),
    stop: sinal.Event(
      StopMeasurements(extra_measurements),
      StopMetadata(stop_metadata),
    ),
    exception: sinal.Event(
      ExceptionMeasurements,
      ExceptionMetadata(start_metadata),
    ),
  )
}

Constructors

SpanEvents(
  start: sinal.Event(
    StartMeasurements,
    StartMetadata(start_metadata),
  ),
  stop: sinal.Event(
    StopMeasurements(extra_measurements),
    StopMetadata(stop_metadata),
  ),
  exception: sinal.Event(
    ExceptionMeasurements,
    ExceptionMetadata(start_metadata),
  ),
)

StartMeasurements

</>

Measurements of [name.., start].

pub type StartMeasurements {
  StartMeasurements(
    system_time: SystemTime,
    monotonic_time: MonotonicTime,
  )
}

Constructors

StartMeasurements(
  system_time: SystemTime,
  monotonic_time: MonotonicTime,
)

StartMetadata

</>

Metadata of [name.., start].

pub type StartMetadata(metadata) {
  StartMetadata(metadata: metadata, context: SpanContext)
}

Constructors

StartMetadata(metadata: metadata, context: SpanContext)

StopMeasurements

</>

Measurements of [name.., stop]: the timing fields and the span’s own.

pub type StopMeasurements(extra) {
  StopMeasurements(
    duration: NativeDuration,
    monotonic_time: MonotonicTime,
    extra: extra,
  )
}

Constructors

StopMeasurements(
  duration: NativeDuration,
  monotonic_time: MonotonicTime,
  extra: extra,
)

StopMetadata

</>

Metadata of [name.., stop].

pub type StopMetadata(metadata) {
  StopMetadata(metadata: metadata, context: SpanContext)
}

Constructors

StopMetadata(metadata: metadata, context: SpanContext)

SystemTime

opaque </>

A wall-clock timestamp in native time units.

pub opaque type SystemTime

TimeUnit

</>

A unit accepted by the Erlang runtime for native time conversion.

pub type TimeUnit {
  Native
  Nanosecond
  Microsecond
  Millisecond
  Second
}

Constructors

```
Native
```
```
Nanosecond
```
```
Microsecond
```
```
Millisecond
```
```
Second
```

Values

define

</>

pub fn define(
  name: List(String),
  start_metadata start_metadata: fields.Fields(start_metadata),
  stop_measurements stop_measurements: fields.Fields(
    extra_measurements,
  ),
  stop_metadata stop_metadata: fields.Fields(stop_metadata),
) -> Span(start_metadata, extra_measurements, stop_metadata)

Defines a span. name is the prefix of its three events.

Panics when name is empty or breaks the name grammar, or when a codec declares a key the span protocol owns: duration and monotonic_time in the stop measurements, telemetry_span_context, kind, reason and stacktrace in the start metadata, and telemetry_span_context in the stop metadata.

duration_in

</>

pub fn duration_in(
  duration: NativeDuration,
  unit: TimeUnit,
) -> Int

Converts a native span duration to unit.

events

</>

pub fn events(
  span: Span(start_metadata, extra_measurements, stop_metadata),
) -> SpanEvents(start_metadata, extra_measurements, stop_metadata)

Returns the typed start, stop and exception events of span.

monotonic_time_in

</>

pub fn monotonic_time_in(
  time: MonotonicTime,
  unit: TimeUnit,
) -> Int

Converts a native monotonic timestamp to unit.

reason_to_dynamic

</>

pub fn reason_to_dynamic(
  reason: ExceptionReason,
) -> dynamic.Dynamic

The exception reason as a native term, which may be any BEAM value.

run

</>

pub fn run(
  span: Span(start_metadata, extra_measurements, stop_metadata),
  start_metadata: start_metadata,
  work: fn() -> Completion(a, extra_measurements, stop_metadata),
) -> a

Runs work inside the span and returns its result. A raised exception (error, exit or throw) emits the exception event and is re-raised with its class, reason and stacktrace.

stacktrace_to_dynamic

</>

pub fn stacktrace_to_dynamic(
  stacktrace: ExceptionStacktrace,
) -> dynamic.Dynamic

The exception stacktrace as a native term.

system_time_in

</>

pub fn system_time_in(time: SystemTime, unit: TimeUnit) -> Int

Converts a native system timestamp to unit.