Widget & Metrics API

DRAFT — Internal Developer Use Only

This API reference is for internal development teams.

Overview

What it is: The widget and metrics API provides operational monitoring data for Discovery infrastructure. This includes system resource metrics (CPU, memory, disk), web traffic metrics, and identity collection metrics. Widgets combine these metrics into chart-ready data structures.

How it relates to Dashboard Data: The Dashboard Data API provides identity posture data (accounts, threats, groups). This widget API provides infrastructure monitoring data (CPU, memory, collection health). Both feed into Control's dashboard system — posture data for identity risk widgets, operational data for platform health widgets.

Endpoints

Method	Path	Description	Auth
POST	/internal/v1/logging/metrics	Query raw metric data points	JWT
POST	/internal/v1/logging/metrics/chart	Query metric data formatted for charts	JWT
GET	/internal/v1/logging/dashboard/:did	Get dashboard configuration with widget list	JWT

---

POST /internal/v1/logging/metrics/chart

Query one or more metrics and receive chart-ready data with timestamps, line series, and formatting hints.

Request:

POST /internal/v1/logging/metrics/chart
Authorization: Bearer <token>
Content-Type: application/json

{
  "duration": 86400,
  "interval": 3600,
  "TickFormat": "l",
  "LabelFormat": "lll",
  "metricQuery": [
    {
      "metric": "proc.cpu.usage",
      "labelQuery": [
        { "label": [{ "key": "mod", "value": "collector.ad" }] }
      ],
      "dimension": "nid",
      "aggregate": "max",
      "name": "AD Collector CPU"
    }
  ]
}

WidgetQuery fields

Field	Type	Description
start	int64	Query start (unix seconds). Optional — defaults to now - duration
end	int64	Query end (unix seconds). Optional — defaults to now
duration	int64	Time window in seconds (e.g., 86400 = 24 hours)
interval	int64	Aggregation bucket size in seconds (e.g., 3600 = 1 hour)
TickFormat	string	Tick label format (e.g., "l" for short date)
LabelFormat	string	Data label format (e.g., "lll" for full date-time)
metricQuery	MetricQuery[]	One or more metric queries

MetricQuery fields

Field	Type	Description
metric	string	Metric name (see Available Metrics)
labelQuery	LabelQuery[]	Label filters to narrow the metric
dimension	string	Dimension to group by (see Dimensions)
start	int64	Override query start for this metric
end	int64	Override query end for this metric
duration	int64	Override duration for this metric
interval	int64	Override interval for this metric
aggregate	string	Aggregation function: sum, avg, min, max, lst
combine	string[]	Dimensions to combine (flatten multiple series)
name	string	Display label for this metric series

LabelQuery

Field	Type	Description
label	Label[]	Array of key-value pairs that must all match

Label

Field	Type	Description
key	string	Label key (e.g., "mod", "nid")
value	string	Label value (e.g., "collector.ad", "node-001")

Response (200):

{
  "data": [1707609600, 1707613200, 1707616800],
  "lines": [
    {
      "id": "proc.cpu.usage-node-001",
      "labels": { "mod": "collector.ad", "nid": "node-001" },
      "metric": "proc.cpu.usage",
      "key": "node-001",
      "name": "AD Collector CPU",
      "type": "gauge",
      "unit": "%",
      "metricPoint": {
        "1707609600": 23.5,
        "1707613200": 45.2,
        "1707616800": 31.8
      }
    }
  ],
  "labelFormat": "lll",
  "tickFormat": "l",
  "start": 1707609600,
  "end": 1707696000,
  "interval": 3600,
  "timestamp": 1707696000000
}

Chart response fields

Field	Type	Description
data	int64[]	Array of timestamps (unix seconds) for the x-axis
lines	ChartLine[]	One series per metric dimension value
lines[].id	string	Unique series identifier
lines[].labels	map<string, string>	Label key-value pairs for this series
lines[].metric	string	Metric name
lines[].key	string	Dimension value this series represents
lines[].name	string	Display label
lines[].metricPoint	map<int64, float64>	Timestamp → value mapping
labelFormat	string	Label format hint
tickFormat	string	Tick format hint
start	int64	Actual query start (unix seconds)
end	int64	Actual query end (unix seconds)
interval	int64	Aggregation interval used
timestamp	int64	Response generation time (ms since epoch)

---

POST /internal/v1/logging/metrics

