Dynatrace OneAgent SDK for Node.js: Extend end-to-end visibility

综合技术 2018-03-13

Dynatrace provides extensive Node.js monitoring capabilities, including heap and process metrics, heap dumps, CPU sampling, event loop metrics, insights into inbound and outbound HTTP calls and dedicated support for a variety of databases (including query capture). To learn more about Dynatrace out-of-the-box monitoring features for Node.js, check out our blog posts by Daniel Khan on Understanding Garbage Collection and hunting Memory Leaks in Node.js
, Tracking down CPU issues in Node.js
and Understanding the Node.js Event Loop and its Metrics

However, some users are looking for insights into additional frameworks (for example, using remote calls) or additional database systems. This is why Dynatrace has created an SDK that can be hooked into these applications. Beginning with Dynatrace OneAgent v1.137, Dynatrace provides beta support for custom tracing in Node.js applications.

Dynatrace OneAgent SDK for Node.js

To use the OneAgent SDK for Node.js, you’ll have to edit the source code of the Node.js application you want to monitor. The SDK enables you to instrument your application manually. The OneAgent SDK for Node.js currently supports remote call tracing and SQL database request tracing. The feature set will be extended over the coming months.

The best way to get started is by checking out our GitHub repository
. The repository includes the SDK documentation, API description, and two code samples, which are described below.

Once you’ve added the OneAgent SDK for Node.js to your application, you can run it through your pipeline and deploy it. Instrumentation remains dormant and doesn’t impact systems where the Dynatrace OneAgent is not installed. OneAgent automatically detects that your application is instrumented with the SDK and immediately begins monitoring it. A restart of the application is required after OneAgent has been installed on the host.

Integrating the SDK into your application

The OneAgent SDK for Node.js is available on npm
. You can install it by typing:

$ npm install --save @dynatrace/oneagent-sdk

If you want to integrate the OneAgent SDK into your application, just add the following line of code:

const Sdk = require '@dynatrace/oneagent-sdk';

The Dynatrace OneAgent SDK for Node.js has no further dependencies.

Sample sources

In the GitHub repository
, you’ll find two samples that showcase the tracing of remote calls and database calls. Once the services are started on a monitored host, you’ll see them listed on the Transactions & services

Tracing remote calls

The RemoteCall
code sample showcases use of the SDK for implementing incoming and outgoing remote calls. For detailed technical documentation, have a look at the GitHub repository, but here is an example of a simple remote call trace:

On the calling side of the remote call, it looks like this:

async function tracedOutgoingRemoteCall(method, data) {

const tracer = Api.traceOutgoingRemoteCall({

serviceEndpoint: "ChildProcess",

serviceMethod: method,

serviceName: "StringManipulator",

channelType: Sdk.ChannelType.NAMED_PIPE


try {

// start tracer, get dynatrace tag and trigger sending via sendMessage()

return await tracer.start(function sendTaggedMessage() {

// getting a tag from tracer needs to be done after start()

const dtTag = tracer.getDynatraceStringTag();

return sendMessage(method, data, dtTag);


} catch (e) {


throw e;

} finally {




On the server side of the remote call, it looks like this:

async function tracedMessageHandler(message) {

const tracer = Api.traceIncomingRemoteCall({

serviceEndpoint: "ChildProcess",

serviceMethod: message.method,

serviceName: "StringManipulator",

dynatraceTag: message.traceTag, // extract and set the dynatrace tag

protocolName: "Json" // optional


try {

// start tracer and trigger actual message processing via processMessage(message)

const result = await tracer.start(processMessage, message);

// send result calculated by processMessage() back to caller

process.send({ result: result, id: message.id });

// end tracer


} catch (e) {

// send error back

process.send({ error: e.message, id: message.id });

// set error and end tracer




The important thing here is that you need to transport the tag across the wire yourself.

The OneAgent SDK is fully compatible with OneAgent. SDK-instrumented remote calls are shown in the form of RPC services, which behave just like any other service. You get full access to all analysis and monitoring functionality, including Smartscape topology, auto-baselining, and AI-based root cause analysis.

Note that the service StringManipulator
is called by our main program, just as expected. Let’s take a look at the Service flow to get a sense of what’s going on here.

As you can see, OneAgent recorded 44
requests to the service StringManipulator
. From here, we can analyze the individual requests in PurePaths

Tracing database calls

The Database code sample showcases the use of the SDK for implementing database calls for SQL based databases that aren’t automatically detected by OneAgent. Again, for detailed technical documentation, see the GitHub repository, but here is an example of a simple database call trace:

// Static info describing the database

const dbInfo = {

name: dbConfig.database,

vendor: Sdk.DatabaseVendor.MARIADB,

host: dbConfig.host,

port: dbConfig.port


// Issue a traced SQL database request

function tracedSqlDatabaseRequest(sql, clientCb) {

// create a SQL database tracer

const tracer = Api.traceSQLDatabaseRequest(dbInfo, {

statement: sql


// start tracer, calls connection.query(sql, cb) with connection set as this in query()

tracer.startWithContext(connection.query, connection, sql, (err, results, fields) => {

if (err) {

// set the error on the tracer



// end the tracer and call client callback forwarding results

tracer.end(clientCb, err, results, fields);



SDK-instrumented database calls behave just like all other database calls. You get full access to all analysis and monitoring functionality, including auto-baselining and AI-based root cause analysis. The detected database appears in Smartscape topology as well.

Let’s drill down to the database page to see how the database behaves.

As you can see, OneAgent has recorded a 50%
failure rate for the SQL Queries. From here, we can analyze the individual database statements to see which queries are failing.

We’ll add more functionality to the OneAgent SDK for Node.js over the coming months.

Your feedback on the OneAgent SDK for Node.js is most welcome. The best way for you to do this is via our GitHub repository issue tracker
. You can also comment on our roadmap thread in AnswerHub

Prerequisites and Limitations:

  • Dynatrace OneAgent v1.137 or higher
  • Dynatrace OneAgent SDK for Node.js (beta)
  • Dynatrace Managed version 138 or higher/ Dynatrace SaaS is supported.

The One Agent SDK is also available as beta forJava andC / C++.


Avoiding Torn Pages For thePostgres file layout, Postgres reads and writes data to disk 8kb at a time. Most operating systems make use of a smaller page size, such as 4k...
What is node.js excatly? i am new to web sockets and node .. I am confused with different terminologies used with node.js . Few places it's mentioned it's a tool, few ot...
DevOps for Database Refcard #255 DevOps for Database 6 Free .PDF for easy Reference Written by ...
python django Automated testing part 2 Running Test we have learned about tests in the previous lesson now here we can see how to run the test to run the test write...
没想到你是这样的JDBC 本文将介绍 MySQL Client 与 Server 的通信原理,以及 Java JDBC 的工作原理等。什么是JDBC 的 Type4,什么又是 Type 3? 一、 MySQL Client & Server 我们在进行数据库的操作时,总是通过 GUI 数据管理工具,或者命令行...