Socket
Socket
Sign inDemoInstall

roarr

Package Overview
Dependencies
Maintainers
1
Versions
150
Alerts
File Explorer

Advanced tools

License
Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

roarr - npm Package Compare versions

Comparing version 2.13.3 to 2.14.0

dist/constants.js
dist/constants.js.flow
dist/constants.js.map
dist/factories/createMockLogger.js
dist/factories/createMockLogger.js.flow
dist/factories/createMockLogger.js.map
dist/factories/createNodeWriter.js
dist/factories/createNodeWriter.js.flow
dist/factories/createNodeWriter.js.map

26

dist/factories/createLogger.js

@@ -8,2 +8,4 @@ "use strict";

var _globalthis = _interopRequireDefault(require("globalthis"));
var _jsonStringifySafe = _interopRequireDefault(require("json-stringify-safe"));

@@ -13,3 +15,3 @@

var _config = require("../config");
var _constants = require("../constants");

@@ -24,11 +26,3 @@ function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }

var version = '1.0.0';
var logLevels = {
debug: 20,
error: 50,
fatal: 60,
info: 30,
trace: 10,
warn: 40
};
var globalThis = (0, _globalthis.default)();

@@ -38,8 +32,4 @@ var createLogger = function createLogger(onMessage, parentContext) {

var log = function log(a, b, c, d, e, f, g, h, i, k) {
if (!_config.ROARR_LOG && !global.ROARR_LOG) {
return;
}
var time = Date.now();
var sequence = global.ROARR.sequence++;
var sequence = globalThis.ROARR.sequence++;
var context;

@@ -65,3 +55,3 @@ var message;

time,
version
version: '1.0.0'
});

@@ -94,3 +84,3 @@ };

return log.child({
logLevel: logLevels[logLevel]
logLevel: _constants.logLevels[logLevel]
})(a, b, c, d, e, f, g, h, i, k);

@@ -100,3 +90,3 @@ };

for (var _i = 0, _Object$keys = Object.keys(logLevels); _i < _Object$keys.length; _i++) {
for (var _i = 0, _Object$keys = Object.keys(_constants.logLevels); _i < _Object$keys.length; _i++) {
_loop();

@@ -103,0 +93,0 @@ } // @see https://github.com/facebook/flow/issues/6705

15

dist/factories/createRoarrInititialGlobalState.js

@@ -10,8 +10,8 @@ "use strict";

var _detectNode = _interopRequireDefault(require("detect-node"));
var _package = require("../../package.json");
var _config = require("../config");
var _createNodeWriter = _interopRequireDefault(require("./createNodeWriter"));
var _createWriter = _interopRequireDefault(require("./createWriter"));
function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }

@@ -38,4 +38,2 @@

