Kathikon.Dashboard (Kathikon v0.2.1)

Operations and reporting facade for dashboards, CLIs, and RPC consumers.

Extends Kathikon.Report.queue_summary/1 with dashboard fields (ui_counts, dynamic queues from storage) and delegates job control to Kathikon.*.

See docs/dashboard_spec.md and docs/management_api.md.

Examples

{:ok, queues} = Kathikon.Dashboard.queue_summary()

{:ok, %{jobs: jobs, total: total}} =
  Kathikon.Dashboard.list_jobs(queue: :default, states: [:completed], limit: 50)

{:ok, %{job: job, history: history}} = Kathikon.Dashboard.fetch_job(job_id)

:ok = Kathikon.Dashboard.pause_all()

Summary

Types

fetch_result()

job_map()

state_tab()

Functions

actions_for_state(state)

Returns UI action atoms enabled for a job state.

cancel_job(job_id, reason \\ nil)

cancel_jobs(opts \\ [])

Cancels all cancellable jobs (not :running).

discard_job(job_id, reason \\ nil)

discard_jobs(opts \\ [])

Discards jobs in discardable states.

fetch_job(job_id)

Fetches a job and its history for drill-down views.

list_jobs(opts \\ [])

Lists jobs with optional queue, state, and pagination filters.

pause_all()

Pauses every known queue.

pause_queue(queue)

promote_now()

Sends a scheduler promoter tick (promotes :scheduled → :available).

prune_now()

Triggers a pruner tick on the local node.

purge_jobs(opts \\ [])

Deletes jobs matching filters.

queue_status(queue)

queue_summary(opts \\ [])

Returns queue summary rows for the dashboard table.

rerun_job(job_id, opts \\ [])

rerun_jobs(opts \\ [])

Creates linked reruns for dead (or failed) jobs.

resume_all()

Resumes every known queue.

resume_queue(queue)

retry_job(job_id, opts \\ [])

retry_jobs(opts \\ [])

Retries jobs in retryable, failed, or dead states.

state_tabs()

Returns configured dashboard state tab names in stable UI order.

states_for_tab(tab)

Maps a dashboard tab name to its job states.

Types

fetch_result()

@type fetch_result() :: %{history: [map()], job: job_map()}

job_map()

@type job_map() :: %{attempt: non_neg_integer()}

state_tab()

@type state_tab() ::
  :available
  | :executing
  | :retryable
  | :completed
  | :cancelled
  | :dead
  | :discarded

Functions

actions_for_state(state)

@spec actions_for_state(atom()) :: [atom()]

Returns UI action atoms enabled for a job state.

Actions: :cancel, :retry, :rerun, :discard, :purge.

:running and :waiting_for_children cannot be cancelled (v0.2 limitation).

cancel_job(job_id, reason \\ nil)

@spec cancel_job(String.t(), term()) :: {:ok, Kathikon.Job.t()} | {:error, term()}

cancel_jobs(opts \\ [])

@spec cancel_jobs(keyword()) :: {:ok, map()} | {:error, term()}

Cancels all cancellable jobs (not :running).

Options

:queue — limit to a queue

Returns {:ok, %{succeeded: n, errors: [{id, reason}]}}.

discard_job(job_id, reason \\ nil)

@spec discard_job(String.t(), term()) :: {:ok, Kathikon.Job.t()} | {:error, term()}

discard_jobs(opts \\ [])

@spec discard_jobs(keyword()) :: {:ok, map()} | {:error, term()}

Discards jobs in discardable states.

Options

:queue — limit to a queue
:states — defaults to [:failed, :dead, :retryable]

Returns {:ok, %{succeeded: n, errors: [{id, reason}]}}.

fetch_job(job_id)

@spec fetch_job(String.t()) :: {:ok, fetch_result()} | {:error, term()}

Fetches a job and its history for drill-down views.

The job is a plain map from Kathikon.Job.to_map/1.

list_jobs(opts \\ [])

@spec list_jobs(keyword()) :: {:ok, map()} | {:error, term()}

Lists jobs with optional queue, state, and pagination filters.

Options

:queue — filter by queue atom
:states — list of job states (or a single state atom)
:tab — preset tab (:available, :executing, :retryable, etc.)
:limit — max rows (default 50)
:offset — skip rows (default 0)
:order — :newest (default) or :oldest by inserted_at

Returns {:ok, %{jobs: [map()], total: count, limit: n, offset: n}}.

pause_all()

@spec pause_all() :: :ok

Pauses every known queue.

pause_queue(queue)

@spec pause_queue(atom()) :: :ok

promote_now()

@spec promote_now() :: :ok

Sends a scheduler promoter tick (promotes :scheduled → :available).

prune_now()

@spec prune_now() :: :ok

Triggers a pruner tick on the local node.

purge_jobs(opts \\ [])

@spec purge_jobs(keyword()) :: {:ok, map()} | {:error, term()}

Deletes jobs matching filters.

Options

:queue — limit to a queue
:states — defaults to [:completed, :cancelled, :discarded]
:older_than — DateTime — only delete when terminal timestamp is before this

Returns {:ok, %{purged: count, errors: [{id, reason}]}}.

queue_status(queue)

@spec queue_status(atom()) :: map()

queue_summary(opts \\ [])

@spec queue_summary(keyword()) :: {:ok, [map()]} | {:error, term()}

Returns queue summary rows for the dashboard table.

Each row includes counts, ui_counts, executing (:claimed + :running), failed (:failed + :dead), total, and paused.

Builds on Kathikon.Report.queue_summary/1 and includes queues seen in storage even when not in config :kathikon, :queues.

rerun_job(job_id, opts \\ [])

@spec rerun_job(
  String.t(),
  keyword()
) :: {:ok, Kathikon.Job.t()} | {:error, term()}

rerun_jobs(opts \\ [])

@spec rerun_jobs(keyword()) :: {:ok, map()} | {:error, term()}

Creates linked reruns for dead (or failed) jobs.

Options

:queue — limit to a queue
:states — defaults to [:dead, :failed]

Returns {:ok, %{succeeded: n, errors: [{id, reason}]}}.

resume_all()

@spec resume_all() :: :ok

Resumes every known queue.

resume_queue(queue)

@spec resume_queue(atom()) :: :ok

retry_job(job_id, opts \\ [])

@spec retry_job(
  String.t(),
  keyword()
) :: {:ok, Kathikon.Job.t()} | {:error, term()}

retry_jobs(opts \\ [])

@spec retry_jobs(keyword()) :: {:ok, map()} | {:error, term()}

Retries jobs in retryable, failed, or dead states.

Options

:queue — limit to a queue
:states — defaults to [:retryable, :failed, :dead]

Returns {:ok, %{succeeded: n, errors: [{id, reason}]}}.

state_tabs()

Returns configured dashboard state tab names in stable UI order.

states_for_tab(tab)

@spec states_for_tab(atom()) :: [atom()]

Maps a dashboard tab name to its job states.