@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