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.

PluginLoggerServer

Server-side representation of the soundworks logger plugin.

WriterClient

Client-side stream writer.

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

WriterServer

Server-side stream writer.

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

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

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

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

pluginLoggerServer.createWriter(name, options) ​

Create a writer.

Kind: instance method of PluginLoggerServer

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

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.

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.

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

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.

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