soundworks | plugin logger

soundworks plugin for recording arbitrary data from any node of the network into plain old files.

Table of Contents

• Installation
• Usage
  • Server
  • Client
• Notes & Receipes
  • Default extension
  • Prefix in log files
  • Creating log files in sub-directories
  • Share a writer between several clients
  • Client-side buffering
• API
  • Classes
  • PluginLoggerClient
  • PluginLoggerServer
  • WriterClient
  • WriterServer
• Credits
• License

Installation

npm install @soundworks/plugin-logger --save

Usage

Server

// index.js
import { Server } from '@soundworks/core/server.js';
import pluginLogger from '@soundworks/plugin-logger/server.js';

const server = new Server(config);
server.pluginManager.register('logger', pluginLogger, {
  // define directory in which the files will be written, 
  // defaults to `null`, i.e. kind of "idle" plugin state
  dirname: 'logs',
});

await server.start();
// create a logger
const logger = await server.pluginManager.get('logger');
const writer = await logger.createWriter('my-server-log');
writer.write('hello server');

Client

// index.js
import { Client } from '@soundworks/core/client.js';
import pluginLogger from '@soundworks/plugin-logger/client.js';

const client = new Client(config);
client.pluginManager.register('logger', pluginLogger);

await client.start();
// create a logger
const logger = await client.pluginManager.get('logger');
const writer = await logger.createWriter('my-client-log');
writer.write('hello client');

Notes & Receipes

In the following examples, we assume the server-side logger as been configured to use the logs directory.

Default extension

If a writer is created with no extesion in its name, the .txt extention is added by default, otherwise the given extension is kept intact:

const writer = await logger.createWriter('first-log.txt');
console.log(writer.pathname);
> 'logs/2023.07.3_16.39.43_0001_first-log.txt';

const writer = await logger.createWriter('second-log.md');
console.log(writer.pathname);
> 'logs/2023.07.3_16.39.43_0002_second-log.txt';

Prefix in log files

By default all log files (client-side and server-side) are prefixed following a format: yyyy.mm.dd_hh.mm.ss_id_${basename}. This behavior can be turned of by seeting the usePrefix option to false when creating a writer.

With usePrefix = true (default):

const writer = await logger.createWriter('my-log.txt');
console.log(writer.pathname);
> 'logs/2023.07.3_16.39.43_0001_my-log.txt';

With usePrefix = false:

const writer = await logger.createWriter('my-log.txt', { usePrefix: false });
console.log(writer.pathname);
> 'logs/my-log.txt';

While usefull in some situations, this option can lead to errors if two writers are created with the same name.

Creating log files in sub-directories

If a path is given in the name, e.g. my-dir/my-log, sub-directories will be automatically created:

const writer = await logger.createWriter(`my-dir/my-log`);
console.log(writer.pathname);
> 'logs/my-dir/my-log.txt';

Share a writer between several clients

In a similar way as the shared state (while most simple), clients can attach to a writer created by the server. This can be used for example to create global logs informations where all clients contribute. Create a writer server as usual:

// server-side
const sharedWrite = await logger.createWriter('shared-writer');

Attach to the writer on the client-size, note the attachWriter method:

// client-side
const sharedWriter = await logger.attachWriter('shared-writer');

All writers created by the server can be attached by clients.

Client-side buffering

In many cases you may want to buffer the data client-side and batch the sends to the server to avoid network congestion. This can be done on writers created or attach by the client by defining the bufferSize option.

// client-side
const myWriter = await logger.createWriter('buffered-writer', { bufferSize: 10 });
// data is buffered on the client side
myWriter.write('1');
myWriter.write('2');
// ...
myWriter.write('10');
// data is sent to the server

API

Classes

PluginLoggerClient

Client-side representation of the soundworks sync plugin.

Kind: global class

• PluginLoggerClient
  • new PluginLoggerClient()
  • .createWriter(name, options)
  • .attachWriter(name, options)

new PluginLoggerClient()

The constructor should never be called manually. The plugin will be instantiated by soundworks when registered in the pluginManager

Example

client.pluginManager.register('logger', pluginLogger);

pluginLoggerClient.createWriter(name, options)

Create a writer.

Kind: instance method of PluginLoggerClient

| Param | Type | Default | Description | | --- | --- | --- | --- | | name | String | | Name of the writer. Used to generate the log file pathname. | | options | Object | | Options for the writer. | | [options.bufferSize] | Number | 1 | Number of writes buffered before sending the logs to the server. | | [options.usePrefix] | Boolean | true | Whether the writer file should be prefixed with a YYYY.MM.DD_hh.mm.ss_uid_ string. | | [options.allowReuse] | Boolean | false | If usePrefix is false, allow to reuse an existing underlying file for the writer. New data will be appended to the file. Can be usefull to log global informations in the same file amongst different sessions. |

pluginLoggerClient.attachWriter(name, options)

Attach to a shared writer created by the server. Can be usefull to create files that gather informations from multiple nodes.

Kind: instance method of PluginLoggerClient

