Class SuperAdminApi

java.lang.Object

nl.bimbase.bimworks.client.apis.SubApi

nl.bimbase.bimworks.client.apis.SuperAdminApi

public class SuperAdminApi
extends SubApi

Super-admin API calls: server statistics and health, the API latency and network usage stores, reindexing, the email queue, and JFR recordings. Every call requires a client authenticated as a SUPER_ADMIN account (username/password); API tokens and auth tokens are refused by the server.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static interface	SuperAdminApi.EmailListener	Receives the rows the email queue pushes after the snapshot.
static enum	SuperAdminApi.Slice	Time slices accepted by the latency and network usage queries.
static enum	SuperAdminApi.StatisticsRange	Ranges accepted by getStatistics(SuperAdminApi.StatisticsRange).

Constructor Summary

Constructors

Constructor	Description
SuperAdminApi(BimWorksClient bimWorksClient)

Method Summary

Modifier and Type	Method	Description
void	controlReindexing(String action, UUID jobUuid)	continue, continue_without_interrupted, drop_interrupted, pause, cancel_job, requeue_job.
com.fasterxml.jackson.databind.node.ObjectNode	createLoginLink(String username, Duration validity)	Mint a one-time login link for an account (server setting security.login_links_enabled, off by default): opening the returned url in a browser logs it in as that account, once, within the validity.
void	gc()	Trigger a full GC on the server.
com.fasterxml.jackson.databind.node.ObjectNode	getApiLatency(com.fasterxml.jackson.databind.node.ObjectNode parameters)	API latency rows.
com.fasterxml.jackson.databind.node.ObjectNode	getApiLatencyActivity(Instant from, Instant to, SuperAdminApi.Slice slice)	Checkin / reindex / restart intervals in the range (the timeline's activity bands).
com.fasterxml.jackson.databind.node.ObjectNode	getApiLatencyAnomalies(Instant from, Instant to)
com.fasterxml.jackson.databind.node.ObjectNode	getApiLatencyDisk(Instant from, Instant to, SuperAdminApi.Slice slice, boolean includeLive)	This node's disk usage per slice and filesystem (size, least/newest usable space, the storage backends' own bytes), plus the catalog of watched storage locations.
com.fasterxml.jackson.databind.node.ObjectNode	getApiLatencyNode(Instant from, Instant to, SuperAdminApi.Slice slice, boolean includeLive)	The per-interval saturation rows (in-flight, pending, CPU, checkins/reindex running…).
com.fasterxml.jackson.databind.node.ObjectNode	getApiLatencyStatus()	Configuration, counters and store size of the latency tracker.
com.fasterxml.jackson.databind.node.ObjectNode	getEmail(UUID uuid)	The full email record including untruncated bodies.
com.fasterxml.jackson.databind.node.ObjectNode	getJfrStatus()	Every recording the server JVM knows about, including ones started from the command line.
com.fasterxml.jackson.databind.node.ObjectNode	getMemoryInfo()	Heap/non-heap usage plus the allocator's own dumps (fields, dump, stats, kv).
com.fasterxml.jackson.databind.node.ObjectNode	getNetworkUsage(com.fasterxml.jackson.databind.node.ObjectNode parameters)	Network usage rows.
com.fasterxml.jackson.databind.node.ObjectNode	getReindexingStatus()	Snapshot of the reindex queue: counts, pending, running, history, open submissions.
com.fasterxml.jackson.databind.node.ObjectNode	getStatistics(SuperAdminApi.StatisticsRange range)	Activity statistics (same figures as the daily digest email).
com.fasterxml.jackson.databind.node.ObjectNode	getStorage(boolean full)	Storage tiers; full adds the used bytes per backend (slower).
com.fasterxml.jackson.databind.node.ObjectNode	getThreadInfo()	threadCount, peakThreadCount, totalStartedThreadCount.
com.fasterxml.jackson.databind.node.ObjectNode	health()	{database: <connection status>}.
com.fasterxml.jackson.databind.node.ArrayNode	listAccountsAndInvites(boolean showDeleted)	Every account and open invite on the server.
com.fasterxml.jackson.databind.JsonNode	listAllApiTokens()
com.fasterxml.jackson.databind.node.ObjectNode	listApiLatencyEndpoints(Instant from, Instant to)	Every endpoint seen in the range, most called first: {endpoints:[{name, layer, clazz, count, last_seen, state}]}.
com.fasterxml.jackson.databind.node.ArrayNode	listEmails()	The 200 newest rows of the email queue, bodies truncated (see getEmail(UUID)).
AutoCloseable	listenToEmails(SuperAdminApi.EmailListener listener)	Keep the email queue view open: the snapshot goes to the listener as inserted rows (newest first), then every queue transition as it happens.
com.fasterxml.jackson.databind.JsonNode	listModelCheckSets()
com.fasterxml.jackson.databind.node.ArrayNode	listUploads()	The newest uploads (versions and errors) across the server.
com.fasterxml.jackson.databind.node.ObjectNode	startJfrRecording(String name, String settings, long maxSizeBytes, Duration maxAge)	Start a JFR recording on the server JVM (docs/multi-user-load-test-design.md §10.3).
InputStream	stopJfrRecording(long id, boolean keepOnServer)	Stop a recording started with startJfrRecording(String, String, long, Duration) and download it.
com.fasterxml.jackson.databind.node.ObjectNode	submitReindex(com.fasterxml.jackson.databind.node.ObjectNode parameters, long timeOut, TimeUnit timeUnit)	Submit reindex work.

