@jrh-works/log
Combined local and remote logging (via LogDNA) for Node.js applications.
Installation
npm install @jrh-works/log
The Configuration Function
Usage
const configureLogger = require('@jrh-works/log')
Syntax
configureLogger(options)
Arguments
Returns
Exceptions
Throws a standard Error if all configuration options are not present.
The Options Object
| Property | Type | Description |
|---|
| application | String | The name of the application. |
| key | String | The LogDNA API key. |
| mode | String | The mode of the running application (i.e. production). When the mode is set to testing, remote logs are disabled. |
| source | String | The source of the log line. |
| fetch | Function: Fetch (optional) | A fetch implementation to be used for remote requests. Defaults to node-fetch. |
The Factory Function
Usage
const createLogger = require('@jrh-works/log')(options)
const log = createLogger('logger-one')
Syntax
createLogger(name)
Arguments
| Name | Type | Description |
|---|
| name | String | A name which will be prepended to output from this logger. |
Returns
Exceptions
Throws a standard Error if a name is not present.
The Logging Function
Syntax
log(message, [metadata], notes)
Example Usage
const createLogger = require('@jrh-works/log')(options)
const log = createLogger('logger-one')
await log('Hello world!')
Arguments
| Name | Type | Description |
|---|
| message | String | A message to log. |
| metadata | Object (optional) | Metadata to be included in the logging output. |
| notes | Object: Notes (optional) | Notes to append to the log message. |
Returns
| Type | Description |
|---|
| Object: Promise | A preconfigured call to fetch. |
Exceptions
Throws a standard Error if called without a message.
Effects
- Logs will appear in the local console and in LogDNA.
- The log level will be
info.
The Notes Object
| Attribute | Type | Description |
|---|
| note | Boolean | A note to be appended to the log message if the value is true. |
Example Usage
await log('My message.', null, {
'dry run': true,
'limit: 1': true,
'production mode': false
})
// Logs:
// "My message. (dry run, limit: 1)"
Logging Errors
Syntax
log.error(messageOrError, [metadata])
Example Usage
const createLogger = require('@jrh-works/log')(options)
const log = createLogger('logger-two')
await log.error(new Error())
Arguments
| Name | Type | Description |
|---|
| messageOrError | String | Error | An error message or error object to be logged. |
| metadata | Object (optional) | Metadata to be included in the logging output. |
Returns
| Type | Description |
|---|
| Object: Promise | A preconfigured call to fetch. |
Exceptions
Throws a standard Error if no message or error is present.
Effects
- Logs will appear in the local console and in LogDNA.
- When given a string, the error message will be logged with optional metadata.
- When given an error object, the error message will be logged. The error object and stacktrace will be included in the metadata.
- In all cases, the log level will be
error.
Logging HTTP Requests
Usage
const createLogger = require('@jrh-works/log')(options)
// An example serverless function.
module.exports = async (request, response) => {
const log = createLogger('logger-two')
await log.request(request)
}
Syntax
log.request(request)
Arguments
Returns
| Type | Description |
|---|
| Object: Promise | A preconfigured call to fetch. |
Exceptions
Throws a standard Error if no request is present.
Effects
- Logs will appear in the local console and in LogDNA.
- The URL and HTTP method will be logged (
GET /hello) as the message, with the request body as metadata. - The log level will be
info.
Composing Loggers
Syntax
log.append()
Arguments
| Name | Type | Description |
|---|
| name | String | A name which will be added to the previous logger's name. |
Returns
Exceptions
Throws a standard Error if a name is not present.