@dynatrace/agent-api

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

Installation

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

Usage

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;
  }).then(dta.passContext(next)); 
}

router.get('/couchdb', couchMiddleware, (req, res, next) => {
  request.get('https://google.com', (err, result) => {
    res.send('hello');
  });
});

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) {
    console.log(document.name);

    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.

Disclaimer

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

License

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