Pbench Server V1 API documentation¶
The documents in this set describe the APIs supported by the Pbench 1.0 Server.
Discovering the Pbench Server API¶
Once you know the hostname of a Pbench Server, you can ask for the API configuration using the endpoints API. This will report the server’s version and a list of all API end points supported by the server.
Pbench Server configuration settings¶
Some aspects of Pbench Server operation can be controlled by a user holding the
ADMIN
role through the
server configuration API, including disabling the Pbench
Server API while the server is undergoing maintenance and setting a banner
message accessible to clients.
Pbench Server resources¶
Datasets¶
The dataset resource encompasses everything the Pbench Server knows about a performance run captured by the Pbench Agent through a “dataset tarball”. This includes the physical files transferred from the agent along with all backend databases maintained by the server.
The API identifies a dataset using the dataset resource ID, which is a hex representing a checksum hash of the dataset tarball. This ID can’t change during the life of the dataset.
When a dataset is deleted, all data maintained by the server associated with that dataset resource ID is deleted, including backend database records, unpacked file artifacts, and the archived tarball. The resource ID becomes invalid subsequently unless a new dataset is created with the same checksum value. (This is highly unlikely, unless the same Pbench Agent tarball is uploaded again.)
Metadata¶
Metadata resources are secondary resources tied to a dataset resource and, for
the user
namespace also to a user resource. Metadata resources are key/value
pairs, as described in metadata.
The lifetime of a metadata resource is bounded by the lifetime of the dataset
resource ID. That is, when a dataset is deleted, all metadata associated with
that dataset is also deleted. If a user is deleted, then all user
namespace
metadata associated with that user (for any dataset) is also deleted.
Although user
namespace metadata can be associated with any dataset to which
the authenticated user has READ access, those metadata keys will become
unreachable if the user’s access to the associated dataset changes to remove
READ access. For example, if a PUBLIC access dataset owned by a different user
is made PRIVATE, or if the user relies on a role or group (see
access model) to READ the dataset and that privilege is
removed. In this case, however, the metadata values remain, and will become
visible again if READ access is restored.
Dataset metadata¶
You can read a more complete specification of Pbench Server metadata at metadata.
When a dataset is first processed, the Pbench Server will populate basic
metadata, including the creation timestamp, the owner of the dataset (the user
associated with the authorization token given to the Pbench Agent
pbench-results-move
command), and the full contents of the dataset’s
metadata.log
file inside the dataset tarball. The Pbench Server will also
calculate a default deletion date for the dataset based on the owner’s
retention policy and the server administrator’s retention policy.
Clients can also set arbitrary metadata in the global
and user
metadata namespaces. The global
namespace can only be modified by the
owner of the dataset, and is visible to anyone with read access to the dataset.
The user
namespace is private to each authenticated user, and even if you
don’t own a dataset you can set your own private user
metadata to help you
categorize that dataset and to find it again.
The primary dataset resource_id
is the computed MD5 of the dataset tarball.
This is generated by the agent, and checked on the server side to ensure data
consistency.
Discovering accessible datasets¶
The datasets accessible by a client are limited by the dataset access controls and the client’s authorization. Any client can read all “public” datasets, but only the owning user can access “private” datasets.
You can determine the datasets you’re allowed to view using the list API. This will return the resource name, the formal resource ID, and selected metadata for each dataset the authenticated user is allowed to read. You can filter the datasets you want listed by date range, owning user, or access policy.
It may sometimes be convenient to know the date range of those datasets in advance, for example to initialize a date picker. You can do this by calling the daterange API to determine the range of dataset creation dates accessible to the authenticated client.
Discovering dataset details¶
To get the details of the dataset’s run configuration, in addition to specified server metadata, you can use the detail API. This returns the resource ID of each selected dataset, along with selectable metadata providing information about the system configuration and tool configuration for the dataset.
Managing a dataset¶
You can control the visibility (access policy) for a dataset that you own by using the publish API. You can make each dataset “public” (readable to everyone) or “private” (readable only to you).
To delete a dataset you own, use delete.
Accessing dataset inventory¶
The Pbench Agent code uploads a dataset to the Pbench Server in the form of a tarball with a carefully designed format. That tarball contains a directory structure which the Pbench Server uses to index and expose details collected by the Pbench Agent during the course of a Pbench benchmark run.
While there are many ways for a client to access the metrics and metadata associated with a dataset, a client can also directly access the dataset tarball inventory.
The contents API exposes the directory hierarchy within the
tarball, from the root directory /
through the leaf files. A client can
discover the entire hierarchical content of the dataset tarball by iterating
through the directories
list of each
directory object.
The inventory API returns the raw byte stream of any regular file within the directory hierarchy, including log files, postprocessed JSON files, and benchmark result text files.