ODA Execution Block API Client

The ODA offers a custom API for Execution Blocks, so they can be created and updated during telescope operation without operators needing to know the internal ODA details. See the REST API documentation for more.

Generally, it is expected that the create_eb function will be called at the start of a session, and function calls where the request/response should be stored in the ExecutionBlock should be decorated with @capture_request_response. For more context on Execution Blocks, see the section in the Scripting documentation

This client is intended to be imported when sending commands to the telescope, for example during a Jupyter notebook session or SB driven observing from the OET.

It provides functions to interact with the ODA EB API.

ska_db_oda.client.ebclient.capture_request_response(fn: Callable) → Callable[source]

A decorator function which will record requests and responses sent to the telescope in an Execution Block within the ODA. It will send individual request_response objects to the ODA /ebs/<eb_id>/request_response API over HTTP, containing the decorated function name, the arguments and the return value, as well as timestamps.

Important: the function assumes two environment variables are set:

  • ODA_URI: the location of a running instance of the ODA, eg https://k8s.stfc.skao.int/staging-ska-db-oda/api/v1/

  • EB_ID: the identifier of the ExecutionBlock to update. The create_eb function from this module should have already been called during execution, which will set this variable.

The decorator is designed such that it does not block execution of commands if there is a problem with the ODA connection, or the environment variables are not set. Instead, a warning message is logged and execution allowed to continue. Also, any errors raised by the decorated function will not be changed, they will just be recorded in the ODA and reraised.

The standard OSO Scripting functions are decorated using this function, so will automatically record request/responses. To record other function calls in an Execution Block, either use this decorator in your source code:

from ska_db_oda.client.ebclient import capture_request_response

@capture_request_response
def my_function_to_record(args):
    ...

or use at runtime when calling the function:

from ska_db_oda.client.ebclient import capture_request_response

capture_request_response(my_function_to_record)(args)
ska_db_oda.client.ebclient.create_eb() → str[source]

Calls the ODA /ebs/create API to create an ‘empty’ ExecutionBlock in the ODA, ready to be updated with request/responses from telescope operation.

This function will also set the EB_ID environment variable to the value of the eb_id returned from the create request, so it can be used by subsequent calls to capture_request_response during the same session.

Important: the ODA_URI environment variables must be set to a running instance of the ODA, eg https://k8s.stfc.skao.int/staging-ska-db-oda/api/v1/

Returns:

The eb_id generated from SKUID that is persisted in the ODA

Raises:

  • KeyError – if the ODA_URI variable is not set

  • ConnectionError – if the ODA requests raises an error or returns a status code other than 200