1.2.0 • Public • Published

    Node.js API for Dynatrace OneAgent

    This module provides JavaScript bindings for Node.js applications monitored with Dynatrace.

    What does this module provide?

    The current version provides a method passContext() which passes transactional context through chains of callbacks for new modules that are not yet supported out-of-the-box. Dynatrace supports many technologies out-of-the-box and this module needs to be used only in rare corner cases - so only use this module if transactions seem to be incomplete.

    Quick Start


    $ npm install --save @dynatrace/agent-api


    Example: Regular callbacks

    const dta = require('@dynatrace/agent-api')();
    some.asyncFunction(someParam, dta.passContext(function(err, result) {
       // Context is preserved
       http.get('https://some-api.xyz/service', dta.passContext((res) => {}));

    Example: Express route with couchDB middleware and promises

    const dta = require('@dynatrace/agent-api')();
    function couchMiddleware(req, res, next) {
      couch.get('testdb', '123a3354452ddfa2973ec0a477000f7a').then(dta.passContext(couchCallback), err => {
        if(err) throw err;
    router.get('/couchdb', couchMiddleware, (req, res, next) => {
      request.get('https://google.com', (err, result) => {

    Please Note

    • Make sure that the module is required after Dynatrace agent.
    • Using this module will not cause any errors if no agent is present (e.g. in testing).
    • The wrapping needs to happen call time.
    // This will *NOT* work
    const wrappedFunction = dta.passContext(someFunction);
    some.asyncFunction('someParam', wrappedFunction);
    // This works
    some.asyncFunction('someParam', dta.passContext(someFunction));

    Further Information

    What is transactional context?

    Dynatrace's patented PurePath Technology® captures timing and code level context for all transactions, end-to-end, from user click, across all tiers, to the database of record and back. Technically this means that Dynatrace adds transactional context to any inbound-, outbound- and function call of an application.

    What does this mean for Node.js applications?

    Node.js is single threaded - its control flow is based on events and asynchronous callbacks.

    Let's look at an example for finding a document with mongoDB:

    function callback(err, document) {
        http.get('https://some-api.xyz/service', (res) => {});
          // ^^^                                 °°°°°°°°°°°
          // Asynchronous call                   Asynchronous callback                                            
    collection.findOne({_id: doc_id}, callback);
            // ^^^^^^^                °°°°°°°°
            // Asynchronous call      Asynchronous callback

    After collection.findOne() is executed asynchronously callback() will be called. callback() again contains an asynchronous call http.get() which performs an outbound http request. If there is a current transactional context, Dynatrace will transparently add a header containing a transaction id to this outbound request. The next tier - if instrumented with Dynatrace - will continue this transaction then.

    Without further intervention any transactional context would get lost between asynchronous invocation and a callback.

    Currently the only reliable way to pass over context information to a callback is called 'wrapping'.

    This means: Dynatrace will transparently wrap supported libraries to add context information. For every yet unsupported module passContext() can be used to provide transactional context to callbacks.


    This module is supported by the Dynatrace Innovation Lab. Please use the issue tracker to report any problems or ask questions.


    Licensed under the MIT License. See the LICENSE file for details.


    npm i @dynatrace/agent-api

    DownloadsWeekly Downloads






    Last publish


    • avatar
    • avatar