API Documentation

pyauditor is a client for interacting with an Auditor instance via Python.

class pyauditor.AuditorClientBuilder

The AuditorClientBuilder class is used to build an instance of AuditorClient.

Examples

Using the address and port of the Auditor instance:

# Create an instance of the builder
builder = AuditorClientBuilder()

# Configure the builder
builder = builder.address("localhost", 8000).timeout(20)

# Build the client
client = builder.build()

Using an connection string:

client = AuditorClientBuilder().connection_string("http://localhost:8000").build()

address(address: str, port: int)

Set the address of the Auditor server

Parameters:

address (str) – Host name / IP address of the Auditor instance
port (int) – Port of the Auditor instance

build(): Build an AuditorClient from AuditorClientBuilder

build_blocking(): Build an AuditorClientBlocking from AuditorClientBuilder

build_queued(): Build a QueuedAuditorClient from AuditorClientBuilder

connection_string(connection_string: str)

Set a connection string of the form http://<auditor_address>:<auditor_port>

Parameters:: connection_string (str) – Connection string

database_path(path)

Set the file path for the persistent storage sqlite db. This setting is only relevant to the QueuedAuditorClient.

Parameters:: path (str) – Path to the database (SQLite) file

send_interval(interval)

Set an interval in seconds for periodic updates to AUDITOR. This setting is only relevant to the QueuedAuditorClient.

Parameters:: interval (int) – Interval in sections

timeout(timeout: int)

Set a timeout in seconds for HTTP requests

Parameters:: timeout (int) – Timeout in sections

with_tls(ca_cert_path, client_cert_path, client_key_path)

Set the ca_certificate path, client_certificate path and the client key path

Parameters:

ca_cert_path – Path to the ca_certificate
client_cert_path – Path to the client_certificate
client_key_path – Path to the client_key_path

class pyauditor.AuditorClient

The AuditorClient handles the interaction with the Auditor instances and allows one to add records to the database, update records in the database and retrieve the records from the database.

add(record: Record): Push a record to the Auditor instance

advanced_query(query_string: string)

Get records from the database depending on the query parameters

Parameters:: query_string (string) – query_string constructed with QueryBuilder using .build() method

Example

value1 = Value.set_datetime(start_time)
value2 = Value.set_datetime(stop_time)
operator1 = Operator().gt(value1)
operator2 = Operator().gt(value2)
query_string = QueryBuilder().with_start_time(operator1).with_stop_time(operator2).build()
records = await client.advanced_query(query_string)

bulk_insert(records): add(record: Record) Push a list of records to the Auditor instance

get(): Gets all records from the Auditors database

get_single_record(record_id)

get_one_record(record_id: string) Get one record using record_id

Parameters:: record_id (string) – record_id

Example

record: &str = "record-1"
record = await client.get_one_record(record)

get_started_since(timestamp: datetime.datetime)

Get all records in the database with a started timestamp after timestamp.

Warning

The timestamp MUST be in UTC!

Parameters:: timestamp (datetime.datetime) – Timestamp in UTC

Example

# If the date/time is already in UTC:
start_since = datetime.datetime(2022, 8, 8, 11, 30, 0, 0, tzinfo=datetime.timezone.utc)

# If it is in local time:
from tzlocal import get_localzone
local_tz = get_localzone()
start_since = datetime.datetime(2022, 8, 8, 11, 30, 0, 0, tzinfo=local_tz).astimezone(datetime.timezone.utc)

records = client.get_stopped_since(start_since)

get_stopped_since(timestamp: datetime.datetime)

Get all records in the database with a stopped timestamp after timestamp.

Warning

The timestamp MUST be in UTC!

Parameters:: timestamp (datetime.datetime) – Timestamp in UTC

Example

# If the date/time is already in UTC:
stop_since = datetime.datetime(2022, 8, 8, 11, 30, 0, 0, tzinfo=datetime.timezone.utc)

