Audit

This class processes log files to track and analyze the lifecycle of tasks, including their reception, completion, and success status. It provides mechanisms to identify incomplete tasks and generate summary reports on task types and error counts. Users can also provide custom callback functions to handle task errors, trace information, and debug logs during the auditing process.

Attributes

Attribute	Type	Description
ids	set = set()	A set of unique task identifiers encountered during the audit process.
names	dict = {}	A mapping of task identifiers to their corresponding task names.
results	dict = {}	A dictionary storing the result strings associated with each completed task identifier.
ready	set = set()	A set of task identifiers that have reached a ready state and completed execution.
task_types	Counter = Counter()	A counter tracking the frequency of each task name encountered.
task_errors	int = 0	The total count of tasks that failed to succeed during processing.
on_task_error	callable = None	An optional callback function triggered when a task error is detected.
on_trace	callable = None	An optional callback function used to handle multi-line trace information when log lines do not match the start pattern.
on_debug	callable = None	An optional callback function invoked for log lines that match the start pattern but are not recognized as task events.
prev_line	string = None	Stores the content of the previous log line to facilitate multi-line trace reconstruction.

---

Constructor

Signature

def Audit(
    on_task_error: callable = None,
    on_trace: callable = None,
    on_debug: callable = None
) - > null

Parameters

Name	Type	Description
on_task_error	callable = None	A callback function triggered when a task error is encountered.
on_trace	callable = None	A callback function for handling trace-level log information.
on_debug	callable = None	A callback function for handling debug-level log information.

---

Methods

---

run()

@classmethod
def run(
    files: list
) - > [Audit](audit.md?sid=celery_bin_logtool_audit)

Processes a collection of log files to audit task execution by feeding each line into the parser.

Parameters

Name	Type	Description
files	list	A list of file paths or file-like objects to be read and audited.

Returns

Type	Description
[Audit](audit.md?sid=celery_bin_logtool_audit)	The current Audit instance after processing all input files.

---

task_received()

@classmethod
def task_received(
    line: string,
    task_name: string,
    task_id: string
)

Registers a new task entry, tracking its unique identifier and incrementing the count for its specific task type.

Parameters

Name	Type	Description
line	string	The raw log line containing the task reception event.
task_name	string	The descriptive name or category of the task being received.
task_id	string	The unique UUID or identifier associated with the specific task instance.

---

task_ready()

@classmethod
def task_ready(
    line: string,
    task_name: string,
    task_id: string,
    result: string
)

Marks a task as completed and stores its result, triggering an error handler if the task did not succeed.

Parameters

Name	Type	Description
line	string	The raw log line indicating the task has finished processing.
task_name	string	The name of the task that has reached the ready state.
task_id	string	The unique identifier of the completed task.
result	string	The outcome message or status string returned by the task execution.

---

task_error()

@classmethod
def task_error(
    line: string,
    task_name: string,
    task_id: string,
    result: string
)

Increments the global error counter and executes the optional error callback for a failed task.

Parameters

Name	Type	Description
line	string	The log line associated with the task failure.
task_name	string	The name of the task that encountered an error.
task_id	string	The unique identifier of the failed task.
result	string	The error details or failure status returned by the task.

---

feed()

@classmethod
def feed(
    line: string
)

Parses a single log line to identify task lifecycle events or trigger trace and debug callbacks for unrecognized lines.

Parameters

Name	Type	Description
line	string	A single line of text from the log file to be analyzed.

---

incomplete_tasks()

@classmethod
def incomplete_tasks() - > set

Identifies tasks that were received but never reached a ready state.

Returns

Type	Description
set	A set of task IDs representing tasks that are still pending or lost.

---

report()

@classmethod
def report() - > dict

Generates a summary dictionary containing statistics on task types, totals, completions, and success rates.

Returns

Type	Description
dict	A nested dictionary containing aggregated audit metrics for all processed tasks.

---