Node.js Agent API Reference

The Node.js Agent APIs includes methods for managing business transactions and exit points in Node.js applications. This topic describes the Node.js Agent API. 

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:  { } [ ] | & ;
  • An 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.

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 appd.startTransaction(transactionInfo)) 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. See Transaction Snapshots for information on when transaction snapshots are generated.

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.

To enable this feature, the analytics settings in the require statement must be set. See "Node.js Agent Settings" in Install the Node.js Agent.

See for Analytics Data Sources for information about AppDynamics Analytics.

Exit Call Management

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_WEBSERVICE"
  • 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.

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

Returns an ExitCall.

Optional 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.

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 an 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