# If it is in local time:
from tzlocal import get_localzone
local_tz = get_localzone()
stop_since = datetime.datetime(2022, 8, 8, 11, 30, 0, 0, tzinfo=local_tz).astimezone(datetime.timezone.utc)

records = client.get_stopped_since(stop_since)

health_check(): Returns true if the Auditor instance is healthy, false otherwise

update(record: Record): Update an existing record in the Auditor instance

class pyauditor.Value

Value is used to specify the type of the value which is used in the query

static set_count(count)

Sets the count value Sets the runtime value to query

Parameters:: count (int) – int

Example

count_value = 100000
value = Value.set_count(count_value)

static set_datetime(datetime)

Sets datetime for start_time and stop_time queries

Warning

The timestamp MUST be in UTC!

Parameters:: timestamp (datetime.datetime) – Timestamp in UTC

Example

# If the date/time is already in UTC:
start_time = datetime.datetime(2022, 8, 8, 11, 30, 0, 0, tzinfo=datetime.timezone.utc)

# If it is in local time:
from tzlocal import get_localzone
local_tz = get_localzone()
start_time = datetime.datetime(2022, 8, 8, 11, 30, 0, 0, tzinfo=local_tz).astimezone(datetime.timezone.utc)

value = Value.set_datetime(start_time)

static set_runtime(runtime)

Sets the runtime value to query

Parameters:: runtime (int) – int

Example

runtime_value = 100000
value = Value.set_runtime(runtime_value)

class pyauditor.Operator

The Operator is used to specify the operators on the query parameters

equals(value)

Sets equal to (equals) operator value

Parameters:: value (Value object) – The value for greater than operator

Example

count_value = 100000
value = Value.set_count(count_value)
operator = Operator().equals(value)

gt(value)

Sets the greater than (gt) operator Value

Parameters:: value (Value object) – The value for greater than operator

Example

count_value = 100000
value = Value.set_count(count_value)
operator = Operator().gt(value)

gte(value)

Sets the greater than or equal to (gte) operator value

Parameters:: value (Value object) – The value for greater than or equal to operator

Example

count_value = 100000
value = Value.set_count(count_value)
operator = Operator().gte(value)

lt(value)

Sets the lesser than (lt) operator value

Parameters:: value (Value object) – The value for lesser than operator

Example

count_value = 100000
value = Value.set_count(count_value)
operator = Operator().lt(value)

lte(value)

Sets lesser than or equal to (lte) operator value

Parameters:: value (Value object) – The value for greater than operator

Example

count_value = 100000
value = Value.set_count(count_value)
operator = Operator().lte(value)

class pyauditor.QueryBuilder

The QueryBuilder is used to construct QueryParameters using the builder pattern.

build(): Builds the query string for the given query parameters

limit(number)

Limits the query records

Parameters:: number (int) – number specifying the number of records that needs to be returned

Example

records = QueryBuilder().limit(500).build()

sort_by(sort_by)

SortBy provides options on sorting the query records

Parameters:: sort_by – SortBy object instantiatied with the sorting order(asc or desc) and column

name :type sort_by: SortBy object

Example

sort_by = SortBy().ascending("start_time")
records = QueryBuilder().sort_by(sort_by).build()

with_component_query(component)

Sets the component query in the query parameters

Parameters:: component (ComponentQuery object) – ComponentQuery object instantiated with component name and amount

Example

value = Value.count(4)
component_operator = Operator().equals(value)
component_query = ComponentQuery().component_operator("cpu", component_operator)
records = QueryBuilder().with_component_query(component_query).build()

with_meta_query(meta)

Sets the meta query in the query parameters

:param meta- meta contains the meta key and value :type meta- MetaQuery object

Example

meta_operator = MetaOperator().contains("group_1")
meta_query = MetaQuery().meta_operator("group_id", meta_operator)
query_string = QueryBuilder().with_meta_query(meta_query).build()

with_record_id(record_id)

Sets the exact record_id to retrieve

Parameters:: record_id (string) – Exact record_id to be retrieved

Example

record_id = "r101"
query_string = QueryBuilder().with_record_id(record_id).build()

