Module: Browserctl::Tracing

Defined in:
lib/browserctl/tracing.rb

Overview

Pluggable tracing seam shaped like OpenTelemetry’s span API, without taking an OpenTelemetry dependency.

Backend contract

A tracing backend must respond to two methods:

start_span(name, attributes:) -> span
  - `name` is a String (e.g. "command.navigate").
  - `attributes` is a Hash of additional span tags.
  - Returns an opaque span object that will be passed back to
    `end_span`. May return `nil`; `end_span` must tolerate that.

end_span(span, status:, attributes: {})
  - `span` is whatever `start_span` returned.
  - `status` is `:ok` or `:error`.
  - `attributes` carries any tags computed at close time
    (notably `duration_ms`). Optional.

The default backend is ‘NoopBackend` — it does nothing. A custom backend is wired in via `Browserctl::Tracing.backend = …`. The contract is part of the Extension zone — see `docs/reference/api-stability.md`.

Defined Under Namespace

Classes: NoopBackend

Class Method Summary collapse

Class Method Details

.backend ⇒ Object 



44
45
46
 
# File 'lib/browserctl/tracing.rb', line 44

def backend
  @backend_mutex.synchronize { @backend }
end

.backend=(value) ⇒ Object 



48
49
50
 
# File 'lib/browserctl/tracing.rb', line 48

def backend=(value)
  @backend_mutex.synchronize { @backend = value || NoopBackend.new }
end

.in_span(name, attributes: {}) ⇒ Object

Wraps a block in a span. Computes ‘duration_ms` and routes exceptions to `end_span(span, status: :error)`.



54
55
56
57
58
59
60
61
62
63
64
65
66
 
# File 'lib/browserctl/tracing.rb', line 54

def in_span(name, attributes: {})
  bk = backend
  span = bk.start_span(name, attributes: attributes)
  start = monotonic_ms
  begin
    result = yield
  rescue StandardError
    bk.end_span(span, status: :error, attributes: { duration_ms: monotonic_ms - start })
    raise
  end
  bk.end_span(span, status: :ok, attributes: { duration_ms: monotonic_ms - start })
  result
end