https://github.com/dynatrace/nodejs-agent-api
Node.js bindings for Dynatrace OneAgent
https://github.com/dynatrace/nodejs-agent-api
data-ingestion
Last synced: 9 months ago
JSON representation
Node.js bindings for Dynatrace OneAgent
- Host: GitHub
- URL: https://github.com/dynatrace/nodejs-agent-api
- Owner: Dynatrace
- License: mit
- Created: 2016-09-12T11:05:23.000Z (about 9 years ago)
- Default Branch: master
- Last Pushed: 2017-02-28T15:00:08.000Z (over 8 years ago)
- Last Synced: 2025-01-25T09:25:25.658Z (10 months ago)
- Topics: data-ingestion
- Language: JavaScript
- Size: 15.6 KB
- Stars: 1
- Watchers: 7
- Forks: 0
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Node.js API for Dynatrace OneAgent
This module provides JavaScript bindings for Node.js applications
monitored with [Dynatrace](https://www.dynatrace.com/technologies/nodejs-monitoring/).
## 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
```js
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
```js
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.
```js
// 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®](https://www.dynatrace.com/en_us/application-performance-management/products/purepath-technology.html) 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:
```js
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.