Deployment Integrations

Enrich Tracing in Node.js

Manual Instrumentation with Open Tracing

Thundra's Node.js agent automatically traces a broad range of libraries by default when integration is complete. However, if you would like to fine-tune your traces and perform manual instrumentation, then you will need to get a tracer instance with the command thundra.tracer() in your Lambda function.

Using Manual Instrumentation

In your Lambda Handler code, add instrumentation to the operations you want to track. You can do that primarily by placing "spans" around operations of interest and adding log statements to capture useful data relevant to those operations. Below is a simple hello-world example:

Manual instrumentation example
const thundra = require("@thundra/core");
exports.handler = thundra()((event, context,callback) => {
// Get the tracer instance
const tracer = thundra.tracer();
// Manually create a new span to represent some group of operations
const parent = tracer.startSpan('parentSpan');
console.log('Doing some work in the parent span...');
// Create another span under the above span
const child = tracer.startSpan('childSpan');
console.log('In the child span...');
// Finish the innermost span(childSpan)
// You can use OpenTracing compatible span.close() method
// Finish the parentSpan
// This time using the tracer.finishSpan() method provided by Thundra
callback(null, 'Success');

Thundra Specific Methods

Apart from being OpenTracing compatible, Thundra's Node.js agent also provides specific methods to allow easier configuration of Trace Support.


The Thundra tracer provides additional methods beyond those found in the OpenTracing spec.

Below you can see how to obtain an active span via the getActiveSpan method and finish the active span via the finishSpan method.

getActiveSpan() Example
// In your handler
const tracer = thundra.tracer();
const parent = tracer.startSpan('parent');
const child = tracer.startSpan('child', {childOf: parent});
const span = tracer.getActiveSpan(); //return child span as current active span
tracer.finishSpan(); // closes children and active span is parent
tracer.finishSpan(); // closes parent and active span is null

Callback Wrapper

The Thundra tracer provides a wrapper that will wrap your asynchronous callback. The wrapper returns a closure that saves the current active span at the time of callback creation, and then uses the saved active span as a parent span when the callback occurs. In the example below, the Thundra tracer’s wrapper method wraps a callback function with a try/catch statement. It starts a span with the name callback at the beginning and closes the span either before returning or in the case of an error.

Callback Wrapper Example
// In your handler
const tracer = thundra.tracer();
const callback = function() {
console.log('callback called');
const parentSpan = tracer.startSpan('parent');
// Callback is wrapped with span whose parent will be parentSpan which is the current active span
const wrappedCallback = tracer.wrapper('callback', callback);
const doStuff = function(stuff, callback) {
const doStuffSpan = tracer.startSpan(‘doStuff’);
console.log(`Starting doing my ${stuff}`);
doStuff('yoga', wrappedCallback);
// Span tree right now :
// parentSpan
// / \
// callback doStuff
// Span tree without wrapper would be:
// parentSpan
// /
// doStuff
// /
// callback

Offline Debugging

Offline Debugging is supported by Thundra's Node.js agent and allows you to debug your Lambda functions just like you would in an IDE. That means you can see how your functions behave right down to the code level of your function, giving you in-depth monitoring capabilities. This also gives you micro-tracing capability even inside the method. By default, offline debugging behavior is disabled, but you can enable it using environment variables.

Configuration via Environment Variables

To configure the offline debugging feature through environment variables, the traceLineByLine property of thethundra_agent_lambda_trace_instrument_traceableConfig environment variable can be set true.

For example, if you want to enable offline debugging for all methods in the src/user/service.js module using environment variables, the thundra_agent_lambda_trace_instrument_traceableConfig environment variable can be specified as src/user/service.*[traceLineByLine=true].

thundra_agent_lambda_trace_instrument_traceableConfig: src/user/service.*[traceLineByLine=true]

Here src/user/servicepart specifies the file location of your function, and * means offline debugging for all the methods in this file will be enabled. If you want to debug just one function, you can specify its name instead of using wildcard, such as:

thundra_agent_lambda_trace_instrument_traceableConfig: src/user/service.getUser[traceLineByLine=true]

If you need to enable offline debugging for multiple files in different packages, you can specify multiple configurations using the same environment variable key, thundra_agent_lambda_trace_instrument_traceableConfig, as the prefix, such as in the following example:

thundra_agent_lambda_trace_instrument_traceableConfig_1: src/user/service.*[traceLineByLine=true]
thundra_agent_lambda_trace_instrument_traceableConfig_2: src/product/api.*[traceLineByLine=true]

Using with webpack

If you are using webpack with your functions, offline debugging configurations given through environment variables will not work. You can use thundra-webpack-plugin to solve this problem.