Origami Frontend Components & Services

JSDoc: o-errors

module:oErrors

The oErrors error tracking and reporting module.

Links

module:oErrors

Property

Type

  • Errors

A constructed object, this module is a Singleton due to the architecture of Raven JS. See [Errors](#Errors) for the publicly available interface.

Links

initialised

Global Property

Type

  • bool

The initialised state of the object.

Links

new Logger(logSize, logLevel)

Create a new Logger class. Used internally by [Errors](#Errors).

parameter type default description
logSize Number The default, fixed size of the log buffer.
logLevel String The default log level, see the enumeration {@link Logger.level} for valid values, expects a String corresponding to a log level name.

Properties

  • level - (type: Number) Describes the logging levels available

Links

new Errors

Methods

  • init(...) - (instance) Initialises the Error object with a Raven dependency. All options are optional, if a configuration option is missing, the module will try to initialise using any configuration found in the DOM using the script config tag.
  • report(error, context) - (instance) Report an Error object to the error aggregator.
  • error(message) - (instance) Log an 'ERROR' level log. Intended to have the same semantics as console.error. This.stores the log in memory and will attach the last `n` log lines to the context of any reported errors. See [Errors#log](#Errors#log) to log a log message.
  • warn(warnMessage) - (instance) Log a 'WARN' level log. Intended to have the same semantics as console.warn. This stores the log in memory and will attach the last `n` log lines to the context of the error. See [Errors#log](#Errors#log) to log a log message.
  • log(logMessage) - (instance) Log a 'LOG' level log. Intended to have the same semantics as console.log. This stores the log in memory and will attach the last `n` log lines to the context of the error. See [Errors#warn](#Errors#warn) to log a warn message.
  • wrap(fn) - (instance) Wrap a function so that any uncaught errors are caught and reported to the error aggregator.
  • wrapWithContext(context, fn) - (instance) Wrap a function so that any uncaught errors are caught and reported to the error aggregator. This method allows additional context to be attached to the error if it occurs.
  • destroy - (instance) Remove the `oErrors.log` event listener and clean up as much of the Raven client as possible. Errors is unusable after a call to destroy and calling `init` subsequently will fail.

Links

Logger.level

Static Property

Type

  • Number

Describes the logging levels available

Links

Logger.level.off

Static Property

Type

  • Number

No logging at all occurs, each call to errors.log or errors.log are no-ops

Links

Logger.level.contextonly

Static Property

Type

  • Number

Logs are stored in a buffer, by default the last 10 lines. When an error occurs, these log lines are attached to the error object.

Links

Logger.level.debug

Static Property

Type

  • Number

Logs are stored in the buffer as with `contextonly` however, they are also passed through to the relevant `console.*` API.

Links

Logger.level.consoleonly

Static Property

Type

  • Number

Logging only occurs in the console. Raven client is not initialised.

Links

Errors#init(...)

Instance Method

Initialises the Error object with a Raven dependency.

All options are optional, if a configuration option is missing, the module will try to initialise using any configuration found in the DOM using the script config tag.

parameter type default description
options Object Optional, configuration options object
options.sentryEndpoint string Optional if configued via the DOM, Required if not, must be a valid {@link https://app.getsentry.com/docs/platforms/|Sentry DSN}.
options.siteVersion string Optional, optionally the version of the code the page is running. This tags each error with the code version
options.environment string Optional, track the environment name inside Sentry.
options.logLevel string Optional, see {@link Logger.level} for valid names
options.disabled boolean Optional, If `true`, disable o-errors reporting.
options.buffer Array Optional, pre-existing buffer of error events to flush.
raven Object The Raven JS client object.

Returns

  • Errors - - The Errors instance

Example

<!-- DOM configuration settings -->
<script type="application/json" data-o-errors-config>
{
  "sentryEndpoint": "https://dsn@app.getsentry.com/123"
}
</script>

Links

Errors#report(error, context)

Instance Method

Report an Error object to the error aggregator.

parameter type default description
error Error The error object to report.
context Object Optional context to attach to the Error in the aggregator

Returns

  • Error - - The passed in error

Examples

Example #1

// Reports a caught Error generated by the Promise
fetch('example.com').then(doSomething).catch(oErrors.report);

Example #2

// Reports and re-throws the caught error
try {
  doSomething();
} catch(e) {
  throw oErrors.report(e);
}

Links

Errors#error(message)

Instance Method

Log an 'ERROR' level log. Intended to have the same semantics as console.error.

This.stores the log in memory and will attach the last n log lines to the context of any reported errors. See Errors#log to log a log message.

parameter type default description
message String The message to log

Returns

  • undefined - - undefined

Links

Errors#warn(warnMessage)

Instance Method

Log a 'WARN' level log. Intended to have the same semantics as console.warn. This stores the log in memory and will attach the last n log lines to the context of the error. See Errors#log to log a log message.

parameter type default description
warnMessage String The message to log.

Returns

  • undefined - - undefined

Links

Errors#log(logMessage)

Instance Method

Log a 'LOG' level log. Intended to have the same semantics as console.log. This stores the log in memory and will attach the last n log lines to the context of the error. See Errors#warn to log a warn message.

parameter type default description
logMessage String The message to log.

Returns

  • undefined - - undefined

Links

Errors#wrap(fn)

Instance Method

Wrap a function so that any uncaught errors are caught and reported to the error aggregator.

parameter type default description
fn function The function to wrap.

Returns

  • function - - Wrapped function

Example

// Wraps function, any errors occurring within the function are caught, logged, and rethrown.
let wrappedFunction = oErrors.wrap(function() {
  throw new Error("My Error");
});

If you want to attach additional contextual information to the error, see
{@link Errors#wrapWithContext}.
 -

Links

Errors#wrapWithContext(context, fn)

Instance Method

Wrap a function so that any uncaught errors are caught and reported to the error aggregator. This method allows additional context to be attached to the error if it occurs.

parameter type default description
context Object Additional context to report along with the error if the function `fn` throws an Error.
fn function The function to wrap

Returns

  • function - - Wrapped function with context

Example

// Wrap a function with some additional context to be reported in the event
// `doSomethingCallback` throws an error.
setTimeout(oErrors.wrapWithContext({ "context:url": "example.com" }, doSomethingCallback), 1000);

Links

Errors#destroy

Instance Method

Remove the oErrors.log event listener and clean up as much of the Raven client as possible.

Errors is unusable after a call to destroy and calling init subsequently will fail.

Returns

  • undefined - - undefined

Links

module:oErrors

The oErrors error tracking and reporting module.

Links

Switch component view

GitHub Repository

Install o-errors

If using the Build Service, add o-errors@^3.6.2 to your script tag.

If running a Manual Build, run bower install --save "o-errors@^3.6.2".

Help & Support

o-errors is maintained directly by the Origami team. If you have any questions about o-errors or Origami in general, we are happy to help. 😊

Slack: #ft-origami
Email: origami.support@ft.com

Feedback / Issues

To report a bug or request features please create an issue on Github. For support or general feedback please get in touch 😊

Slack: #ft-origami
Email: origami.support@ft.com