Package for collecting information about the execution of a use case
Project description
Use Case Outcome
A Python package that records logs and metrics throughout the execution of a Use Case ran in Swimlane. This allows us to easily save a record within our Use Case Outcome application to diagnose issues with Use Cases much quicker.
In this README :point_down:
Usage
Initial setup
- Simply install the package
pip install use_case_outcome
or pip install use_case_outcome==1.0.0
- Import it into your module:
from use_case_outcome import UseCaseOutcome
- Initialise your own instance of
UseCaseOutcome
uco = UseCaseOutcome(swimlane, "Application Name", "Integration Name", extra_key_value="test")
- Start your use case. This will start your timer and you can log your logs, metrics and fields changed as you go through. Please refer to Functionality
uco.start()
Creating releases
Manually
If you wish to build and deploy a release of this package manually from your own machine, you can do that via the poetry CLI
. Please ensure that you have a value key setup to access PyPi with Poetry. Please see the docs for poetry here
Build the package:
Poetry uses the pyproject.toml
file for it's config when you run commands within this directory, so it gets all of it's information about the package from there including any dependencies and where to look for the modules.
poetry build
Publish the packagee:
Once you have your creds setup with PyPi and you're ready to publish, you should be able to publish by using the below command
poetry publish
Functionality
UseCaseOutcome class
Properties
sl
- Swimlane instanceapp_name
- The application name that the Use Case belongs tointegration_name
- The integration that is runningdefault_fields
- Any default fields that you want available on every loglogs
- All of the logs that get logged during the execution of a use casemetrics
- All of the metrics that get logged during the execution of a use casefields_changed
- All of the fields changed that get logged during the execution of a use caseuse_case_started
- The timestamp of when the use case was started (seestart()
method below)arbitrary_record_fields
- This is to protect future enhancements to the UseCaseOutcome application. Applications can make use of new fields without having to update this package
Methods
__init__(self, sl: Swimlane, app_name: str, integration_name: str, **default_fields)
:
Parameters:
* sl: Swimlane - The Swimlane instance that you instantiate inside of your Use Case
* app_name: str - The application name that triggered the use case
* integration_name: str - The integration that is executing
* default_fields: kwargs - This is a kwargs argument allowing you to pass in default fields for your logs. This means any fields passed in via this parameter will be available on every log
start(self)
:
The
start()
method is called at the start of a Use Case and records the time that it starts on the UseCaseOutcome object
update_field(self, field_name: str, field_value: str)
:
Update field is used to update a field inside of the Use Case Outcome application. It remains dynamic to ensure that as fields get added to the Use Case Outcome application, we don't have to apply updated to this package
Parameters:
* field_name: str - The field name on the Use Case Outcome application you wish to update. To conform with Python standards, we have some processing on the field names and so they have to be in a certain format. Example : If the field in the Use Case Outcome application is `Saim Case Created`, then the `field_name` you would pass into this method would be `saim_case_created`. **IMPORTANT: We must ensure that fields in the Use Case Outcome application conform with this format : Saim Case Created. Each word capitalised and separated by a space**
* field_value: str - The value you wish to set the field to in the Use Case Outcome application
submit(self, status: Literal["Success", "Failed"], record: Record, auto_closed: bool = False)
:
This is what you will run at the end, once you have finished the use case. This will take all of the logs, metrics and other pieces of information you have gathered during the executing of your use case and create a record in the Use Case Outcome application allowing you to see them all in a single record
Parameters:
* status: Literal["Success", "Failed"] - The status of which the use case was. Currently only either a complete success, or a complete failure
* record: Record - The record the Use Case is running for
* auto_closed: Bool = False - Whether or not the execution of the use case caused an auto-closure of that current record or not
duration(self, end_time: DateTime) -> float
:
A helper method that simply takes in an end time and gets the duration between the
start_time
on the object and the end time that was passed in
Parameters:
* end_time: DateTime - It uses this time, and the start time registered when running the `start()` method to work out an overall duration. This method is ran as part of the `submit` method so is nothing you have to worry about in a use case
Returns:
* duration: float - The duration in seconds between `self.start_time` and the `end_time` parameter
create_uco_record(self, data: Dict[str, Any], record: Record)
This is responsible for taking the data that has been processed inside of the object already and creating the Use Case Outcome application which allows us to refer back to this data at a later date. This method is called within the
submit()
method and so is nothing you have to worry about inside of your use case
Parameters:
* data: Dict[str, Any] - This is the data you want to unpack to create the actual record. The data processing has already been done within the `submit()` method
* record: Record - The originating record that is creating the Use Case Outcome record. This will allow us to add a reference back to that originating record
log(self, level: str, **kwargs)
This is a generic log method which allows us to create logs to be created in the Use Case Outcome record. The levels allowed are as per below. Kwargs allows you to pass any number of arbitrary key/value pairs into your logs allowing for ultimate flexibility
Levels allowed : _LEVELS = ["debug", "info", "warning", "error", "critical"]
Parameters:
* level: str - The level, as a string. It must be one of those defined in `_LEVELS` as outlined above
* **kwargs - Each log may require different amounts of information to provide different pieces of contextual information to that log, depending on what it's doing. That's what kwargs allows us to do, each log will have full flexibility in terms of what data it can provide to that particular log
metric(self, metric_name: str, metric_value: Any)
:
This is a method, similar to the log method that allows you to create metrics on the fly during the execution of your use case. You can only ever create one metric/value at one time
Parameters:
* metric_name: str - The name of your metric
* metric_value: Any - The value of your metric
record_saved(self)
:
This is ran whenever you have ran the
save()
orpatch()
method on your record within your use case. This will then record that time against all fields taht were changed as part of that process
field_changed(self, field_name: str, old_field_value: str, new_field_value: str)
:
This method allows us to register whenever a field is changed within your use case. For example if you're setting
analysis complete
toYES
, then this would be an opportunity to run this method. When you run therecord_saved
method, it will go through the fields and record a timestamp against when they changed
Parameters:
* field_name: str - The field name that we have changed the value of
* old_field_value: str - The old field value, the value we are changing from
* new_field_value: str - This is the value we have changed to
_normalise_logs(self)
:
The widget responsible for displaying the logs, requires there to be the exact same fields available in each log. This is a problem with the setup we have, as each log can contain any arbitrary key/value pairs and therefore by default this isn't the case. This method will iterate over all of the logs ensuring that they contain all of the same key/value pairs - allowing our widget to work
_normalise_keys(d: dict)
:
A helper method to normalise the keys of the dictionary that is passed in. It will iterate over all of the keys, replace the
_
with aspace
and replacing the start of each word with a capitalised letter.create_saim_case
becomesCreate Saim Case
Parameters:
* d: dict - The data of which we want to normalise the keys for
Contributing
To contribute to this project, please just Git Clone the project and ensure a pull request is raised and assigned to an applicable person
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for use_case_outcome-1.2.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | a8957c5bda085cc896638cd5d2a5cb010480c541a21a3338b7ec87c1e259b5da |
|
MD5 | b0d4adf96cce10be6d321ffdac444dfe |
|
BLAKE2b-256 | ea261688d6d819e000ba4565eca9b235b8e93bc506eb6b29b84fb5e0e8c543d2 |