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.
You can use the APIs in your application by adding the "appdynamics" Node.js module in a require statement, after appd.profile().
transactionInfo string, HttpRequest, or
transactionInfo parameter can be one of the following:
CorrelationHeaderobject 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.
Re-joins a long-running or asynchronous transaction.
Ends the transaction and reports transaction information to the controller.
error is passed, the error is associated with the transaction and the transaction is flagged as an error transaction.
requestHTTP 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.
statusCodeoptional transaction status code
statusCodeparameter nor an error.statusCode property in the
errorparameter is provided, the status code defaults to 500.
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.
keykey to custom data being added
valuevalue 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.
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.
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.
txn === mytxn. It is passed into the callback so the callback does not need to be defined in the same scope as
keykey to analytics data being added
valuevalue 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.
exitCallInfoobject has the following required properties:
exitType: string — the type of exit call, one of "EXIT_HTTP", "EXIT_DB", "EXIT_CACHE", "EXIT_RABBITMQ", "EXIT_WEBSERVICE"
abel: 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
You can supply more identifying properties in addition to the required ones.
ExitCall. See Exit Call Properties.
ExitCallinstance returned by startExitCall()
Ends a custom exit call and attaches it to this transaction.
error is passed, the error is associated with the exit call, and the exit call is flagged as being in an error state.
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:
• 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.
sourceString or HttpRequest
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
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
For other exit call types, you need to define how correlation information is attached to the originating transaction and retrieved in the downstream transaction.
exitCall is one of the following:
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.
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.
|command||String (URL)*||SQL query executed||SQL query executed||N/A||N/A||N/A|
|commandArgs||N/A||SQL query positional parameters||SQL query positional parameters||N/A||N/A||N/A|
|identifyingProperties||See Backend Identifying Properties and .|
* host, port and path; does not include query string
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.
|Backend Service||Exit Call Type||Identifying Properties|
|HTTP Server||"EXIT_HTTP"||"HOST", "PORT"|
|MySql Server||"EXIT_DB"||"Host", "Port", "Database", "Vendor" = "MYSQL"|
|Postgres Server||"EXIT_DB"||"Host", "Port", "Database", "Vendor" = "POSTGRESQL"|
|MongoDB Server||"EXIT_DB"||"Server Pool"1, "Database", "Vendor" = "MONGODB"|
|Memcached||"EXIT_CACHE"||"EXIT_CACHE" "Server Pool"1|
|Redis Server||"EXIT_CACHE"||"Server Pool"2|
1 "\n" separated list of server addresses in <host>:<port> format