BB.Telemetry (bb v0.15.0)

View Source

Telemetry events emitted by the BB framework.

BB uses :telemetry for both performance monitoring and diagnostics. This module documents all events and provides helper functions for instrumentation.

Performance Events (Spans)

Performance events use :telemetry.span/3 which emits :start, :stop, and :exception events automatically.

Motion Events

  • [:bb, :motion, :solve] - IK solver execution

    • Start measurements: %{system_time: integer}
    • Stop measurements: %{duration: native_time, monotonic_time: integer}
    • Metadata: %{robot: atom, target_link: atom, solver: module}
    • Stop metadata adds: %{iterations: integer, residual: float, reached: boolean}

  • [:bb, :motion, :move_to] - Full move operation (solve + send)

    • Start measurements: %{system_time: integer}
    • Stop measurements: %{duration: native_time}
    • Metadata: %{robot: atom, target_link: atom}

  • [:bb, :motion, :send_positions] - Sending positions to actuators

    • Start measurements: %{system_time: integer}
    • Stop measurements: %{duration: native_time}
    • Metadata: %{robot: atom, joint_count: integer, delivery: atom}

Kinematics Events

  • [:bb, :kinematics, :forward] - Forward kinematics computation
    • Start measurements: %{system_time: integer}
    • Stop measurements: %{duration: native_time}
    • Metadata: %{robot: atom, target_link: atom}

Command Events

  • [:bb, :command, :execute] - Command execution
    • Start measurements: %{system_time: integer}
    • Stop measurements: %{duration: native_time}
    • Metadata: %{robot: atom, command: atom, execution_id: reference}

Diagnostic Events

  • [:bb, :diagnostic] - Component health diagnostics
    • Measurements: %{}
    • Metadata: %BB.Diagnostic{} struct

See BB.Diagnostic for details on diagnostic events.

Subscribing to Events

Use :telemetry.attach/4 or :telemetry.attach_many/4:

:telemetry.attach_many(
  "my-perf-handler",
  [
    [:bb, :motion, :solve, :stop],
    [:bb, :motion, :move_to, :stop]
  ],
  &MyApp.handle_perf_event/4,
  nil
)

Converting Duration

Durations are in native time units. Convert to milliseconds:

duration_ms = System.convert_time_unit(duration, :native, :millisecond)

Or to microseconds for high-precision timing:

duration_us = System.convert_time_unit(duration, :native, :microsecond)

Summary

Functions

emit(event, measurements, metadata)

Emits a telemetry event.

span(event, metadata, fun)

Wraps a function in a telemetry span.

Functions

emit(event, measurements, metadata)

@spec emit([atom()], map(), map()) :: :ok

Emits a telemetry event.

Convenience wrapper around :telemetry.execute/3.

Examples

BB.Telemetry.emit([:bb, :custom, :event], %{count: 1}, %{robot: :my_robot})

span(event, metadata, fun)

@spec span([atom()], map(), (-> {any(), map()})) :: any()

Wraps a function in a telemetry span.

This is a convenience wrapper around :telemetry.span/3 that handles the common pattern of extracting metadata from the result.

Parameters

  • event - The event name prefix (e.g., [:bb, :motion, :solve])
  • metadata - Initial metadata map
  • fun - Function to execute, should return {result, extra_metadata}

Examples

BB.Telemetry.span([:bb, :motion, :solve], %{robot: :my_robot}, fn ->
  result = do_solve()
  {result, %{iterations: 10, residual: 0.001}}
end)