Methods inherited from class SubApi

getBimWorksClient

Modifier and Type	Method	Description
BimWorksClient	getBimWorksClient()

Methods inherited from class Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

SuperAdminApi

public SuperAdminApi(BimWorksClient bimWorksClient)

Method Details

getStatistics

public com.fasterxml.jackson.databind.node.ObjectNode getStatistics(SuperAdminApi.StatisticsRange range)
                                                             throws BimWorksException

Activity statistics (same figures as the daily digest email).

Throws:

BimWorksException

getMemoryInfo

public com.fasterxml.jackson.databind.node.ObjectNode getMemoryInfo()
                                                             throws BimWorksException

Heap/non-heap usage plus the allocator's own dumps (fields, dump, stats, kv).

Throws:

BimWorksException

getThreadInfo

public com.fasterxml.jackson.databind.node.ObjectNode getThreadInfo()
                                                             throws BimWorksException

threadCount, peakThreadCount, totalStartedThreadCount.

Throws:

BimWorksException

health

public com.fasterxml.jackson.databind.node.ObjectNode health()
                                                      throws BimWorksException

{database: <connection status>}.

Throws:

BimWorksException

getStorage

public com.fasterxml.jackson.databind.node.ObjectNode getStorage(boolean full)
                                                          throws BimWorksException

Storage tiers; full adds the used bytes per backend (slower).

Throws:

BimWorksException

listUploads

public com.fasterxml.jackson.databind.node.ArrayNode listUploads()
                                                          throws BimWorksException

The newest uploads (versions and errors) across the server.

Throws:

BimWorksException

getNetworkUsage

public com.fasterxml.jackson.databind.node.ObjectNode getNetworkUsage(com.fasterxml.jackson.databind.node.ObjectNode parameters)
                                                               throws BimWorksException

Network usage rows. Keys (all optional): from, to (ISO-8601), slice (MINUTE|HOUR|DAY), username, token_name, point, detail, node, direction (SENT|RECEIVED), exclude_points (csv), group_by (csv of username,token_name,point,direction,detail,node,time).

Returns:

{rows, totals, slice, from, to, truncated?}

Throws:

BimWorksException

getApiLatency

public com.fasterxml.jackson.databind.node.ObjectNode getApiLatency(com.fasterxml.jackson.databind.node.ObjectNode parameters)
                                                             throws BimWorksException

API latency rows. Keys (all optional): from, to, slice (MINUTE|FIVE_MINUTES|HOUR|DAY|TOTAL), names (csv), classes (csv), outcomes (csv), latency_outcomes (csv), group_by (csv of name,outcome,time), percentiles (csv), bound (UPPER|MID), include_live, with_histogram, with_baseline.

Returns:

{rows, totals, slice, from, to, bound, live, store_available, enabled}

Throws:

BimWorksException

listApiLatencyEndpoints

public com.fasterxml.jackson.databind.node.ObjectNode listApiLatencyEndpoints(Instant from,
 Instant to)
                                                                       throws BimWorksException

Every endpoint seen in the range, most called first: {endpoints:[{name, layer, clazz, count, last_seen, state}]}.

Throws:

BimWorksException

getApiLatencyNode

public com.fasterxml.jackson.databind.node.ObjectNode getApiLatencyNode(Instant from,
 Instant to,
 SuperAdminApi.Slice slice,
 boolean includeLive)
                                                                 throws BimWorksException

The per-interval saturation rows (in-flight, pending, CPU, checkins/reindex running…).

Throws:

BimWorksException

getApiLatencyDisk

public com.fasterxml.jackson.databind.node.ObjectNode getApiLatencyDisk(Instant from,
 Instant to,
 SuperAdminApi.Slice slice,
 boolean includeLive)
                                                                 throws BimWorksException

This node's disk usage per slice and filesystem (size, least/newest usable space, the storage backends' own bytes), plus the catalog of watched storage locations.

Returns:

{rows:[{time, fs, total, usable_min, usable_last, used, storage, backends}], locations, enabled, sample_seconds, live}

Throws:

BimWorksException