var newState = _objectSpread({
buffer: '',
prepend: {},
sequence: 0

@@ -46,7 +44,4 @@ }, currentState, {

if (currentIsLatestVersion || !newState.write) {
newState = _objectSpread({}, newState, {}, (0, _createWriter.default)({
bufferSize: _config.ROARR_BUFFER_SIZE,
stream: _config.ROARR_STREAM
}));
if (_detectNode.default && (currentIsLatestVersion || !newState.write)) {
newState = _objectSpread({}, newState, {}, (0, _createNodeWriter.default)());
}

@@ -53,0 +48,0 @@

21

dist/log.js

@@ -8,19 +8,16 @@ "use strict";

var _globalthis = _interopRequireDefault(require("globalthis"));
var _factories = require("./factories");
global.ROARR = (0, _factories.createRoarrInititialGlobalState)(global.ROARR || {}); // We want to register just one event listener for 'exit' event
// across all instances of Roarr.
function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
if (!global.ROARR.registeredFlush) {
global.ROARR.registeredFlush = true;
process.on('exit', function () {
if (global.ROARR.flush) {
global.ROARR.flush();
}
});
}
var globalThis = (0, _globalthis.default)();
globalThis.ROARR = (0, _factories.createRoarrInititialGlobalState)(globalThis.ROARR || {});
var _default = (0, _factories.createLogger)(function (message) {
var body = JSON.stringify(message);
global.ROARR.write(body);
if (globalThis.ROARR.write) {
var body = JSON.stringify(message);
globalThis.ROARR.write(body);
}
});

@@ -27,0 +24,0 @@

8

package.json

@@ -23,2 +23,4 @@ {

"boolean": "^1.0.0",
"detect-node": "^2.0.4",
"globalthis": "^1.0.0",
"json-stringify-safe": "^5.0.1",

@@ -54,4 +56,4 @@ "semver-compare": "^1.0.0",

"hooks": {
"post-commit": "npm run create-readme && git add README.md && git commit -m 'docs: generate docs' --no-verify",
"pre-commit": "npm run lint && npm run test && npm run build"
"pre-commit": "npm run lint && npm run test && npm run build",
"pre-push": "gitdown ./.README/README.md --output-file ./README.md --check"
}

@@ -90,3 +92,3 @@ },

},
"version": "2.13.3"
"version": "2.14.0"
}

160

README.md

@@ -16,4 +16,5 @@ <a name="roarr"></a>

* [Usage](#roarr-usage)
* [Producing logs](#roarr-usage-producing-logs)
* [Consuming logs](#roarr-usage-consuming-logs)
* [Filtering logs](#roarr-usage-filtering-logs)
* [jq primer](#roarr-usage-jq-primer)
* [Log message format](#roarr-log-message-format)

@@ -32,3 +33,3 @@ * [API](#roarr-api)

* [Transports](#roarr-transports)
* [Environment variables](#roarr-environment-variables)
* [Node.js environment variables](#roarr-node-js-environment-variables)
* [Conventions](#roarr-conventions)

@@ -74,9 +75,12 @@ * [Context property names](#roarr-conventions-context-property-names)

Roarr logging is disabled by default. To enable logging, you must start program with an environment variable `ROARR_LOG` set to `true`, e.g.
<a name="roarr-usage-producing-logs"></a>
### Producing logs
```bash
ROARR_LOG=true node ./index.js
Roarr logger API for producing logs is the same in Node.js and browser.
```
1. Import `roarr`
2. Use any of the [API](#api) methods to log messages.
e.g.
```js

@@ -87,71 +91,83 @@ import log from 'roarr';

log('bar %s', 'baz');
```
const debug = log.child({
logLevel: 10
});
<a name="roarr-usage-consuming-logs"></a>
### Consuming logs
debug('qux');
Roarr logs are consumed differently in Node.js and browser.
debug({
quuz: 'corge'
}, 'quux');
<a name="roarr-usage-consuming-logs-node-js"></a>
#### Node.js
```
In Node.js, Roarr logging is disabled by default. To enable logging, you must start program with an environment variable `ROARR_LOG` set to `true`, e.g.
Produces output:
```bash
ROARR_LOG=true node ./index.js
```
{"context":{},"message":"foo","sequence":0,"time":1506776210000,"version":"1.0.0"}
{"context":{},"message":"bar baz","sequence":1,"time":1506776210000,"version":"1.0.0"}
{"context":{"logLevel":10},"message":"qux","sequence":2,"time":1506776210000,"version":"1.0.0"}
{"context":{"logLevel":10,"quuz":"corge"},"sequence":3,"message":"quux","time":1506776210000,"version":"1.0.0"}
All logs will be written to stdout.
<a name="roarr-usage-consuming-logs-browser"></a>
#### Browser
In a browser, you must implement `globalThis.ROARR.write` method to read logs, e.g.
```js
globalThis.ROARR.write = () => {};
```
<a name="roarr-usage-filtering-logs"></a>
### Filtering logs
The API of the `ROARR.write` is:
Roarr is designed to print all or none logs (refer to the [`ROARR_LOG` environment variable](#environment-variables) documentation).
```js
(message: string) => void;
To filter logs you need to use [`roarr filter` CLI program](#filter-program) or a JSON processor such as [jq](https://stedolan.github.io/jq/).
```
<a name="roarr-usage-jq-primer"></a>
### jq primer
Example implementation:
`jq` allows you to filter JSON messages using [`select(boolean_expression)`](https://stedolan.github.io/jq/manual/#select(boolean_expression)), e.g.
```js
// Ensure that `globalThis.ROARR` is configured.
globalThis.ROARR = globalThis.ROARR || {};
```bash
ROARR_LOG=true node ./index.js | jq 'select(.context.logLevel > 40)'
globalThis.ROARR.write = (message) => {
console.log(JSON.parse(message));
};
```
Combine it with `roarr pretty-print` to pretty-print a subset of the logs:
<a name="roarr-usage-filtering-logs"></a>
### Filtering logs
<a name="roarr-usage-filtering-logs-node-js-1"></a>
#### Node.js
In Node.js, Roarr prints all or none logs (refer to the [`ROARR_LOG` environment variable](#environment-variables) documentation).
Use [`roarr filter` CLI program](#filter-program) to filter the logs that are written to stdout by the program, e.g.
```bash
ROARR_LOG=true node ./index.js | jq -cM 'select(.context.logLevel > 40)'
ROARR_LOG=true node ./index.js | roarr filter '{"context.logLevel":{gt:30}}'
```
(Notice the use of `-cM` parameters to disable JSON colorization and formatting.)
Alternatively, use a JSON processor such as [jq](https://stedolan.github.io/jq/)
If your application outputs non-JSON output, jq will fail with an error similar to:
<a name="roarr-usage-filtering-logs-browser-1"></a>
#### Browser
```
parse error: Invalid numeric literal at line 1, column 5
Error: write EPIPE
at _errnoException (util.js:1031:13)
at WriteWrap.afterWrite (net.js:873:14)
In a browser, Roarr calls `globalThis.ROARR.write` for every log message. Implement your own custom logic to filter logs, e.g.
```
```js
globalThis.ROARR.write = (message) => {
const payload = JSON.parse(message);
To ignore the non-JSON output, use jq `-R` flag (raw input) in combination with [`fromjson`](https://stedolan.github.io/jq/manual/#Convertto/fromJSON), e.g.
if (payload.context.logLevel > 30) {
console.log(payload);
}
};
```bash
ROARR_LOG=true node ./index.js | jq -cRM 'fromjson? | select(.context.logLevel > 40)'
```
For a simplified way of filtering Roarr logs, refer to [`roarr filter` CLI program](#filter-program).
<a name="roarr-log-message-format"></a>

@@ -189,3 +205,3 @@ ## Log message format

`roarr` package exports a function that accepts the following API:
`roarr` package exports a function with the following API:

@@ -242,9 +258,9 @@ ```js

Creates a child logger appending the provided `context` object to the previous logger context.
```js
type ChildType = (context: MessageContextType) => LoggerType;
(context: MessageContextType) => LoggerType;
```
Creates a child logger appending the provided `context` object to the previous logger context.
Example:

@@ -272,9 +288,9 @@

Creates a child logger where every message is intercepted.
```js
type ChildType = (translateMessage: TranslateMessageFunctionType) => LoggerType;
(translateMessage: TranslateMessageFunctionType) => LoggerType;
```
Creates a child logger where every message is intercepted.
Example:

@@ -288,3 +304,3 @@

...message,
message: message.message.replace('foo', 'bar')
message: message.message.replace('foo', 'bar'),
}

@@ -306,2 +322,17 @@ });

Example:
```js
import log from 'roarr';
const childLogger = log.child({
foo: 'bar'
});
childLogger.getContext();
// {foo: 'bar'}
```
<a name="roarr-api-trace"></a>

@@ -320,3 +351,3 @@ ### <code>trace</code>

Convenience methods for logging a message with `logLevel` context property value set to the name of the convenience method, e.g.
Convenience methods for logging a message with `logLevel` context property value set to a numeric value representing the [log level](#log-levels), e.g.

@@ -379,3 +410,3 @@ ```js

Roarr CLI program provides ability to augment, filter and pretty-print Roarr logs.
Roarr CLI program provides ability to filter and pretty-print Roarr logs.

@@ -408,6 +439,6 @@ ![CLI output demo](./.README/cli-output-demo.png)

<a name="roarr-environment-variables"></a>
## Environment variables
<a name="roarr-node-js-environment-variables"></a>
## Node.js environment variables
When running the script in a Node.js environment, use environment variables to control `roarr` behaviour.
Use environment variables to control `roarr` behaviour.

@@ -418,3 +449,2 @@ |Name|Type|Function|Default|

|`ROARR_STREAM`|`STDOUT`, `STDERR`|Name of the stream where the logs will be written.|`STDOUT`|
|`ROARR_BUFFER_SIZE`|Number|Configures the buffer size. Buffer is used to store messages before printing them to the stdout/ stderr. Recommended buffer size depends on how often program produces logs. Experiment with values 1024, 2048, 4096 and 8192.|`0` (disabled)|

@@ -434,7 +464,5 @@ When using `ROARR_STREAM=STDERR`, use [`3>&1 1>&2 2>&3 3>&-`](https://stackoverflow.com/a/2381643/368691) to pipe stderr output.

|`application`|Name of the application (do not use in code intended for distribution; see `package` property instead).|
|`hostname`|Machine hostname. See `roarr augment --append-hostname` option.|
|`instanceId`|Unique instance ID. Used to distinguish log source in high-concurrency environments. See `roarr augment --append-instance-id` option.|
|`logLevel`|A numeric value indicating the [log level](#log-levels). See [API](#api) for the build-in loggers with a pre-set log-level.|
|`namespace`|Namespace within a package, e.g. function name. Treat the same way that you would construct namespaces when using the [`debug`](https://github.com/visionmedia/debug) package.|
|`package`|Name of the package.|
|`package`|Name of the NPM package.|

@@ -462,3 +490,3 @@ The `roarr pretty-print` [CLI program](#cli-program) is using the context property names suggested in the conventions to pretty-print the logs for the developer inspection purposes.

I recommend to create a file `Logger.js` in the project directory. Use this file to create an child instance of Roarr with context parameters describing the project and the initialisation instance, e.g.
I recommend to create a file `Logger.js` in the project directory. Inside this file create and export a child instance of Roarr with context parameters describing the project and the script instance, e.g.

@@ -482,3 +510,3 @@ ```js

Roarr does not have reserved context property names. However, I encourage use of the conventions. The `roarr pretty-print` [CLI program](#cli-program) is using the context property names suggested in the [conventions](#conventions) to pretty-print the logs for the developer inspection purposes.
Roarr does not have reserved context property names. However, I encourage use of the [conventions](#conventions).

@@ -599,5 +627,5 @@ <a name="roarr-recipes"></a>

If your package is using Roarr, include instructions to README.md describing how to enable logging, e.g.
If your package is using Roarr, include instructions in `README.md` describing how to enable logging, e.g.
```markdown
```md
## Logging

@@ -604,0 +632,0 @@ 

dist/config.js
dist/config.js.flow
dist/config.js.map
dist/factories/createWriter.js
dist/factories/createWriter.js.flow
dist/factories/createWriter.js.map
dist/factories/createLogger.js.flow

Sorry, the diff of this file is not supported yet

dist/factories/createLogger.js.map

Sorry, the diff of this file is not supported yet

dist/factories/createRoarrInititialGlobalState.js.flow

Sorry, the diff of this file is not supported yet

dist/factories/createRoarrInititialGlobalState.js.map

Sorry, the diff of this file is not supported yet

dist/log.js.flow

Sorry, the diff of this file is not supported yet

dist/log.js.map

Sorry, the diff of this file is not supported yet

dist/types.js.flow

Sorry, the diff of this file is not supported yet

LICENSE

Sorry, the diff of this file is not supported yet

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog

About

Packages

npm

Go

Maven

PyPI

Rubygems

Stay in touch

Get open source security insights delivered straight into your inbox.

  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc