RichError objects

[eloytoro]

Motivation

As of today there are two ways of reporting errors to datadog: uncaught errors that are reported by the SDK automatically, or sending them manually by using addError.

These methods are efficient for capturing application errors that occur in the client’s browser. In addition to that our APIs also allow for adding custom attributes to errors to make triaging and filtering easier when using Datadog, however the existing API does not make it easy for customers to add these attributes to the error as it’s being sent.

Case 1: An error is explicitly thrown from the customer’s application.

Take a hypothetical scenario where an error is thrown explicitly by a user-defined function.

function main() {
  // ...
  throw new Error('Something went wrong');
}

This error would show up in datadog (unless caught by the caller). However it does not contain information about what led up to the error. Data such as what parameters were used, or what was in the execution context, will not be automatically added by our SDK

Case 2: An error is thrown by a third party dependency.

Similar to the previous case, but now we know that the error will not carry any additional context, in which case it’s the user’s responsibility to add the additional context.

A potential solution would be to catch the error and throw it again, reporting the error with additional context to datadog. This is cumbersome to do and it can also result in the error being reported twice.

function main() {
  try {
    thirdParty(param);
  } catch (err) {
    addError(err, { param });
    throw err;
  }
}

Changes

Implement a special error class that inherits from Error that allows for attributes to be passed to error instances

Customers could then throw error with context attached to them explicitly without having to do it when the error is being reported.

throw new RichError('ValidationError', 'Error message', { param: 'custom value' });

When a RichError is passed to addError it automatically takes the errorContext attribute from it and adds it to the payload being sent to datadog. This can be done by either:

• Detect that the error object passed is an instance of RichError (which works with inherited classes as well)
• Detect that the error object passed has an errorContext attribute, in which case it will be automatically added to the payload

Testing

• Local
• Staging
• Unit
• End to end

---

I have gone over the contributing documentation.

[bits-bot]

All committers have signed the CLA.

[michaelcretzman]

I see TBD Description. Please let the Docs Team know when this PR is ready for review.

You can notify the Docs Team on the #documentation channel.

[buraizu]

Adding the WIP label to remove from documentation team review queue until the content requested above is provided. Feel free to remove the label when the PR is ready for documentation team review.