appd.startTransaction(transactionInfo)

• transactionInfo string, HttpRequest or CorrelationHeader

The transactionInfo parameter can be one of the following:

• A string specifying the name of the custom transaction. The following characters cannot be used in transaction names: { , } , [ , ] , | , & , and ; .
• A HttpRequest object. Normal transaction matching and naming rules are applied, and any included RUM and/or transaction correlation information is picked up automatically.
• A CorrelationHeader object providing information to correlate with a transaction that is upstream to this one. See parseCorrelationInfo().

Creates and starts a custom business transaction and returns a transaction handle as a TimePromise instance, which is used for subsequent operations on this transaction.

TimePromise.prototype.resume()

Re-joins a long-running or asynchronous transaction.

Call resume():

• When a long-running transaction needs to be kept alive beyond the default transaction timeout of five minutes. This prevents the agent from assuming the transaction has failed and then deleting the transaction.
• When the code being instrumented crosses an async boundary. This re-associates the current execution context with the correct transaction and ensures any exit calls performed are charged to the right transaction.

TimePromise.prototype.end(error)

• error: any; optional

Ends the transaction and reports transaction information to the Controller.

If an error is passed, the error is associated with the transaction and the transaction is flagged as an error transaction.

appd.getTransaction(request)

• request: HTTP request object

Returns a handle to the business transaction associated with the specified request, if one exists. If no associated business transaction exists, returns false.

Use appd.getTransaction() to access both custom and automatically detected business transactions.

appd.addAnalyticsData (key, value)

• key: key to custom data being added
• value: value being added for this key

Attaches custom data to Analytics generated for the current transaction. Your application does not require a transaction handle.

To enable this feature, the Analytics settings in the require statement must be set. See Node.js Settings Reference. For information about Analytics, see Analytics Data Sources.

appd.addSnapshotData (key, value)

• key: key to custom data being added
• value: value being added for this key

Attaches custom data to snapshots generated for the current transaction.

addSnapshotData() can be called on a transaction at any time, but the added data is used only when a transaction snapshot is generated. For information on when transaction snapshots are generated, see Troubleshoot Business Transaction Performance with Transaction Snapshots.

The following sample adds session count to USER DATA in the snapshot:

txn.addSnapshotData(“active sessions”, my.api.getSessionCount());

If the data to be added to the snapshot is available after the transaction completes, it can be attached using a txn.onSnapshotCaptured(txn) callback. This technique avoids overhead for collecting the data when no snapshot has been generated. The custom data is exposed in the USER DATA tab of the transaction snapshot details in the Controller UI.

appd.markError(error, [statusCode])

• error: JavaScript error object
• statusCode: optional transaction status code

This value can also be passed as a statusCode property on the error object.

If neither a statusCode parameter nor an error.statusCode property in the error parameter is provided, the status code defaults to 500.

See also TimePromise.prototype.end(error) for another way to attach an error object to a business transaction.

Marks the transaction as an error transaction. The marked transaction is reported as an error transaction and not as a slow, very slow or stalled transaction, even if the transaction was also slow or stalled.

txn.markError(error, [statusCode])

• error JavaScript error object
• statusCode optional transaction status code. This value can also be passed as a statusCode property on the error object.

If neither a statusCode parameter nor an error.statusCode property in the error parameter is provided, the status code defaults to 500.

See also TimePromise.prototype.end(error) for another way to attach an error object to a business transaction.

Marks the transaction as an error transaction. The marked transaction is reported as an error transaction and not as a slow, very slow or stalled transaction, even if the transaction was also slow or stalled.

txn.addSnapshotData(key, value)

• key: key to custom data being added
• value: value being added for this key

Attaches custom data to snapshots generated for this transaction.

addSnapshotData() can be called on a transaction at any time, but the added data is used only when a transaction snapshot is generated. For information on when transaction snapshots are generated, see Troubleshoot Business Transaction Performance with Transaction Snapshots.

The following sample adds session count to USER DATA in the snapshot.

txn.addSnapshotData(“active sessions”, my.api.getSessionCount());

If the data to be added to the snapshot is available after the transaction completes, it can be attached using a txn.onSnapshotCaptured(txn)callback. This technique avoids overhead for collecting the data when no snapshot has been generated. The custom data is exposed in the USER DATA tab of the transaction snapshot details in the Controller UI.

txn.onSnapshotCaptured(txn)

• txn : transaction

Callback method that can be set on a transaction to add custom data to the transaction snapshot. Used with txn.addSnapshotData(key, value).

When the callback function is supplied, the agent invokes this API immediately after capturing a transaction snapshot.

If specified, the callback is invoked on transaction completion, if the transaction triggers a snapshot.

You must define a function to call and assign it to the callback.

mytxn.onSnapshotCaptured = customTitle (txn) {
// get book title for current transaction instance
title = getBookTitle();
txn.addSnapshotData ("book title", title);
}

Note that txn === mytxn. It is passed into the callback so the callback does not need to be defined in the same scope as mytxn.

txn.addAnalyticsData(key, value)

• key: key to analytics data being added
• value: value being added for this key

Attaches custom data to Analytics generated for this transaction. If your application has a transaction handle, you can call txn.addAnalyticsData(key, value). If not, use appd.addAnalyticsData(key, value).

To enable this feature, the Analytics settings in the require statement must be set. SeeNode.js Settings Reference. For more information about Analytics, see Analytics Data Sources.

txn.onResponseComplete(req, res)

• req : HTTP request for the transaction
• res : HTTP response for the transaction

Callback method that can be set on a transaction to be notified when the associated HTTP response has been completed. This can be used with txn.addAnalyticsData(key, value) to add data from response after it is complete, before the transaction completes. When the callback function is supplied, the agent invokes this API immediately after the HTTP response completes, before closing out the transaction. You must define a function to call and assign it to the callback.

mytxn.onResponseComplete = function customTitle (req, res) {
// get status code of HTTP response
code = res.statusCode;
txn.addAnalyticsData ("http response code", code);
};