Query raw metric data points without chart formatting.

Request:

POST /internal/v1/logging/metrics
Authorization: Bearer <token>
Content-Type: application/json

{
  "metric": "proc.mem.usage",
  "labelQuery": [
    { "label": [{ "key": "mod", "value": "datastore" }] }
  ],
  "dimension": "nid",
  "duration": 3600,
  "interval": 300,
  "aggregate": "avg"
}

Response (200): Array of metric objects with label sets and data points.

---

GET /internal/v1/logging/dashboard/:did

Get a dashboard configuration including its ordered list of widgets.

Path parameters:

Parameter	Type	Description
did	string	Dashboard identifier (main or identity)

Request:

GET /internal/v1/logging/dashboard/main
Authorization: Bearer <token>

Response (200):

{
  "id": "main",
  "name": "main",
  "includeDefault": true,
  "widget": [
    "Controller CPU",
    "Controller Memory",
    "Registry CPU",
    "Web Services HTTP Request Summary",
    "Web Services Successful Logons"
  ],
  "userWidget": []
}

Dashboard fields

Field	Type	Description
id	string	Dashboard identifier
name	string	Display name
includeDefault	bool	Whether to include default system widgets
widget	string[]	Ordered list of widget names
userWidget	string[]	User-added widgets

---

Available Metrics

System process metrics

Metric	Description	Label filter	Chart type
proc.cpu.usage	CPU usage percentage	mod = module name	LineChart
proc.mem.usage	Memory usage	mod = module name	LineChart

Module labels for proc.cpu.usage and proc.mem.usage:

Label value (mod)	Service
controller	Controller
registry	Registry
collector.ad	Active Directory Collector
collector.azure	Azure Collector
collector.okta	Okta Collector
collector.linux	Linux Collector
collector.windows	Windows Collector
datastore	Datastore
reporting	Reporting
entitystore	Entity Store
commshub	Communications Hub
audit	Audit
apigw	API Gateway (Web Services)
scheduler	Scheduler
idmapper	ID Mapper
dashboard	Dashboard

File system metrics

Metric	Description	Chart type
sys.fs.free	Free disk space	LineChart
sys.fs.size	Total disk capacity	LineChart
sys.fs.usage	Used disk space	LineChart

Web traffic metrics

Metric	Description	Dimension	Chart type
http.request	HTTP request count	l6n (location) or ctn (tenant)	BarChart / PieChart
signin.success	Successful sign-ins	—	BarChart
signin.failure	Failed sign-in attempts	—	BarChart

Identity collection metrics

Metric	Description	Dimension	Chart type
identity.collection.accounts.total	Total discovered accounts	—	Text
identity.collection.accounts	Accounts by collector	cid (collector ID)	BarChart / PieChart
identity.collection.accounts.new	New accounts by collector	cid	BarChart
identity.collection.accounts.stale.account	Stale account count	—	Text
identity.collection.accounts.stale.password	Stale password count	—	Text
identity.collection.scan	Collection scans	cid	BarChart / PieChart
identity.collection.scan.fail	Failed scans	cid	BarChart

---

Dimensions

Dimensions control how metric data is grouped into separate series.

Dimension	Description	Example
nid	Node ID — groups by Discovery collector node	One line per collector node
mod	Module name — groups by service module	One line per service
l6n	Location — groups by geographic location	One slice per location
ctn	Tenant — groups by tenant	One series per tenant
cid	Collector/data source ID	One bar per data source
tid	Tenant ID	Per-tenant metrics
age	Age threshold	For stale password/account bucketing

---

Aggregation Functions

Function	Description
sum	Sum all values in the bucket
avg	Average value in the bucket
min	Minimum value in the bucket
max	Maximum value in the bucket
lst	Last (most recent) value in the bucket

---

Predefined Widgets

Main dashboard widgets

Service resource monitoring:

