Clarity.Telemetry (Clarity v0.5.1)

Telemetry integration for Clarity introspection and worker events.

This module subscribes to Clarity events and emits corresponding telemetry events for monitoring and observability purposes.

Events

• [:clarity, :introspection, :start]
  • Description: Emitted when introspection of the application starts.

This event marks the beginning of the introspection process where Clarity analyzes the application structure and dependencies.

• Measurements: %{monotonic_time: integer(), system_time: integer()}

• Metadata: %{clarity_server: GenServer.server(), telemetry_span_context: reference()}

• [:clarity, :introspection, :progress]

  • Description: Emitted periodically during introspection to report progress.

This event provides updates on the introspection process, including queue sizes and the number of vertices being processed.

• Measurements: %{ duration: integer(), monotonic_time: integer(), system_time: integer(), future_queue: non_neg_integer(), requeue_queue: non_neg_integer(), in_progress: non_neg_integer(), total_vertices: non_neg_integer() }

• Metadata: %{clarity_server: GenServer.server(), telemetry_span_context: reference()}

• [:clarity, :introspection, :stop]

  • Description: Emitted when introspection of the application completes.

This event marks the end of the introspection process.

• Measurements: %{duration: integer(), monotonic_time: integer(), system_time: integer()}

• Metadata: %{clarity_server: GenServer.server(), telemetry_span_context: reference()}

• [:clarity, :worker, :start]

  • Description: Emitted when a worker starts processing a vertex.

This event is emitted at the beginning of vertex processing in a worker process.

• Measurements: %{monotonic_time: integer(), system_time: integer()}

• Metadata: %{ clarity_server: GenServer.server(), worker: GenServer.server(), telemetry_span_context: reference(), introspector: module(), vertex_type: module() }

• [:clarity, :worker, :stop]

  • Description: Emitted when a worker finishes processing a vertex.

This event is emitted after successful vertex processing, including the result type and entry count.

• Measurements: %{ duration: integer(), monotonic_time: integer(), system_time: integer(), result_entry_count: non_neg_integer() | nil }

• Metadata: %{ clarity_server: GenServer.server(), worker: GenServer.server(), telemetry_span_context: reference(), introspector: module(), vertex_type: module(), result_type: :ok | :unmet_dependencies }

• [:clarity, :worker, :exception]

  • Description: Emitted when a worker encounters an exception during vertex processing.

This event is emitted when an error, exit, or throw occurs during vertex processing.

• Measurements: %{duration: integer(), monotonic_time: integer(), system_time: integer()}
• Metadata: %{ clarity_server: GenServer.server(), worker: GenServer.server(), telemetry_span_context: reference(), introspector: module(), vertex_type: module(), kind: :error | :exit | :throw, reason: term(), stacktrace: list() }

Usage with Telemetry Metrics / Phoenix.LiveDashboard

To monitor Clarity events in Phoenix.LiveDashboard, add these metrics to your telemetry module:

defmodule MyApp.Telemetry do
  use Supervisor
  import Telemetry.Metrics

  def start_link(arg) do
    Supervisor.start_link(__MODULE__, arg, name: __MODULE__)
  end

  def init(_arg) do
    children = [
      {:telemetry_poller, measurements: periodic_measurements(), period: 10_000}
    ]

    Supervisor.init(children, strategy: :one_for_one)
  end

  def metrics do
    [
      # Introspection Events
      summary("clarity.introspection.start.system_time",
        unit: {:native, :millisecond}
      ),
      summary("clarity.introspection.stop.duration",
        unit: {:native, :second}
      ),
      summary("clarity.introspection.progress.duration",
        unit: {:native, :millisecond}
      ),
      summary("clarity.introspection.progress.future_queue"),
      summary("clarity.introspection.progress.requeue_queue"),
      summary("clarity.introspection.progress.in_progress"),
      summary("clarity.introspection.progress.total_vertices"),

      # Worker Events
      summary("clarity.worker.start.system_time",
        unit: {:native, :millisecond}
      ),
      distribution("clarity.worker.stop.duration",
        unit: {:native, :millisecond},
        tags: [:vertex_type, :introspector],
        tag_values: &%{&1 | worker: inspect(&1.worker)}
      ),
      counter("clarity.worker.slow.duration",
        unit: {:native, :millisecond},
        tags: [:vertex_type, :introspector],
        tag_values: &%{&1 | worker: inspect(&1.worker)}
      ),
      summary("clarity.worker.exception.duration",
        unit: {:native, :millisecond}
      )
    ]
  end

  defp periodic_measurements do
    []
  end
end