diff --git a/docs/agent-api.asciidoc b/docs/agent-api.asciidoc index 175dc3bc91..332ac36c69 100644 --- a/docs/agent-api.asciidoc +++ b/docs/agent-api.asciidoc @@ -34,12 +34,7 @@ you can simply require `elastic-apm-node` to access the already started singleto You therefore don't need to manage or pass around the started `Agent` yourself. [[apm-start]] -==== `apm.start()` - -[source,js] ----- -apm.start([options]) ----- +==== `apm.start([options])` Starts the Elastic APM agent for Node.js and returns itself. @@ -59,10 +54,7 @@ See the <> for available options. [[apm-is-started]] ==== `apm.isStarted()` -[source,js] ----- -apm.isStarted() ----- +[small]#Added in: v1.5.0# Use `isStarted()` to check if the agent has already started. Returns `true` if the agent has started, @@ -73,23 +65,20 @@ otherwise returns `false`. [small]#Added in: v2.8.0# -* `options` +{type-object}+ +* `options` +{type-object}+ The following options are supported: ** `name` +{type-string}+ Framework name. ** `version` +{type-string}+ Framework version. ** `overwrite` +{type-boolean}+ If set to `false`, the <> and <> provided as <> will not be overwritten. - **Default:** `true`. + *Default:* `true`. Set or change the <> or <> after the agent has started. These config options can also be provided as part of the <>. [[apm-add-filter]] -==== `apm.addFilter()` +==== `apm.addFilter(callback)` -[source,js] ----- -apm.addFilter(callback) ----- +// [small]#Added in: # Use `addFilter()` to supply a filter function. @@ -131,55 +120,42 @@ Though you can also use filter functions to add new contextual information to th it's recommended that you use <> and <> for that purpose. [[apm-add-error-filter]] -==== `apm.addErrorFilter()` +==== `apm.addErrorFilter(callback)` -[source,js] ----- -apm.addErrorFilter(callback) ----- +// [small]#Added in: # Similar to <>, but the `callback` will only be called with error payloads. [[apm-add-transaction-filter]] -==== `apm.addTransactionFilter()` +==== `apm.addTransactionFilter(callback)` -[source,js] ----- -apm.addTransactionFilter(callback) ----- +// [small]#Added in: # Similar to <>, but the `callback` will only be called with transaction payloads. [[apm-add-span-filter]] -==== `apm.addSpanFilter()` +==== `apm.addSpanFilter(callback)` -[source,js] ----- -apm.addSpanFilter(callback) ----- +// [small]#Added in: # Similar to <>, but the `callback` will only be called with span payloads. [[apm-set-user-context]] -==== `apm.setUserContext()` +==== `apm.setUserContext(context)` -[source,js] ----- -apm.setUserContext(context) ----- +[small]#Added in: 0.1.0# + +* `context` +{type-object}+ Accepts the following optional properties: +** `id` +{type-string}+ | +{type-number}+ The user's ID. +** `username` +{type-string}+ The user's username. +** `email` +{type-string}+ The user's e-mail. Call this to enrich collected performance data and errors with information about the user/client. This function can be called at any point during the request/response life cycle (i.e. while a transaction is active). -The given `context` argument must be an object and can contain the following properties (all optional): - -* `id` - The user's ID -* `username` - The user's username -* `email` - The user's e-mail - The given `context` will be added to the active transaction. If no active transaction can be found, `false` is returned. @@ -195,20 +171,17 @@ and any custom context given as the 2nd argument to <> takes precedence and is shallow merged on top. [[apm-set-tag]] -==== `apm.setTag()` +==== `apm.setTag(name, value)` -[source,js] ----- -apm.setTag(name, value) ----- +// [small]#Added in: # + +* `name` +{type-string}+ +Any periods (`.`), asterisks (`*`), or double quotation marks (`"`) will be replaced by underscores (`_`), +as those characters have special meaning in Elasticsearch +* `value` +{type-string}+ +If a non-string data type is given, +it's converted to a string before being sent to the APM Server Set a tag on the current transaction. You can set multiple tags on the same transaction. @@ -236,23 +213,20 @@ it will also get tagged with the same tags. Tags are key/value pairs that are indexed by Elasticsearch and therefore searchable (as opposed to data set via <>). -Arguments: -* `name` - Any string. +[[apm-add-tags]] +==== `apm.addTags({ [name]: value })` + +[small]#Added in: v1.5.0# + +* `tags` +{type-object}+ Contains key/value pairs: +** `name` +{type-string}+ Any periods (`.`), asterisks (`*`), or double quotation marks (`"`) will be replaced by underscores (`_`), as those characters have special meaning in Elasticsearch -* `value` - Any string. +** `value` +{type-string}+ If a non-string data type is given, it's converted to a string before being sent to the APM Server -[[apm-add-tags]] -==== `apm.addTags()` - -[source,js] ----- -apm.addTags({ [name]: value }) ----- - Add several tags on the current transaction. You can add tags multiple times. If an error happens during the current transaction, @@ -260,47 +234,25 @@ it will also get tagged with the same tags. Tags are key/value pairs that are indexed by Elasticsearch and therefore searchable (as opposed to data set via <>). -Arguments: - -* `tags` - An object containing key/value pairs each representing tag `name` and tag `value`: -** `name` - Any string. -Any periods (`.`), asterisks (`*`), or double quotation marks (`"`) will be replaced by underscores (`_`), -as those characters have special meaning in Elasticsearch -** `value` - Any string. -If a non-string data type is given, -it's converted to a string before being sent to the APM Server - [[apm-capture-error]] -==== `apm.captureError()` +==== `apm.captureError(error[, options][, callback])` -[source,js] ----- -apm.captureError(error[, options][, callback]) ----- +// [small]#Added in: # -Send an error to the APM Server: - -[source,js] ----- -apm.captureError(new Error('boom!')) ----- - -Arguments: - -* `error` - Can be either an `Error` object, +* `error` - Can be either an +{type-error}+ object, a <>, or a <> -* `options` - The following options are supported: +* `options` +{type-object}+ The following options are supported: -** `timestamp` - The time when the error happended. +** `timestamp` +{type-number}+ The time when the error happened. Must be a Unix Time Stamp representing the number of milliseconds since January 1, 1970, 00:00:00 UTC. Sub-millisecond precision can be achieved using decimals. If not provided, the current time will be used -** `message` - If the `error` argument is an error object, -is's possible to use this option to supply an additional message string that will be stored along with the error message under `log.message` +** `message` - If the `error` argument is an +{type-error}+ object, +it's possible to use this option to supply an additional message string that will be stored along with the error message under `log.message` ** `user` - See <> for details about this option @@ -310,6 +262,13 @@ is's possible to use this option to supply an additional message string that wil It will receive an `Error` instance if the agent failed to send the error, and the id of the captured error +Send an error to the APM Server: + +[source,js] +---- +apm.captureError(new Error('boom!')) +---- + [[message-strings]] ===== Message strings @@ -420,10 +379,7 @@ In which case it will automate this processes for you. [[apm-middleware-connect]] ==== `apm.middleware.connect()` -[source,js] ----- -apm.middleware.connect() ----- +// [small]#Added in: # Returns a middleware function used to collect and send errors to the APM Server. @@ -452,34 +408,29 @@ app.listen(3000) NOTE: `apm.middleware.connect` _must_ be added to the middleware stack _before_ any other error handling middleware functions or there's a chance that the error will never get to the agent. [[apm-start-transaction]] -==== `apm.startTransaction()` +==== `apm.startTransaction([name][, type][, options])` -[source,js] ----- -var transaction = apm.startTransaction([name][, type][, options]) ----- +// [small]#Added in: # -Start a new transaction. - -Arguments: - -* `name` - The name of the transaction (string). +* `name` +{type-string}+ The name of the transaction. You can always set this later via <> or <>. -Defaults to `unnamed` +*Default:* `unnamed` -* `type` - The type of transaction (string). +* `type` +{type-string}+ The type of transaction. You can always set this later via <>. -Defaults to `custom` +*Default:* `custom` -* `options` - The following options are supported: +* `options` +{type-object}+ The following options are supported: -** `startTime` - The time when the transaction started. +** `startTime` +{type-number}+ The time when the transaction started. Must be a Unix Time Stamp representing the number of milliseconds since January 1, 1970, 00:00:00 UTC. Sub-millisecond precision can be achieved using decimals. If not provided, the current time will be used -** `childOf` - The traceparent header received from a remote service (string) +** `childOf` +{type-string}+ The traceparent header received from a remote service. + +Start a new transaction. Use this function to create a custom transaction. Note that the agent will do this for you automatically whenever your application receives an incoming HTTP request. @@ -492,10 +443,17 @@ See the <> docs for details on how to use custo [[apm-end-transaction]] ==== `apm.endTransaction([result][, endTime])` -[source,js] ----- -apm.endTransaction([result][, endTime]) ----- +// [small]#Added in: # + +* `result` +{type-string}+ Describes the result of the transaction. +This is typically the HTTP status code, +or e.g. "success" or "failure" for a background task + +* `endTime` +{type-number}+ The time when the transaction ended. +Must be a Unix Time Stamp representing the number of milliseconds since January 1, 1970, 00:00:00 UTC. +Sub-millisecond precision can be achieved using decimals. +If not provided, +the current time will be used Ends the active transaction. If no transaction is currently active, @@ -506,25 +464,10 @@ You only need to use this function to end custom transactions created by <> directly on an active transaction object. -Arguments: - -* `result` - A string describing the result of the transaction. -This is typically the HTTP status code, -or e.g. "success" or "failure" for a background task - -* `endTime` - The time when the transaction ended. -Must be a Unix Time Stamp representing the number of milliseconds since January 1, 1970, 00:00:00 UTC. -Sub-millisecond precision can be achieved using decimals. -If not provided, -the current time will be used - [[apm-current-transaction]] ==== `apm.currentTransaction` -[[source,js]] ----- -var transaction = apm.currentTransaction ----- +// [small]#Added in: # Get the currently active transaction, if used within the context of a transaction. @@ -535,10 +478,7 @@ NOTE: If there's no active transaction available, [[apm-current-span]] ==== `apm.currentSpan` -[source,js] ----- -var span = apm.currentSpan ----- +// [small]#Added in: # Get the currently active span, if used within the context of a span. @@ -547,15 +487,11 @@ NOTE: If there's no active span available, `null` will be returned. [[apm-set-transaction-name]] -==== `apm.setTransactionName()` +==== `apm.setTransactionName(name)` -[source,js] ----- -apm.setTransactionName(name) ----- +// [small]#Added in: # -Set or overwrite the name of the current transaction. -The `name` argument must be a string. +* `name` +{type-string}+ Set or overwrite the name of the current transaction. If you use a supported router/framework the agent will automatically set the transaction name for you. @@ -567,34 +503,29 @@ Read more about naming routes manually in the <>. -Defaults to `unnamed` +*Default:* `unnamed` -* `type` - The type of span (string). +* `type` +{type-string}+ The type of span. You can alternatively set this via <>. -Defaults to `custom.code` +*Default:* `custom.code` -* `options` - The following options are supported: +* `options` +{type-object}+ The following options are supported: -** `startTime` - The time when the span started. +** `startTime` +{type-number}+ The time when the span started. Must be a Unix Time Stamp representing the number of milliseconds since January 1, 1970, 00:00:00 UTC. Sub-millisecond precision can be achieved using decimals. If not provided, the current time will be used +Start and return a new custom span associated with the current active transaction. +This is the same as getting the current transaction with `apm.currentTransaction` and, +if a transaction was found, +calling `transaction.startSpan(name, type, options)` on it. + When a span is started it will measure the time until <> is called. See <> docs for details on how to use custom spans. @@ -603,12 +534,9 @@ NOTE: If there's no active transaction available, `null` will be returned. [[apm-handle-uncaught-exceptions]] -==== `apm.handleUncaughtExceptions()` +==== `apm.handleUncaughtExceptions([callback])` -[source,js] ----- -apm.handleUncaughtExceptions([callback]) ----- +// [small]#Added in: # By default, the agent will terminate the Node.js process when an uncaught exception is detected. Use this function if you need to run any custom code before the process is terminated. @@ -623,7 +551,7 @@ apm.handleUncaughtExceptions(function (err) { The callback is called *after* the event has been sent to the APM Server with the following arguments: -* `err` - the captured exception +* `err` +{type-error}+ the captured exception This function will also enable the uncaught exception handler if it was disabled using the <> configuration option. @@ -637,6 +565,8 @@ remember to terminate the node process. [[apm-flush]] ==== `apm.flush([callback])` +[small]#Added in: v0.12.0# + [source,js] ---- apm.flush(function (err) { @@ -654,6 +584,8 @@ The callback is called even if no HTTP request is currently active. [[apm-lambda]] ==== `apm.lambda([type, ] handler)` +// [small]#Added in: # + [source,js] ---- exports.hello = apm.lambda(function (payload, context, callback) { @@ -670,21 +602,21 @@ Read more lambda support in the <> article. [[apm-add-patch]] ==== `apm.addPatch(name, handler)` -Register a module patch to apply on intercepted `require` calls. - -Arguments: +[small]#Added in: 2.7.0# -* `name` - string +* `name` +{type-string}+ Name of module to apply the patch to, when required. -* `handler` - function or string +* `handler` +{type-function}+ | +{type-string}+ Must be a patch function or a path to a module exporting a patch function -** `exports` - The original export object of the module +** `exports` +{type-object}+ The original export object of the module ** `agent` - The agent instance to use in the patch function -** `options` - The following options are supported: -*** `version` - The module version, if applicable. -*** `enabled` - A flag indicating if the instrumentation is enabled. +** `options` +{type-object}+ The following options are supported: +*** `version` +{type-string}+ | +{type-undefined}+ The module version, if applicable. +*** `enabled` +{type-boolean}+ A flag indicating if the instrumentation is enabled. Any module patch can be disabled, by module name, with <>. +Register a module patch to apply on intercepted `require` calls. + A module can have any number of patches and will be applied in the order they are added. [source,js] @@ -710,6 +642,8 @@ apm.addPatch('timers', './timer-patch') [[apm-remove-patch]] ==== `apm.removePatch(name, handler)` +[small]#Added in: 2.7.0# + Removes a module patch. This will generally only be needed when replacing an existing patch. To _disable_ instrumentation while keeping context propagation support, see <>. @@ -726,6 +660,8 @@ apm.removePatch('timers', timerPatchFunction) [[apm-clear-patches]] ==== `apm.clearPatches(name)` +[small]#Added in: 2.7.0# + Clear all patches for the given module. This will generally only be needed when replacing an existing patch. To _disable_ instrumentation while keeping context propagation support, see <>. diff --git a/docs/index.asciidoc b/docs/index.asciidoc index 41a412af0a..60efad01e2 100644 --- a/docs/index.asciidoc +++ b/docs/index.asciidoc @@ -2,9 +2,13 @@ :server-branch: 6.5 include::{asciidoc-dir}/../../shared/attributes.asciidoc[] -:type-string: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type[``] -:type-boolean: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type[``] -:type-object: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object[``] +:type-string: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type[] +:type-boolean: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type[] +:type-object: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object[] +:type-number: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type[] +:type-function: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function[] +:type-error: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error[] +:type-undefined: https://developer.mozilla.org/en-US/docs/Glossary/Undefined[] ifdef::env-github[] NOTE: For the best reading experience, diff --git a/docs/span-api.asciidoc b/docs/span-api.asciidoc index 8fa22635d8..7c502fb1ba 100644 --- a/docs/span-api.asciidoc +++ b/docs/span-api.asciidoc @@ -28,8 +28,7 @@ All spans belong to a transaction. [[span-name]] ==== `span.name` -* *Type:* String -* *Default:* `unnamed` +* +{type-string}+ *Default:* `unnamed` The name of the span. This can also be set via <>. @@ -37,8 +36,7 @@ This can also be set via <>. [[span-type]] ==== `span.type` -* *Type:* String -* *Default:* `custom` +* +{type-string}+ *Default:* `custom` The type of span. This can also be set via <>. @@ -53,62 +51,47 @@ the following are standardized across all Elastic APM agents: `app`, `db`, `cache`, `template`, and `ext`. [[span-set-tag]] -==== `span.setTag()` +==== `span.setTag(name, value)` -[source,js] ----- -span.setTag(name, value) ----- +// [small]#Added in: # -Set a tag on the span. -You can set multiple tags on the same span. - -Arguments: - -* `name` - Any string. +* `name` +{type-string}+ Periods (`.`), asterisks (`*`), and double quotation marks (`"`) will be replaced by underscores (`_`), as those characters have special meaning in Elasticsearch -* `value` - Any string. +* `value` +{type-string}+ If a non-string data type is given, it's converted to a string before being sent to the APM Server -[[span-add-tags]] -==== `span.addTags()` - -[source,js] ----- -apm.addTags({ [name]: value }) ----- +Set a tag on the span. +You can set multiple tags on the same span. -Add several tags on the span. -You can add tags multiple times. +[[span-add-tags]] +==== `span.addTags({ [name]: value })` -Arguments: +// [small]#Added in: # -* `tags` - An object containing key/value pairs each representing tag `name` and tag `value`: -** `name` - Any string. +* `tags` +{type-object}+ Contains key/value pairs: +** `name` +{type-string}+ Any periods (`.`), asterisks (`*`), or double quotation marks (`"`) will be replaced by underscores (`_`), as those characters have special meaning in Elasticsearch -** `value` - Any string. +** `value` +{type-string}+ If a non-string data type is given, it's converted to a string before being sent to the APM Server -[[span-end]] -==== `span.end()` - -[source,js] ----- -span.end([endTime]) ----- +Add several tags on the span. +You can add tags multiple times. -End the span. -If the span has already ended, -nothing happens. +[[span-end]] +==== `span.end([endTime])` -Arguments: +// [small]#Added in: # -* `endTime` - The time when the span ended. +* `endTime` +{type-number}+ The time when the span ended. Must be a Unix Time Stamp representing the number of milliseconds since January 1, 1970, 00:00:00 UTC. Sub-millisecond precision can be achieved using decimals. If not provided, the current time will be used + +End the span. +If the span has already ended, +nothing happens. \ No newline at end of file diff --git a/docs/transaction-api.asciidoc b/docs/transaction-api.asciidoc index 2e51290fd0..926cacea98 100644 --- a/docs/transaction-api.asciidoc +++ b/docs/transaction-api.asciidoc @@ -18,8 +18,7 @@ see the <> article. [[transaction-name]] ==== `transaction.name` -* *Type:* String -* *Default:* `unnamed` +* +{type-string}+ *Default:* `unnamed` The name of the transaction. @@ -32,8 +31,7 @@ Transactions with the same name and <> are grouped togeth [[transaction-type]] ==== `transaction.type` -* *Type:* String -* *Default:* `custom` +* +{type-string}+ *Default:* `custom` The type of the transaction. @@ -42,8 +40,7 @@ There's a special type called `request` which is used by the agent for the trans [[transaction-result]] ==== `transaction.result` -* *Type:* String -* *Default:* `success` +* +{type-string}+ *Default:* `success` A string describing the result of the transaction. This is typically the HTTP status code, @@ -52,42 +49,40 @@ or e.g. "success" or "failure" for a background task. [[transaction-start-span]] ==== `transaction.startSpan([name][, type][, options])` -[source,js] ----- -var span = transaction.startSpan('My custom span') ----- - -Start and return a new custom span associated with this transaction. - -Arguments: +// [small]#Added in: # -* `name` - The name of the span (string). +* `name` +{type-string}+ The name of the span. You can alternatively set this via <>. -Defaults to `unnamed` +*Default:* `unnamed` -* `type` - The type of span (string). +* `type` +{type-string}+ The type of span. You can alternatively set this via <>. -Defaults to `custom` +*Default:* `custom` * `options` - The following options are supported: -** `startTime` - The time when the span started. +** `startTime` +{type-number}+ The time when the span started. Must be a Unix Time Stamp representing the number of milliseconds since January 1, 1970, 00:00:00 UTC. Sub-millisecond precision can be achieved using decimals. If not provided, the current time will be used +Start and return a new custom span associated with this transaction. When a span is started it will measure the time until <> is called. See <> docs for details on how to use custom spans. [[transaction-set-tag]] -==== `transaction.setTag()` +==== `transaction.setTag(name, value)` -[source,js] ----- -transaction.setTag(name, value) ----- +// [small]#Added in: # + +* `name` +{type-string}+ +Periods (`.`), asterisks (`*`), and double quotation marks (`"`) will be replaced by underscores (`_`), +as those characters have special meaning in Elasticsearch +* `value` +{type-string}+ +If a non-string data type is given, +it's converted to a string before being sent to the APM Server Set a tag on the transaction. You can set multiple tags on the same transaction. @@ -96,23 +91,19 @@ it will also get tagged with the same tags. Tags are key/value pairs that are indexed by Elasticsearch and therefore searchable (as opposed to data set via <>). -Arguments: +[[transaction-add-tags]] +==== `transaction.addTags({ [name]: value })` -* `name` - Any string. -Periods (`.`), asterisks (`*`), and double quotation marks (`"`) will be replaced by underscores (`_`), +// [small]#Added in: # + +* `tags` +{type-object}+ Contains key/value pairs: +** `name` +{type-string}+ +Any periods (`.`), asterisks (`*`), or double quotation marks (`"`) will be replaced by underscores (`_`), as those characters have special meaning in Elasticsearch -* `value` - Any string. +** `value` +{type-string}+ If a non-string data type is given, it's converted to a string before being sent to the APM Server -[[transaction-add-tags]] -==== `transaction.addTags()` - -[source,js] ----- -apm.addTags({ [name]: value }) ----- - Add several tags on the transaction. You can add tags multiple times. If an error happens during the transaction, @@ -120,25 +111,17 @@ it will also get tagged with the same tags. Tags are key/value pairs that are indexed by Elasticsearch and therefore searchable (as opposed to data set via <>). -Arguments: - -* `tags` - An object containing key/value pairs each representing tag `name` and tag `value`: -** `name` - Any string. -Any periods (`.`), asterisks (`*`), or double quotation marks (`"`) will be replaced by underscores (`_`), -as those characters have special meaning in Elasticsearch -** `value` - Any string. -If a non-string data type is given, -it's converted to a string before being sent to the APM Server - [[transaction-ensure-parent-id]] ==== `transaction.ensureParentId()` -* *Type:* String +[small]#Added in: 2.0.0# + +* +{type-string}+ If the transaction does not already have a parent id, calling this method generates a new parent id, sets it as the parent id of this transaction, -and returns it as a `String`. +and returns it as a +{type-string}+. This enables the correlation of the spans the JavaScript Real User Monitoring (RUM) agent creates for the initial page load with the transaction of the backend service. If your backend service generates the HTML page dynamically, @@ -164,25 +147,20 @@ See the {apm-rum-ref}[JavaScript RUM agent documentation] for more information. [[transaction-end]] ==== `transaction.end([result][, endTime])` -[source,js] ----- -transaction.end([result][, endTime]) ----- - -Ends the transaction. -If the transaction has already ended, -nothing happens. - -Alternatively you can call <> to end the active transaction. - -Arguments: +// [small]#Added in: # -* `result` - A string describing the result of the transaction. +* `result` +{type-string}+ Describes the result of the transaction. This is typically the HTTP status code, or e.g. "success" or "failure" for a background task -* `endTime` - The time when the transaction ended. +* `endTime` +{type-number}+ The time when the transaction ended. Must be a Unix Time Stamp representing the number of milliseconds since January 1, 1970, 00:00:00 UTC. Sub-millisecond precision can be achieved using decimals. If not provided, the current time will be used + +Ends the transaction. +If the transaction has already ended, +nothing happens. + +Alternatively you can call <> to end the active transaction.