Bash.Telemetry (Bash v0.6.0)

Copy Markdown View Source

Telemetry instrumentation for the Bash interpreter.

This module emits telemetry events for script execution, allowing you to monitor performance, track usage, and integrate with observability tools.

Available Events

All events follow the span pattern with :start, :stop, and :exception suffixes.

Session Execution

  • [:bash, :session, :run, :start] - Emitted when Bash.run/3 begins execution

    • Measurement: %{system_time: integer}
    • Metadata: %{session: pid}

  • [:bash, :session, :run, :stop] - Emitted when Bash.run/3 completes

    • Measurement: %{duration: native_time}

    • Metadata: %{session: pid, status: :ok | :error | :exit | :exec, exit_code: integer | nil}

  • [:bash, :session, :run, :exception] - Emitted when Bash.run/3 raises an exception

    • Measurement: %{duration: native_time}

    • Metadata: %{session: pid, kind: :error | :exit | :throw, reason: term, stacktrace: list}

Command Execution

  • [:bash, :command, :start] - Emitted before a command executes

    • Measurement: %{system_time: integer}
    • Metadata: %{command: String.t, args: list(String.t)}

  • [:bash, :command, :stop] - Emitted after a command completes

    • Measurement: %{duration: native_time}

    • Metadata: %{command: String.t, args: list(String.t), exit_code: integer | nil}

  • [:bash, :command, :exception] - Emitted when a command raises an exception

    • Measurement: %{duration: native_time}
    • Metadata: %{command: String.t, args: list(String.t), kind: atom, reason: term, stacktrace: list}

For Loop Execution

  • [:bash, :for_loop, :start] - Emitted before a for loop begins

    • Measurement: %{system_time: integer}
    • Metadata: %{variable: String.t, item_count: integer}

  • [:bash, :for_loop, :stop] - Emitted after a for loop completes

    • Measurement: %{duration: native_time}

    • Metadata: %{variable: String.t, item_count: integer, iteration_count: integer, exit_code: integer | nil}

  • [:bash, :for_loop, :exception] - Emitted when a for loop raises an exception

    • Measurement: %{duration: native_time}
    • Metadata: %{variable: String.t, item_count: integer, kind: atom, reason: term, stacktrace: list}

While/Until Loop Execution

  • [:bash, :while_loop, :start] - Emitted before a while/until loop begins

    • Measurement: %{system_time: integer}
    • Metadata: %{until: boolean}

  • [:bash, :while_loop, :stop] - Emitted after a while/until loop completes

    • Measurement: %{duration: native_time}

    • Metadata: %{until: boolean, iteration_count: integer, exit_code: integer | nil}

  • [:bash, :while_loop, :exception] - Emitted when a while/until loop raises an exception

    • Measurement: %{duration: native_time}
    • Metadata: %{until: boolean, kind: atom, reason: term, stacktrace: list}

Usage Example

Attach handlers to receive telemetry events:

:telemetry.attach_many(
  "bash-telemetry-handler",
  [
    [:bash, :session, :run, :start],
    [:bash, :session, :run, :stop],
    [:bash, :session, :run, :exception],
    [:bash, :command, :start],
    [:bash, :command, :stop],
    [:bash, :command, :exception],
    [:bash, :for_loop, :start],
    [:bash, :for_loop, :stop],
    [:bash, :for_loop, :exception],
    [:bash, :while_loop, :start],
    [:bash, :while_loop, :stop],
    [:bash, :while_loop, :exception]
  ],
  &MyApp.TelemetryHandler.handle_event/4,
  nil
)

Note on Output

Output (stdout/stderr) is intentionally NOT included in telemetry metadata to avoid memory issues with large outputs. Use output collectors or sinks if you need to capture command output.