Execution Blocks

What is an Execution Block?

An Execution Blocks (EB) is a record of what happened during an observing session, at the level of the requests and responses sent from OSO to TMC, or any other commands that are decided to be captured. They also provide the link between the data product back to the Project or Proposal - SDP uses the eb_id generated within OSO. For more information on the data model, see the documentation for the PDM project, which is where the EB is defined.

An observing session could be full SBDefinition execution through the Observation Execution Tool (OET), or an ad-hoc notebook execution. Using EBs in notebooks means there is a record of what happened during execution, and the observations will show up in other OSO tools like the Project Tracking Tool (PTT) and the Shift Log Tool (SLT)

EBs are stored in the OSO Data Archive (ODA) and ska-oso-scripting offers an execution_block helper module for creating and updating EBs. This helper modules provides 4 functions:

  1. create_eb - should be called at the start of an observing session to create the EB and set the EB_ID environment variable for use throughout the session.

  2. capture_request_response - a decorator that can be used to capture any Python function calls, and is used to decorate the ska-oso-scripting functions that send TMC commands by default.

  3. mark_eb_observed/mark_eb_failed - updates the OSO status for the EB_ID for tracking purposes

Capturing an observing session in an Execution Block

In either SBDefinition execution or notebooks, the same process for capturing data in an Execution Block should be followed:

  1. Ensure the correct environment variables are set (see next section)

  2. At the start of the session or script, call the create_eb

from ska-oso-scripting.api import execution_block

execution_block.create_eb()

  1. Functions that are decorated with @execution_block.capture_request_response will send the request_responses to the ODA with the relevant eb_id. The public functions in ska_oso_scripting.api are already decorated. To capture custom function calls, the decorator can either imported and added to the function definition, or functions calls can be decorated on the fly during the execution in the session:

from ska-oso-scripting.api import execution_block

# Decorate the function in the source code
@execution_block.capture_request_response
def my_function_to_record(args):
    ...

# OR 'decorate' the function at runtime when calling
my_response = execution_block.capture_request_response(my_function_to_record)(args)

  1. Finish the observing session by marking the EB as either successfully Observed or Failed

from ska-oso-scripting.api import execution_block

...

try:

    observe(...)
    execution_block.mark_execution_block_observed(eb_id)
except Exception as err:
    execution_block.mark_execution_block_failed(eb_id=eb_id, error_message=str(err))
    raise

Configuring the helper module

For SBDefinition execution, the execution_block module will use the PG_ environment variables available in the OET to connect directly to the ODA database.

In the notebook case, if the PG_ variables cannot be set, ska-oso-services offers an /engineering API (see the docs) that the helper will connect to. For this, the OSO_SERVICES_URL must be set to a value like $(HOST)/$(KUBE_NAMESPACE)/oso/api/v$(OSO_SERVICES_API_VERSION) ``