Node.js Agent API Reference

This page describes the Node.js Agent API. The Node.js Agent APIs include methods to manage business transactions and exit points in Node.js applications. 

API Call List

Loading the AppDynamics Module

You can use the APIs in your application by adding the appdynamics Node.js module in a require statement, after appd.profile().

var appd = require('appdynamics');
appd.profile({ . . . })
 
...
  
var transaction = appd.startTransaction(...);
...
 

transaction.end();

Basic Business Transaction Management

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. See Node.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);
};

Exit Call Management

exitCall.addAnalyticsData (key, value)

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

Attaches existing Analytics data generated for this transaction to the exit call. 

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. See Node.js Settings Reference.

TimePromise.prototype.startExitCall(exitCallInfo)

• exitCallInfo object

The exitCallInfo object has the following required properties:

• • exitType: string—the type of exit call, one of "EXIT_HTTP", "EXIT_DB", "EXIT_CACHE", "EXIT_RABBITMQ", "EXIT_WEB_SERVICE"
  • label: string—label for the exit call in the AppDynamics UI
  • backendName: string—name of the backend remote system or service
  • identifyingProperties: Object—a hash of name/value pairs uniquely identifying the remote system or service being called. See Backend Identifying Properties.

Creates and starts a custom exit call, described by the exitCallInfo object.

You can supply more identifying properties in addition to the required ones.

Returns an ExitCall. See Exit Call Properties.

{ 
  exitType: “EXIT_DB”,
  label: "New SQL",
  backendName: "NewDB"
  identifyingProperties: {
    “HOST”: “database-server”, 
    “PORT”: “12345”, 
    “DATABASE”: “my-database”, 
    "VENDOR" = “MYSQL"
  },
  …etc...
}

TimePromise.prototype.endExitCall(exitCall, error)

• exitCall: ExitCall instance returned by startExitCall()
• error: any; optional

Ends a custom exit call and attaches it to this transaction.

If an error is passed, the error is associated with the exit call, and the exit call is flagged as being in an error state.

TimePromise.prototype.beforeExitCall(exitCall)

• exitCall: ExitCall

Returns an ExitCall.

Optional callback for modifying an automatically-detected (not custom) exit call.  

The agent invokes this API immediately before your application makes the exit call when you supply a callback function. You can use the callback to:

• Modify the exit call that is reported to the controller.
• Suppress all reporting of the exit call by returning nothing. 
• Capture the exit call to create correlation information for a downstream transaction.

The following is an example of a modify exit call reported to the Controller.

txn.beforeExitCall = function customExitCallHandler(exitCall) {
    // don't report database access for this transaction
    if (exitCall.isSql) return; 
    // customize label for all other exit calls in this transaction
    exitCall.label += " (my custom transaction)";
    return exitCall;
}

TimePromise.prototype.exitCallCompleted(exitCall)

    •    exitCall: ExitCall

Optional. Returns an ExitCall. Callback for modifying either a custom exit call created by startExitCall() or an automatically-detected exit call on completion of the exit call.

The agent invokes this API immediately after an exit call completes when you supply a callback function.

Use exitCallCompleted() to modify how the exit call is reported to the Controller by returning a modified exit call. Do not modify the backend identifying properties using this callback. 

The following code is an example that modifies the exit call reported to the Controller.

txn.exitCallCompleted = function customExitCallPostProcessor(exitCall) {
    // report MongoDB read and write operations as distinct exit calls
    if (exitCall.backendName === "MongoDB")
        exitCall.label += " " + exitCall.category;
}

Transaction Correlation Management

appd.parseCorrelationInfo(source)

• source: String or HttpRequest

Describes the upstream transaction with which to correlate. If a HttpRequest object is passed, it must have a transaction correlation header attached.

On success, returns a CorrelationHeader object that can be used by startTransaction() to create a transaction that is correlated with the upstream transaction described by source. Returns false if source could not be parsed. This can occur if the source is an HTTP request with no correlation header attached or the string parameter is not recognized as a correlation header.

HTTP requests made through the standard http.request() API have correlation information added automatically. You can correlate a custom transaction created in response to an HTTP request made from another Node.js process by passing the incoming request as source.

For other exit call types, you need to define how correlation information is attached to the originating transaction and retrieved in the downstream transaction. 

TimePromise.prototype.createCorrelationInfo(exitCall, doNotResolve)

• exitCall: ExitCall
• doNotResolve: optional, true|false


The input exitCall is one of the following:

• For a custom exit call, value returned from startExitCall().
• For an automatically-detected exit call, input parameter to the beforeExitCall() callback.

Set the doNotResolve parameter to true if you do not want the backend to be resolved to a tier. It defaults to false, which means that the backend is resolved to the calling tier. You may want to set this for an exit call to a service, such as a messaging queue, that does not have a 1:1 relationship between the consumer and producer of the service. For more information see Resolve Remote Services to Tiers.

Returns a string-encoded correlation header, which a downstream transaction can use to correlate with this transaction.

Exit Call Properties

This table describes the properties of the exit call object for each detected exit call type.

A dash (–) in a table cell indicates that the property is present in a discovered exit call but its format is unspecified. This allows you to set your own values when you create custom exit calls.

N/A indicates that the property is not used with that exit call type. Discovered exit calls may have additional properties not documented here.

^* host, port and path; does not include query string.

Backend Identifying Properties

This table lists the identifying properties for the backends that are automatically detected by the Node.js Agent.

In the Controller UI, these properties are visible in the upper right panel of the backend dashboards.

¹ "\n" separated list of server addresses in <host>:<port> format.
² single server address in <host>:<port> format.