This module provides JavaScript bindings for Node.js applications monitored with Dynatrace.
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.
$ npm install --save @dynatrace/agent-api
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) => {}));
}));
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');
});
});
- 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));
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.
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.
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.