Context module for managing stats groups.
A group is created/updated/deleted here, but reading/writing its
actual metric data always goes through PhoenixKitStats.Metrics and
PhoenixKitStats.DatabaseManager — this module only ever touches
group metadata in Postgres, plus tells DatabaseManager when to
open/close a group's Barograph database as a side effect of a status
change.
Activity logging
Every mutating function accepts opts \ []. When actor_uuid: is
present in opts, the mutation is logged via PhoenixKit.Activity.log/1
under the "stats" module key. Logging failures never crash the
primary operation.
Usage from IEx
alias PhoenixKitStats.Groups
{:ok, group} = Groups.create_group(%{name: "Server 1", key: "server1", port: Groups.next_available_port()})
Groups.pause_group(group)
Groups.resume_group(group)
Groups.delete_group(group)Summary
Functions
Returns an Ecto.Changeset for tracking group changes.
Creates a stats group. Required: :name, :key, :port. Optional:
:template, :description, :settings.
Permanently deletes a group: closes its Barograph DB, deletes the
underlying .bg file, and removes the metadata row. Irreversible —
callers must confirm with the user first (the admin UI does this via
a data-confirm prompt).
Fetches a group by UUID. Returns nil if not found.
Fetches a group by its slug key. Returns nil if not found.
Lists all stats groups, ordered by name.
Returns the lowest port in the configured :port_range
(Application.get_env(:phoenix_kit_stats, :port_range, 9100..9200))
not already used by an existing group. nil if the range is
exhausted. Used to prefill the "new group" form — the admin can
override it.
Pauses a group: keeps its metadata and stored data, closes the Barograph DB, frees its port.
The configured port range groups may allocate collector ports from.
Resumes a paused group: reopens its Barograph DB + Graphite listener.
Updates a stats group. Always closes any currently-open Barograph
listener for it first, then reopens if the (possibly new) status is
"active" — this correctly handles port/template changes and status
changes made through this function rather than pause_group/2 /
resume_group/2.
Types
@type opts() :: keyword()
Functions
@spec change_group(PhoenixKitStats.Schemas.Group.t(), map()) :: Ecto.Changeset.t()
Returns an Ecto.Changeset for tracking group changes.
@spec create_group(map(), opts()) :: {:ok, PhoenixKitStats.Schemas.Group.t()} | {:error, Ecto.Changeset.t()}
Creates a stats group. Required: :name, :key, :port. Optional:
:template, :description, :settings.
If created with status: "active" (the default), opens the group's
Barograph database + Graphite listener immediately via
PhoenixKitStats.DatabaseManager — no app restart needed. A listener
start failure (e.g. the port is unexpectedly taken) is logged but does
not fail the create — the metadata row is the source of truth, and an
admin can fix the port and the group will pick it up on the next
update/resume.
@spec delete_group(PhoenixKitStats.Schemas.Group.t(), opts()) :: {:ok, PhoenixKitStats.Schemas.Group.t()} | {:error, Ecto.Changeset.t()}
Permanently deletes a group: closes its Barograph DB, deletes the
underlying .bg file, and removes the metadata row. Irreversible —
callers must confirm with the user first (the admin UI does this via
a data-confirm prompt).
@spec get_group(String.t()) :: PhoenixKitStats.Schemas.Group.t() | nil
Fetches a group by UUID. Returns nil if not found.
@spec get_group_by_key(String.t()) :: PhoenixKitStats.Schemas.Group.t() | nil
Fetches a group by its slug key. Returns nil if not found.
@spec list_groups(keyword()) :: [PhoenixKitStats.Schemas.Group.t()]
Lists all stats groups, ordered by name.
Options
:status— filter by status ("active"or"paused").
@spec next_available_port() :: pos_integer() | nil
Returns the lowest port in the configured :port_range
(Application.get_env(:phoenix_kit_stats, :port_range, 9100..9200))
not already used by an existing group. nil if the range is
exhausted. Used to prefill the "new group" form — the admin can
override it.
@spec pause_group(PhoenixKitStats.Schemas.Group.t(), opts()) :: {:ok, PhoenixKitStats.Schemas.Group.t()} | {:error, Ecto.Changeset.t()}
Pauses a group: keeps its metadata and stored data, closes the Barograph DB, frees its port.
@spec port_range() :: Range.t()
The configured port range groups may allocate collector ports from.
@spec resume_group(PhoenixKitStats.Schemas.Group.t(), opts()) :: {:ok, PhoenixKitStats.Schemas.Group.t()} | {:error, Ecto.Changeset.t()}
Resumes a paused group: reopens its Barograph DB + Graphite listener.
@spec update_group(PhoenixKitStats.Schemas.Group.t(), map(), opts()) :: {:ok, PhoenixKitStats.Schemas.Group.t()} | {:error, Ecto.Changeset.t()}
Updates a stats group. Always closes any currently-open Barograph
listener for it first, then reopens if the (possibly new) status is
"active" — this correctly handles port/template changes and status
changes made through this function rather than pause_group/2 /
resume_group/2.