@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:

TracesStore (external)

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):

The makeTraceable function returns an array of decorated tasks.

TracerConfig

Traces storage

tracesStore

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

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

Trace

Trace content (Task)

Export data

createRecordsExporter

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

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

Exporter

ExportResult

Tasks

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