with_runtime(operator)

Sets the runtime in the query parameters

Parameters:: operator (Operator object) – Operator object containing runtime value

Example

start_time = datetime.datetime(
 2022, 8, 8, 11, 30, 0, 0, tzinfo=datetime.timezone.utc
)

value = Value.set_runtime(100000)
operator = Operator().gt(value)
query_string = QueryBuilder().with_runtime(operator).build()

with_start_time(operator)

Sets the start time in the query parameters

Parameters:: operator (Operator object) – Operator object containing DateTime<Utc>

Example

start_time = datetime.datetime(
 2022, 8, 8, 11, 30, 0, 0, tzinfo=datetime.timezone.utc
)

value = Value.set_datetime(start_time)
operator = Operator().gt(value)
query_string = QueryBuilder().with_start_time(operator).build()

with_stop_time(operator)

Sets the stop time in the query parameters

Parameters:: operator (Operator object) – Operator object containing DateTime<Utc>

Example

stop_time = datetime.datetime(
 2022, 8, 8, 11, 30, 0, 0, tzinfo=datetime.timezone.utc
)

value = Value.set_datetime(stop_time)
operator = Operator().gt(value)
query_string = QueryBuilder().with_stop_time(operator).build()

class pyauditor.MetaQuery

meta_operator(query_id, meta_operator)

Sets meta operator Value

Parameters:

query_id (string) – Metadata key
meta_operator (MetaOperator object) – Metadata value which is set using MetaOperator object

Example

meta_operator = MetaOperator().contains("group_1")
operator = MetaQuery().meta_operator("group_id", meta_operator)

class pyauditor.MetaOperator

The MetaOperator struct represents operators for metadata queries, specifying conditions for filtering

contains(c)

Sets the meta value using contains operator. This checks if the value exists for the corresponding metadata key

Parameters:

query_id (string) – Metadata key
c (string) – Metadata value to be checked if it exists

Example

meta_operator = MetaOperator().contains("group_1")
meta_query = MetaQuery().meta_operator("group_id", meta_operator)

does_not_contain(dnc)

Sets the meta value using does not contain operator. This checks if the value does not exist for the corresponding metadata key

Parameters:

query_id (string) – Metadata key
c (string) – Metadata value to be checked if it does not exist

Example

operator = MetaOperator().does_not_contain("group_1")

class pyauditor.ComponentQuery

The ComponentQuery struct represents a set of component queries associated with specific query IDs. It is used to filter records based on component-related conditions

component_operator(query_id, operator)

Adds a new component operator to the ComponentQuery instance for a specific query ID.

Parameters:

query_id (string) – Component name
operator (int) – component amount

Example

value = Value.set_count(10)
component_operator = Operator().equals(value)
component_query = ComponentQuery().component_operator("cpu", component_operator)

class pyauditor.SortBy

SortBy provides options on sorting the query records

ascending(column)

Specify the column by which the query records must be sorted in ascending order

Parameters:: column (string) – Name of the column by which the records must be sorted. One of four values (start_time, stop_time, runtime, record_id).

Example

sort_by = SortBy().ascending("start_time")

descending(column)

Specify the column by which the query records must be sorted in descending order

Parameters:: column (string) – Name of the column by which the records must be sorted. One of three values (start_time, stop_time, runtime, record_id).

Example

sort_by = SortBy().descending("start_time")

class pyauditor.AuditorClientBlocking

The AuditorClientBlocking handles the interaction with the Auditor instances and allows one to add records to the database, update records in the database and retrieve the records from the database. In contrast to AuditorClient, no async runtime is needed here.

add(record: Record): Push a record to the Auditor instance

advanced_query(query_string: string)

Get records from the database depending on the query parameters

Parameters:: query_string (string) – query_string constructed with QueryBuilder using .build() method

Example