| Param | Type | Default | Description | | --- | --- | --- | --- | | name | String | | Name of the writer. Used to generate the log file pathname. | | options | Object | | Options for the writer. | | [options.bufferSize] | Number | 1 | Number of writes buffered before sending the logs to the server. |

PluginLoggerServer

Server-side representation of the soundworks logger plugin.

Kind: global class

• PluginLoggerServer
  • new PluginLoggerServer()
  • .switch(dirname)
  • .createWriter(name, options)

new PluginLoggerServer()

The constructor should never be called manually. The plugin will be instantiated by soundworks when registered in the pluginManager

Available options:

• [dirname=null] {String} - The directory in which the log files should be created. If null the plugin is in some "idle" state, and any call to createWriter (or client-side attachWriter) will throw an error. The directory can be changed at runtime usin the switch method.

Example

server.pluginManager.register('logger', pluginLogger, {
  dirname: 'my-logs',
});

pluginLoggerServer.switch(dirname)

Change the directory in which the log files are created. Closes all existing writers.

Kind: instance method of PluginLoggerServer

| Param | Type | Description | | --- | --- | --- | | dirname | String | Object | Path to the new directory. As a convenience to match the plugin filesystem API, an object containing the 'dirname' key can also be passed. |

pluginLoggerServer.createWriter(name, options)

Create a writer.

Kind: instance method of PluginLoggerServer

| Param | Type | Default | Description | | --- | --- | --- | --- | | name | String | | Name of the writer. Used to generate the log file pathname. | | options | Object | | Options for the writer. | | [options.usePrefix] | Boolean | true | Whether the writer file should be prefixed with a YYYY.MM.DD_hh.mm.ss_uid_ string. | | [options.allowReuse] | Boolean | false | If usePrefix is false, allow to reuse an existing underlying file for the writer. New data will be appended to the file. Can be usefull to log global informations in the same file amongst different sessions. |

WriterClient

Client-side stream writer.

Created and retrived by the client-side logger.createWriter(name, bufferSize) and logger.attachWriter(name, bufferSize) methods.

Kind: global class

• WriterClient
  • .name
  • .pathname
  • .write(data)
  • .flush()
  • .close() ⇒ Promise
  • .onPacketSend(callback) ⇒
  • .onClose(callback) ⇒

writerClient.name

Name of the Writer.

Kind: instance property of WriterClient
Read only: true

writerClient.pathname

Pathname of the Writer.

Kind: instance property of WriterClient
Read only: true

writerClient.write(data)

Format and write data.

• Successive write calls are added to a new line
• Data can be of any type, it will be stringified before write.
• TypedArrays are converted to Array before being stringified.

Kind: instance method of WriterClient

| Param | Type | Description | | --- | --- | --- | | data | Any | Data to be written |

writerClient.flush()

Flush the buffer, only applies if bufferSize option is set.

Kind: instance method of WriterClient

writerClient.close() ⇒ Promise

Close the writer.

Kind: instance method of WriterClient
Returns: Promise - Promise that resolves when the stream is closed

writerClient.onPacketSend(callback) ⇒

Register a function to be executed when a packet is sent on the network., i.e. when the buffer is full or flushed on close.

Kind: instance method of WriterClient
Returns: Function that unregister the listener when executed.

| Param | Type | Description | | --- | --- | --- | | callback | function | Function to execute on close. |

writerClient.onClose(callback) ⇒

Register a function to be executed when the Writer is closed. The function will be executed after the buffer has been flushed and underlying state has been deleted, and before the close Promise resolves.

Kind: instance method of WriterClient
Returns: Function that unregister the listener when executed.

| Param | Type | Description | | --- | --- | --- | | callback | function | Function to execute on close. |

WriterServer

Server-side stream writer.

Created and retrived by the server-side logger.createWriter(name) method.

Kind: global class

• WriterServer
  • .name
  • .pathname
  • .write(data)
  • .close() ⇒ Promise
  • .onClose(callback) ⇒

writerServer.name

Name of the Writer.

Kind: instance property of WriterServer
Read only: true

writerServer.pathname

Pathname of the Writer.

Kind: instance property of WriterServer
Read only: true

writerServer.write(data)

Format and write data.

• Successive write calls are added to a new line
• Data can be of any type, it will be stringified before write.
• TypedArrays are converted to Array before being stringified.

Kind: instance method of WriterServer

| Param | Type | Description | | --- | --- | --- | | data | Any | Data to be written |

writerServer.close() ⇒ Promise

Close the writer and the underlying stream.

Kind: instance method of WriterServer
Returns: Promise - Promise that resolves when the stream is closed

writerServer.onClose(callback) ⇒

Register a function to be executed when the Writer is closed. The function will be executed when the underlying stream is closed and before the close() Promise is resolved.

Kind: instance method of WriterServer
Returns: Function that unregister the listener when executed.

| Param | Type | Description | | --- | --- | --- | | callback | function | Function to execute on close. |

Credits

The code has been initiated in the framework of the WAVE and CoSiMa research projects, funded by the French National Research Agency (ANR).

License

BSD-3-Clause