getApiLatencyActivity

public com.fasterxml.jackson.databind.node.ObjectNode getApiLatencyActivity(Instant from,
 Instant to,
 SuperAdminApi.Slice slice)
                                                                     throws BimWorksException

Checkin / reindex / restart intervals in the range (the timeline's activity bands).

Throws:

BimWorksException

getApiLatencyAnomalies

public com.fasterxml.jackson.databind.node.ObjectNode getApiLatencyAnomalies(Instant from,
 Instant to)
                                                                      throws BimWorksException

Throws:

BimWorksException

getApiLatencyStatus

public com.fasterxml.jackson.databind.node.ObjectNode getApiLatencyStatus()
                                                                   throws BimWorksException

Configuration, counters and store size of the latency tracker.

Throws:

BimWorksException

getReindexingStatus

public com.fasterxml.jackson.databind.node.ObjectNode getReindexingStatus()
                                                                   throws BimWorksException

Snapshot of the reindex queue: counts, pending, running, history, open submissions.

Throws:

BimWorksException

submitReindex

public com.fasterxml.jackson.databind.node.ObjectNode submitReindex(com.fasterxml.jackson.databind.node.ObjectNode parameters,
 long timeOut,
 TimeUnit timeUnit)
                                                             throws BimWorksException

Submit reindex work. Keys: scope (ALL|SELECTION), version_uuids, types, cutoff_version, tag, delete_after_reindex, dry_run, wait (streams progress and returns when the jobs are done).

Throws:

BimWorksException

controlReindexing

public void controlReindexing(String action,
 UUID jobUuid)
                       throws BimWorksException

continue, continue_without_interrupted, drop_interrupted, pause, cancel_job, requeue_job.

Throws:

BimWorksException

listEmails

public com.fasterxml.jackson.databind.node.ArrayNode listEmails()
                                                         throws BimWorksException

The 200 newest rows of the email queue, bodies truncated (see getEmail(UUID)).

Throws:

BimWorksException

listenToEmails

public AutoCloseable listenToEmails(SuperAdminApi.EmailListener listener)
                             throws BimWorksException

Keep the email queue view open: the snapshot goes to the listener as inserted rows (newest first), then every queue transition as it happens. Close the returned handle to stop listening; the server side ends with the session or the next ListEmails call.

Throws:

BimWorksException

getEmail

public com.fasterxml.jackson.databind.node.ObjectNode getEmail(UUID uuid)
                                                        throws BimWorksException

The full email record including untruncated bodies.

Throws:

BimWorksException

listAccountsAndInvites

public com.fasterxml.jackson.databind.node.ArrayNode listAccountsAndInvites(boolean showDeleted)
                                                                     throws BimWorksException

Every account and open invite on the server.

Throws:

BimWorksException

listAllApiTokens

public com.fasterxml.jackson.databind.JsonNode listAllApiTokens()
                                                         throws BimWorksException

Throws:

BimWorksException

listModelCheckSets

public com.fasterxml.jackson.databind.JsonNode listModelCheckSets()
                                                           throws BimWorksException

Throws:

BimWorksException

gc

public void gc()
        throws BimWorksException

Trigger a full GC on the server.

Throws:

BimWorksException

createLoginLink

public com.fasterxml.jackson.databind.node.ObjectNode createLoginLink(String username,
 Duration validity)
                                                               throws BimWorksException

Mint a one-time login link for an account (server setting security.login_links_enabled, off by default): opening the returned url in a browser logs it in as that account, once, within the validity.

Parameters:

username - the account; null for the caller's own

validity - how long the link stays usable; null for the server's default, capped by the server's maximum

Returns:

{url, username, expires_at, validity_seconds}

Throws:

BimWorksException

startJfrRecording

public com.fasterxml.jackson.databind.node.ObjectNode startJfrRecording(String name,
 String settings,
 long maxSizeBytes,
 Duration maxAge)
                                                                 throws BimWorksException

Start a JFR recording on the server JVM (docs/multi-user-load-test-design.md §10.3).

Parameters:

settings - the JFR configuration name, profile or default

maxSizeBytes - disk cap of the recording, 0 for unlimited

maxAge - how far back the recording keeps events, null for unlimited

Returns:

{id, name, started, settings}

Throws:

BimWorksException

getJfrStatus

public com.fasterxml.jackson.databind.node.ObjectNode getJfrStatus()
                                                            throws BimWorksException

Every recording the server JVM knows about, including ones started from the command line.

Throws:

BimWorksException

stopJfrRecording

public InputStream stopJfrRecording(long id,
 boolean keepOnServer)
                             throws BimWorksException

Stop a recording started with startJfrRecording(String, String, long, Duration) and download it. The caller closes the stream; the server deletes its copy once the stream is consumed unless keepOnServer.

Throws:

BimWorksException