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

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 page.

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) {
  tracer.error(e);
  throw e;
} finally {
  tracer.end();
  }
}
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
    tracer.end();
  } catch (e) {
    // send error back
    process.send({ error: e.message, id: message.id });

    // set error and end tracer
    tracer.error(e).end();
  }
}
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 view.

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
     tracer.error(err);
    }
    // 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 for Java and C / C++.