value1 = Value.set_datetime(start_time)
value2 = Value.set_datetime(stop_time)
operator1 = Operator().gt(value1)
operator2 = Operator().gt(value2)
query_string = QueryBuilder().with_start_time(operator1).with_stop_time(operator2).build()
records = client.advanced_query(query_string)

bulk_insert(records): add(record: Record) Push a list of records to the Auditor instance

get(): Gets all records from the Auditors database

get_single_record(record_id)

get_started_since(timestamp: datetime.datetime)

Get all records in the database with a started timestamp after timestamp.

Warning

The timestamp MUST be in UTC!

Parameters:: timestamp (datetime.datetime) – Timestamp in UTC

Example

# If the date/time is already in UTC:
start_since = datetime.datetime(2022, 8, 8, 11, 30, 0, 0, tzinfo=datetime.timezone.utc)

# If it is in local time:
from tzlocal import get_localzone
local_tz = get_localzone()
start_since = datetime.datetime(2022, 8, 8, 11, 30, 0, 0, tzinfo=local_tz).astimezone(datetime.timezone.utc)

records = client.get_stopped_since(start_since)

get_stopped_since(timestamp: datetime.datetime)

Get all records in the database with a stopped timestamp after timestamp.

Warning

The timestamp MUST be in UTC!

Parameters:: timestamp (datetime.datetime) – Timestamp in UTC

Example

# If the date/time is already in UTC:
stop_since = datetime.datetime(2022, 8, 8, 11, 30, 0, 0, tzinfo=datetime.timezone.utc)

# If it is in local time:
from tzlocal import get_localzone
local_tz = get_localzone()
stop_since = datetime.datetime(2022, 8, 8, 11, 30, 0, 0, tzinfo=local_tz).astimezone(datetime.timezone.utc)

records = client.get_stopped_since(stop_since)

health_check(): Returns true if the Auditor instance is healthy, false otherwise

update(record: Record): Update an existing record in the Auditor instance

class pyauditor.QueuedAuditorClient

The QueuedAuditorClient handles the interaction with the Auditor instances. All data to be sent is transparently saved in a persistent local database.

When records are sent to Auditor, this client will transparently buffer them in a (persistent) local database. A background task will then periodically send records from the local database to Auditor, deleting them from the local database only after they have been successfully send to Auditor.

Note

There are some quirks that need to be observed when using this client:

Uses an in-memory database by default. It is strongly recommended to provide a path. See AuditorClientBuilder.database_path().
Since sending and updating records is delayed, there is no guarantee that a record can be retrieved from Auditor right after it has been “sent” by this client.
The background task of this client should be stopped by invoking QueuedAuditorClient.stop() before the client is dropped.

add(record: Record): Push a record to the Auditor instance

advanced_query(query_string: string)

Get records from the database depending on the query parameters

Parameters:: query_string (string) – query_string constructed with QueryBuilder using .build() method

Example

value1 = Value.set_datetime(start_time)
value2 = Value.set_datetime(stop_time)
operator1 = Operator().gt(value1)
operator2 = Operator().gt(value2)
query_string = QueryBuilder().with_start_time(operator1).with_stop_time(operator2).build()
records = await client.advanced_query(query_string)

bulk_insert(records): add(record: Record) Push a list of records to the Auditor instance

get(): Gets all records from the Auditors database

get_single_record(record_id)

get_one_record(record_id: string) Get one record using record_id

Parameters:: record_id (string) – record_id

Example

record: &str = "record-1"
record = await client.get_one_record(record)

get_started_since(timestamp: datetime.datetime)

Get all records in the database with a started timestamp after timestamp.

Warning

The timestamp MUST be in UTC!

Parameters:: timestamp (datetime.datetime) – Timestamp in UTC

Example

# If the date/time is already in UTC:
start_since = datetime.datetime(2022, 8, 8, 11, 30, 0, 0, tzinfo=datetime.timezone.utc)

# If it is in local time:
from tzlocal import get_localzone
local_tz = get_localzone()
start_since = datetime.datetime(2022, 8, 8, 11, 30, 0, 0, tzinfo=local_tz).astimezone(datetime.timezone.utc)

