soundworks | plugin logger

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

Table of Contents

• Installation
• Usage
• Notes & Recipes
• API
• ClientPluginLogger
• ClientWriter
• ServerPluginLogger
• ServerWriter
• Credits
• License

Installation

npm install @soundworks/plugin-logger --save

Usage

Server

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

const server = new Server(config);
server.pluginManager.register('logger', ServerPluginLogger, {
  // 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 ClientPluginLogger from '@soundworks/plugin-logger/client.js';

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

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 & Recipes

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 extension in its name, the .txt extension 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 setting 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 useful 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 information 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

Table of Contents

• ClientPluginLogger
  • Examples
  • createWriter
  • attachWriter
• ClientWriter
  • Parameters
  • name
  • pathname
  • write
  • flush
  • close
  • onPacketSend
  • onClose
• ServerPluginLogger
  • Examples
  • switch
  • createWriter
• ServerWriter
  • Parameters
  • name
  • pathname
  • write
  • close
  • onClose

ClientPluginLogger

Extends ClientPlugin

Client-side representation of the soundworks sync plugin.

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

Examples

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

createWriter

Create a writer.

Parameters

• name String Name of the writer. Used to generate the log file pathname.

• options Object Options for the writer. (optional, default {})

  • options.bufferSize Number Number of writes buffered before sending the logs to the server. (optional, default 1)
  • options.usePrefix Boolean Whether the writer file should be prefixed with a YYYY.MM.DD_hh.mm.ss_uid_ string. (optional, default true)
  • options.allowReuse Boolean If usePrefix is false, allow to reuse an existing underlying file for the writer. New data will be appended to the file. Can be useful to log global information in the same file amongst different sessions. (optional, default false)

attachWriter

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

Parameters

• name String Name of the writer. Used to generate the log file pathname.

• options Object Options for the writer. (optional, default {})

  • options.bufferSize Number Number of writes buffered before sending the logs to the server. (optional, default 1)

ClientWriter

Client-side stream writer.

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

Parameters

• plugin
• state
• bufferSize (optional, default 1)

name

Name of the Writer.

pathname

Pathname of the Writer.

write

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.

Parameters

• data Any Data to be written

flush

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

close

Close the writer.

Returns Promise Promise that resolves when the stream is closed

onPacketSend

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.

Parameters

• callback Function Function to execute on close.

Returns Function that unregister the listener when executed.

onClose

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.

Parameters

• callback Function Function to execute on close.

Returns Function that unregister the listener when executed.

ServerPluginLogger

Extends ServerPlugin

Server-side representation of the soundworks logger plugin.

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 using the switch method.

Examples

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

switch

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

Parameters

• 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.

createWriter

Create a writer.

Parameters

• name String Name of the writer. Used to generate the log file pathname.

• options Object Options for the writer. (optional, default {})

  • options.usePrefix Boolean Whether the writer file should be prefixed with a YYYY.MM.DD_hh.mm.ss_uid_ string. (optional, default true)
  • options.allowReuse Boolean If usePrefix is false, allow to reuse an existing underlying file for the writer. New data will be appended to the file. Can be useful to log global information in the same file amongst different sessions. (optional, default false)

ServerWriter

Server-side stream writer.

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

Parameters

• state
• format (optional, default null)

name

Name of the Writer.

pathname

Pathname of the Writer.

write

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.

Parameters

• data Any Data to be written

close

Close the writer and the underlying stream.

Returns Promise Promise that resolves when the stream is closed

onClose

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.

Parameters

• callback Function Function to execute on close.

Returns Function that unregister the listener when executed.

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