hailer.metrics

Read Hailer's usage metrics. Metrics are time-series counters stored in a Prometheus-compatible metrics store and queried through a PromQL builder — you request one or more metric names and get back current values and/or a time series, optionally aggregated, grouped, and filtered by label.

Method	Host op	Returns
list(options?)	metrics.list	Promise<string[] | MetricDefinition[]>
get(metricTypes, options?)	metrics.get	Promise<MetricData>

What metrics exist

Metric names are namespaced by area, e.g. hailer.activity.create, hailer.message.create. Access is permission-gated:

• Available to every user — hailer.activity.create and hailer.message.create.
• Admins — all metrics, including every hailer.* metric and system/runtime metrics (process CPU/memory, Node.js, RPC, files, and so on).

Call list() to discover exactly which names the current user may read. Requesting a metric the user isn't allowed to read fails with a permission error naming the denied metrics.

list(options?)

const names = await hailer.metrics.list();

Returns the metric names the current user is allowed to read.

get(metricTypes, options?)

Fetch data for one or more metrics. A single string is accepted and coerced to an array. Between 1 and 50 metrics may be requested at once; results come back in the same order as requested.

// Current value of one metric in a workspace
const data = await hailer.metrics.get('hailer.activity.create', { workspaceId });

// Time series over the last 24h, hourly buckets
const series = await hailer.metrics.get('hailer.activity.create', {
  workspaceId,
  timeRange: { start: Date.now() - 86_400_000, end: Date.now() },
  interval: '1h',
  aggregation: 'sum',
});

// Top 10 users by activity creation
const top = await hailer.metrics.get('hailer.activity.create', {
  workspaceId,
  aggregation: 'sum',
  groupBy: ['userId'],
  topk: 10,
});

Options

Option	Type	Meaning
workspaceId	string	Scope the query to a workspace.
userId	string	Scope the query to a single user.
timeRange	{ start: number; end: number }	Return a time series over this range (epoch ms).
interval	'1m' | '5m' | '15m' | '30m' | '1h' | '5h'	Bucket size for the time series. Default 1h.
aggregation	'sum' | 'avg' | 'max' | 'min' | 'count' | 'rate' | 'increase'	Aggregation to apply.
groupBy	string[]	Break results down by up to 3 labels.
topk	number	Keep only the top N series (1–100).
labelFilters	Record<string, string>	Keep only series matching these label values.

The labels usable in groupBy and labelFilters are: userId, userRole, workspaceId, teamId, processId, workflowId, discussionId, activityId, signal, type.

Result

get resolves to an array with one entry per requested metric, in request order. Each entry has:

Field	Type	Meaning
value	number	Current scalar value (when not grouped into a series).
labels	object	Labels attached to the value.
timeSeries	{ labels, values: { timestamp, value }[] }[]	One series per group, each a list of { timestamp, value }.
error	boolean	Set if this metric failed.
errorMessage	string	Failure detail.

Metric reads are counted toward workspace usage.

hailer.metrics.admin

Lookups for building admin metric filters (resolving ids to names).

Method	Host op	Returns
workspacesList(options)	metrics.workspaceSearch	Promise<WorkspaceMetricsListResult>
usersList(options)	metrics.userList	Promise<UserMetricsListResult>

// Resolve workspaces by id, or search by name (min 3 chars)
await hailer.metrics.admin.workspacesList({ workspaceIds: ['id1', 'id2'] });
await hailer.metrics.admin.workspacesList({ name: 'Sales' });

// Resolve users by id
await hailer.metrics.admin.usersList({ userIds: ['id1', 'id2'] });

workspacesList returns { _id, name }[]; usersList returns { _id, name?, email }[]. See the metrics types in the Types reference.