Widget name	Metric	Label filter	Chart
Controller CPU	proc.cpu.usage	mod=controller	LineChart
Controller Memory	proc.mem.usage	mod=controller	LineChart
Registry CPU	proc.cpu.usage	mod=registry	LineChart
Registry Memory	proc.mem.usage	mod=registry	LineChart
Active Directory Collector CPU	proc.cpu.usage	mod=collector.ad	LineChart
Active Directory Collector Memory	proc.mem.usage	mod=collector.ad	LineChart
Azure Collector CPU	proc.cpu.usage	mod=collector.azure	LineChart
Azure Collector Memory	proc.mem.usage	mod=collector.azure	LineChart
Okta Collector CPU	proc.cpu.usage	mod=collector.okta	LineChart
Okta Collector Memory	proc.mem.usage	mod=collector.okta	LineChart
Linux Collector CPU	proc.cpu.usage	mod=collector.linux	LineChart
Linux Collector Memory	proc.mem.usage	mod=collector.linux	LineChart
Windows Collector CPU	proc.cpu.usage	mod=collector.windows	LineChart
Windows Collector Memory	proc.mem.usage	mod=collector.windows	LineChart
Datastore CPU	proc.cpu.usage	mod=datastore	LineChart
Datastore Memory	proc.mem.usage	mod=datastore	LineChart
Reporting CPU	proc.cpu.usage	mod=reporting	LineChart
Reporting Memory	proc.mem.usage	mod=reporting	LineChart
Entitystore CPU	proc.cpu.usage	mod=entitystore	LineChart
Entitystore Memory	proc.mem.usage	mod=entitystore	LineChart
Communications Hub CPU	proc.cpu.usage	mod=commshub	LineChart
Communications Hub Memory	proc.mem.usage	mod=commshub	LineChart
Audit CPU	proc.cpu.usage	mod=audit	LineChart
Audit Memory	proc.mem.usage	mod=audit	LineChart
Web Services CPU	proc.cpu.usage	mod=apigw	LineChart
Web Services Memory	proc.mem.usage	mod=apigw	LineChart
Scheduler CPU	proc.cpu.usage	mod=scheduler	LineChart
Scheduler Memory	proc.mem.usage	mod=scheduler	LineChart
ID Mapper CPU	proc.cpu.usage	mod=idmapper	LineChart
ID Mapper Memory	proc.mem.usage	mod=idmapper	LineChart
Dashboard CPU	proc.cpu.usage	mod=dashboard	LineChart
Dashboard Memory	proc.mem.usage	mod=dashboard	LineChart

Storage monitoring:

Widget name	Metric	Chart
Data Storage Free Space	sys.fs.free	LineChart
Data Storage Capacity	sys.fs.size	LineChart
Data Storage Usage	sys.fs.usage	LineChart

Web traffic monitoring:

Widget name	Metric	Dimension	Chart
Web Services HTTP Request Summary	http.request	l6n	PieChart
Web Services HTTP Request History	http.request	l6n	BarChart
Tenant HTTP Request Summary	http.request	ctn	PieChart
Tenant HTTP Request History	http.request	ctn	BarChart
Web Services Successful Logons	signin.success	—	BarChart
Web Services Failed Logons	signin.failure	—	BarChart

Identity dashboard widgets

Widget name	Metric	Dimension	Chart
Total Discovered Accounts	identity.collection.accounts.total	—	Text
Total Scans	identity.collection.scan	—	BarChart
Accounts by Platform Summary	identity.collection.accounts	cid	PieChart
Accounts by Platform History	identity.collection.accounts	cid	BarChart
Active Directory Accounts	identity.collection.accounts	cid (AD)	BarChart
New Active Directory Accounts	identity.collection.accounts.new	cid (AD)	BarChart
Azure Accounts	identity.collection.accounts	cid (Azure)	BarChart
Okta Accounts	identity.collection.accounts	cid (Okta)	BarChart
Linux Host Accounts	identity.collection.accounts	cid (Linux)	BarChart
Windows Host Accounts	identity.collection.accounts	cid (Windows)	BarChart
AD Computers Accounts	identity.collection.accounts	cid (AD Computers)	BarChart
New Accounts by Platform	identity.collection.accounts.new	cid	BarChart
Scans by Platform Summary	identity.collection.scan	cid	PieChart
Scans by Platform History	identity.collection.scan	cid	BarChart
Stale Passwords	identity.collection.accounts.stale.password	—	Text
Stale Accounts	identity.collection.accounts.stale.account	—	Text

---

Chart Types

Type	Description	Use case
LineChart	Time series line chart	CPU/memory trends, resource utilization over time
BarChart	Categorical bar chart	Logon counts, accounts by platform, scan history
PieChart	Proportional pie chart	Distribution summaries (HTTP by location, accounts by platform)
Text	Single numeric value display	Total counts (discovered accounts, stale passwords)