@awarns/tracing

Background execution flows can become quite complex when using the AwarNS Framework, which is not necessarily a bad thing. This module aids at debugging such workflows, thanks to a set of decorators and tasks which allow to keep track of task executions and the raise of certain events. The recorded traces can later be queried and exported to a local file. Optionally, it is possible to automatically store the recorded traces in an external data store (e.g., a backend).

Install the plugin using the following command line instruction:

ns plugin add @awarns/tracing

Usage

After installing and configuring this plugin, you'll be granted with two interaction mechanisms to work with it:

1. The plugin API. Through it, you'll be able to "decorate" existing tasks, to keep track of their execution. Then, you can query the recorded execution traces and export them using the most common information exchange formats.
2. Tasks to track the raise of certain events. Sometimes, the execution of a task itself is not interesting, but just one (or more) of the events it produces. Alternatively, the event generator might not be a task, but some UI code emitting an event in a very specific situation. If the rise of these events is relevant to your application, you can keep track of them using these tasks.

Setup

This plugin requires you to register its loader during the framework initialization, like this:

// ... platform imports
import { awarns } from '@awarns/core';
import { demoTasks } from '../tasks';
import { demoTaskGraph } from '../graph';
import { registerTracingPlugin } from '@awarns/tracing';

import { externalTracesStore } from './external-store';

awarns
  .init(
    demoTasks,
    demoTaskGraph,
    [
      registerTracingPlugin({
        externalTracesStore: externalTracesStore,
        oldTracesMaxAgeHours: 7 * 24 // 1 week
      }),
    ]
  )
  // ... handle initialization promise

Plugin loader config parameter options:

Property	Type	Description
externalTracesStore	TracesStore	(Optional) Inject an adapter to an external traces store and enable automatic upload of the recorded traces. The table below describes the methods that this adapter needs to implement
oldTracesMaxAgeHours	number	(Optional) Tell the plugin to regularly cleanup old local traces. By default, all traces are kept

TracesStore (external)

Method	Return type	Description
insert(trace: Trace)	Promise<void>	Persist the given trace. Throw an error if something goes wrong. The write will be retried during the next app initialization

Due to that, for now, this plugin only supports one-way synchronization, the rest of the methods are meant for future use and don't need to be implemented at the moment. You can throw unimplemented errors inside them, so that you can more easily recognize when they start being used in future versions.

API

The API of this plugin can be classified in 3 groups: task decorator, traces' storage and data exporters.

Task decorator

makeTraceable

In the task decorator group, there is the makeTraceable function, which allows to decorate one or more tasks to keep track of their execution, with the following parameters (see full example usage here):

Parameter	Type	Description
tasksToTrace	Array<Task>	An array including all the tasks that will be decorated to keep track of their execution
config	TracerConfig	(Optional) Allows to adjust some configuration options of the tracer. See TracerConfig properties for more

The makeTraceable function returns an array of decorated tasks.

TracerConfig

Property	Type	Description
outputsSensitiveData	boolean	Indicates the tracer that the tasks being tracked outputs sensitive information that should not be recorded. Defaults to false

Traces storage

tracesStore

In the traces' storage group, there is the tracesStore singleton object, with the following methods:

Method	Return type	Description
insert(record: Record)	Promise<void>	Persist the given trace. On success, if provided during plugin initialization, it will try to automatically write the new trace to the external store
getAll(reverseOrder?: boolean, limitSize?: number)	Promise<Array<Trace>>	Allows to retrieve the current latest (by default) or first traces, optionally limiting the resulting list in size
list(size?: number)	Observable<Trace>	Allows to observe the "n" most recent traces, where "n" is determined by the value given to the size parameter. By default, size is 100
clear()	Promise<void>	Allows to clear all the stored traces from the local database. Note: to only remove old traces, configure the oldTracesMaxAgeHours option during plugin initialization
changes (property)	Observable<Array<string>>	Listen to this observable property to know when a trace has been created. It propagates updates on the ids of the traces that have been recently stored

Note: It is recommended to install RxJS, to operate with the methods that return an Observable.

Trace

Property	Type	Description
id	string	The unique id of the trace
chainId	string	The id of the chain that the trace belongs to. A chain is a succession of event rises and task executions, which originate from the same starting event
type	TraceType	Can either be task or event depending on what originated the trace
name	string	The name of the task or the event that originated the trace
result	TraceResult	Can either be OK or error. This value is always OK for event traces, since, if something goes wrong, the event won't rise at all
timestamp	Date	The date and time when the trace was originated
content	object	Task traces and event traces follow a different structure in their content property. Event traces will contain here the payload of the event, unless it has been declared that the event contains sensitive data, in which case, it will hold an empty ({}) object. The content of task traces has a fixed structure, which can be seen below

Trace content (Task)

Property	Type	Description
emitted	string	The name of the event emitted by the task
outcome	string	The payload included in the event emitted by the task. If outputsSensitiveData is set to true in the tracer config, this property will hold an empty object ({}) instead
message	string	If an error was thrown during the execution of the task, its stack trace will appear here
took	number	The task execution time, in milliseconds

Export data

createRecordsExporter

In the final group, the data exporters group, there is the createTracesExporter() function, with the following parameters:

Parameter	Type	Description
folder	Folder	System folder object. Use NativeScript FileSystem API to define where the exports file will be saved
format	'csv' | 'json'	Select the information exchange format to use. Defaults to csv
fileName	string	(Optional) Specify the file name to use for the exports file (without extension). Defaults to current date and time

The createRecordsExporter() returns an Exporter object with the following API:

Exporter

Method	Return type	Description
export()	Promise<ExportResult>	Tell the exporter to export the traces, and save them inside to the configured exports file. Returns an ExportResult once done

ExportResult

Property	Return type	Description
exportCount	number	The amount of traces that have been exported
fileName	string	The name of the exports file that has been saved

Tasks

Task name	Description
trackEvent	Generates an event trace containing the information regarding the event that invoked its execution
trackSensitiveEvent	Generates an event trace containing the information regarding the event that invoked its execution. The payload of the event will be ignored, since it is considered to contain sensitive information

Track regular events

To register this task for its use, you just need to import it and call its generator function inside your application's task list:

import { Task } from '@awarns/core/tasks';
import { trackEventTask } from '@awarns/tracing';

export const demoTasks: Array<Task> = [
  trackEventTask(),
];

Task generator parameters:

The task generator takes no parameters.

Task output events:

• trackEventFinished (default, no content)

Example usage in the application task graph:

on('startEvent', run('trackEvent')); // Include some payload data in your start event, 
                                     // to see how it becomes recorded too

Track events containing sensitive information

To register this task for its use, you just need to import it and call its generator function inside your application's task list:

import { Task } from '@awarns/core/tasks';
import { trackSensitiveEventTask } from '@awarns/tracing';

export const demoTasks: Array<Task> = [
  trackSensitiveEventTask(),
];

Task generator parameters:

The task generator takes no parameters.

Task output events:

• trackSensitiveEventFinished (default, no content)

Example usage in the application task graph:

on('startEvent', run('trackSensitiveEvent')); // Include some payload data in your start event, 
                                              // to see how it does not appear in the event trace

License

Apache License Version 2.0