records = client.get_stopped_since(start_since)

get_stopped_since(timestamp: datetime.datetime)

Get all records in the database with a stopped timestamp after timestamp.

Warning

The timestamp MUST be in UTC!

Parameters:: timestamp (datetime.datetime) – Timestamp in UTC

Example

# If the date/time is already in UTC:
stop_since = datetime.datetime(2022, 8, 8, 11, 30, 0, 0, tzinfo=datetime.timezone.utc)

# If it is in local time:
from tzlocal import get_localzone
local_tz = get_localzone()
stop_since = datetime.datetime(2022, 8, 8, 11, 30, 0, 0, tzinfo=local_tz).astimezone(datetime.timezone.utc)

records = client.get_stopped_since(stop_since)

health_check(): Returns true if the Auditor instance is healthy, false otherwise

stop(): Stops the background sync task

update(record: Record): Update an existing record in the Auditor instance

class pyauditor.Record(record_id: str, start_time: datetime.datetime)

A Record represents a single accountable unit. It consists of meta information such as

record_id: Uniquely identifies the record
start_time: Timestamp from when the resource was available.

Note

All strings must not include the characters. /, (, ), ", <, >, \, {, }.

Warning

All timestamps must be in UTC! Make sure to create time stamps in UTC or translate them to UTC before using them in a Record.

Records can be sent to and received from Auditor.

When created using the constructor for sending to Auditor, the record is already valid in terms of all checks that Auditor performs when receiving it.

The optional stop_time can be added via the with_stop_time method.

Components are added via with_component. Call this method multiple times for adding multiple components.

Meta information is added via with_meta.

The individual fields of the record can be accessed using the getter methods described below.

Parameters:

record_id (str) – Unique record identifier
start_time – Timestamp from which the resource became available

components

Returns the components

Returns None if no components are attached, otherwise returns a list of Component s.

meta

Returns the meta object

Returns None if no meta is available, otherwise returns a meta object.

record_id: Returns the record_id

runtime: Returns the runtime of a record.

start_time: Returns the start_time

stop_time: Returns the stop_time

to_json(): Output content of Record as JSON-encoded string

with_component(component: Component)

Adds a component to the record. Use this method multiple times to attach multiple components.

Parameters:: component (Component) – Component which is to be added

with_meta(meta: Meta)

Adds Meta to the record.

Parameters:: meta (Meta) – Meta datastructure

with_stop_time(stop_time: datetime.datetime)

Adds a stop_time to the record. This is the time when the resource stopped being available.

Parameters:: stop_time (datetime.datetime) – Timestamp when resource stopped being available

class pyauditor.Meta

Meta stores a list of key value pairs of the form String -> [String].

The strings must not include the characters. /, (, ), ", <, >, \, {, }.

get(key: str)

Returns a list of string values matching the given key

Parameters:: key (str) – Key to get

insert(key: str, value: [str])

Insert a key-value pair into Meta

Parameters:

key (str) – Key
value ([str]) – Value

class pyauditor.Component(name: str, amount: int)

A component represents a single component which is to be accounted for. It consists at least of a name and an amount (how many or how much of this component is to be accounted for). Multiple scores can be attached to a single Component.

The amount must be >= 0 and the name must not include the characters. /, (, ), ", <, >, \, {, }.

Parameters:

name (str) – Name of the component
amount (int) – Amount

amount: Returns the amount of the component

name: Returns the name of the component

scores: Returns all scores attached to the component

with_score(score: Score): Attaches a score to the Component.

class pyauditor.Score(name: str, value: float)

An individual score which consists of a name (str) and a value (float). Scores are attached to a Component and are used to relate different components of the same kind to each other in some kind of performance characteristic. For instance, in case of CPUs, a score could be the corresponding HEPSPEC06 values.

The value must be >= 0.0 and the name must not include the characters. /, (, ), ", <, >, \, {, }.

Parameters:

name (str) – Name of the score
value (float) – Value

name: Returns the name

value: Returns the value