diff --git a/docs/agent-api.asciidoc b/docs/agent-api.asciidoc index ec68b8089..66b28ccb5 100644 --- a/docs/agent-api.asciidoc +++ b/docs/agent-api.asciidoc @@ -2,7 +2,7 @@ === `Agent` API -You can access agent API after initializing the agent: +You can access agent API after initializing the agent: [source,js] ---- @@ -45,7 +45,7 @@ The given `context` argument must be an object and can contain the following pro The provided user context is stored under `context.user` in Elasticsearch on both errors and transactions. -It’s possible to call this function multiple times within the scope of the same active transaction. +It’s possible to call this function multiple times within the scope of the same active transaction. For each call, the properties of the context argument are shallow merged with the context previously given. @@ -62,7 +62,7 @@ Call this to enrich collected errors and transactions with any information that The provided custom context is stored under `context.custom` in Elasticsearch on both errors and transactions. -It’s possible to call this function multiple times within the scope of the same active transaction. +It’s possible to call this function multiple times within the scope of the same active transaction. For each call, the properties of the context argument are shallow merged with the context previously given. The given `context` argument must be an object and can contain any property that can be JSON encoded. @@ -153,12 +153,12 @@ Arguments: * `type` - The type of the transaction (string). Defaults to `custom` -* `options` - Options to modify the created transaction (object). +* `options` - Options to modify the created transaction (object). This argument is optional. The following options are supported: ** `managed` - Controls whether the transaction is managed by the agent or not. Defaults to `false`. -Use this method to create a custom transaction. +Use this method to create a custom transaction. By default, custom transactions are not managed by the agent, however, you can start a managed transaction by passing `{ managed: true }` as the `options` argument. @@ -245,13 +245,18 @@ Use this method to get the current active transaction. If there is no active tra [source,js] ---- -apm.captureError(error) +apm.captureError(error, options) ---- Arguments: * `error` - An instance of `Error`. +* `options` - Options to modify the captured error (object). +This argument is optional. The following options are supported: + +** `labels` - Key/value pairs of labels to add to the error. + Use this method to manually send an error to APM Server: [source,js] @@ -276,11 +281,11 @@ Arguments: * `callback` - A callback function to execute once the event is fired. -Use this method to listen for RUM agent internal events. +Use this method to listen for RUM agent internal events. The following events are supported for the transaction lifecycle: -* `transaction:start` event is fired on every transaction start. +* `transaction:start` event is fired on every transaction start. * `transaction:end` event is fired on transaciton end and before it is added to the queue to be sent to APM Server. The callback function for these events receives the corresponding transaction object diff --git a/packages/rum-core/src/error-logging/error-logging.js b/packages/rum-core/src/error-logging/error-logging.js index e149e516b..8f46801dc 100644 --- a/packages/rum-core/src/error-logging/error-logging.js +++ b/packages/rum-core/src/error-logging/error-logging.js @@ -76,7 +76,7 @@ class ErrorLogging { /** * errorEvent = { message, filename, lineno, colno, error } */ - createErrorDataModel(errorEvent) { + createErrorDataModel(errorEvent, options) { const frames = createStackTraces(stackParser, errorEvent) const filteredFrames = filterInvalidFrames(frames) @@ -100,6 +100,10 @@ class ErrorLogging { } } + if (options && typeof options.labels === 'object') { + errorContext.tags = options.labels + } + if (!errorType) { /** * Try to extract type from message formatted like @@ -150,11 +154,11 @@ class ErrorLogging { return truncateModel(ERROR_MODEL, errorObject) } - logErrorEvent(errorEvent) { + logErrorEvent(errorEvent, options) { if (typeof errorEvent === 'undefined') { return } - var errorObject = this.createErrorDataModel(errorEvent) + var errorObject = this.createErrorDataModel(errorEvent, options) if (typeof errorObject.exception.message === 'undefined') { return } @@ -202,14 +206,14 @@ class ErrorLogging { this.logErrorEvent(errorEvent) } - logError(messageOrError) { + logError(messageOrError, options) { let errorEvent = {} if (typeof messageOrError === 'string') { errorEvent.message = messageOrError } else { errorEvent.error = messageOrError } - return this.logErrorEvent(errorEvent) + return this.logErrorEvent(errorEvent, options) } } diff --git a/packages/rum-core/test/error-logging/error-logging.spec.js b/packages/rum-core/test/error-logging/error-logging.spec.js index 6546210ea..f5348d892 100644 --- a/packages/rum-core/test/error-logging/error-logging.spec.js +++ b/packages/rum-core/test/error-logging/error-logging.spec.js @@ -80,7 +80,8 @@ describe('ErrorLogging', function () { error.anObject = obj error.aFunction = function noop() {} error.null = null - errorLogging.logErrorEvent({ error }) + const labels = { severity: 1 } + errorLogging.logErrorEvent({ error }, { labels }) const events = getEvents() expect(events.length).toBe(1) const errorData = events[0][ERRORS] @@ -89,6 +90,7 @@ describe('ErrorLogging', function () { expect(errorData.context.custom.anObject).toBeUndefined() expect(errorData.context.custom.aFunction).toBeUndefined() expect(errorData.context.custom.null).toBeUndefined() + expect(errorData.context.tags.severity).toBe(1) clearQueue() apmServer diff --git a/packages/rum/src/apm-base.js b/packages/rum/src/apm-base.js index 272d6dc4c..205b0c313 100644 --- a/packages/rum/src/apm-base.js +++ b/packages/rum/src/apm-base.js @@ -314,10 +314,10 @@ export default class ApmBase { } } - captureError(error) { + captureError(error, options) { if (this.isEnabled()) { var errorLogging = this.serviceFactory.getService(ERROR_LOGGING) - return errorLogging.logError(error) + return errorLogging.logError(error, options) } }