Thundra

Thundra: Serverless Observability for AWS Lambda

The black box nature of AWS Lambda and other serverless environments means that identifying and fixing performance issues is difficult and time-consuming. Built for straightforward debugging, monitoring, and observability, Thundra provides deep insight into your entire serverless environment. Thundra collects and correlates all your metrics, logs, and traces, allowing you to quickly identify problematic invocations and also analyzes external services associated with that function. With Thundra’s zero overhead and automated instrumentation capabilities, your developers are free to write code without worrying about bulking up their Lambdas or wasting time on chasing black box problems.

Get Started    Discussions

Sampling Support

You can reduce the amount of data that NodeJS agent sends to Thundra Web Console by enabling sampling. You can add built-in sampling rules to Metric and Trace plugin or provide a custom sampler and implement the sampling logic by yourself. You can sample only timed out invocations.
Checkout the example project on github for more examples.

Timed-Out Invocation Sampling

You can decide to send data Thundra only when a Lambda Timeout happens. With timed-out sampling, you can focus on your timed-out invocations. Below code shows how to enable timed-out invocations programmatically.

const config = {
	 sampleTimedOutInvocations: true
};

const thundra = require("@thundra/core");

exports.handler = thundra(config)((event, context, callback) => {
    callback(null, {msg : 'hello world'});    
});

You can also enable timed-out sampling by setting thundra_agent_lambda_sample_timed_out_invocations to true without any code change.

Masking Stack Traces

You can mask the stack traces of errors that Thundra NodeJS agent collects in order to reduce your data usage. You can enable masking of stack traces by setting environment variable thundra_agent_lambda_error_stacktrace_mask to true without any code change.

Composite Sampler

You can combine one or more sampler with the help of Composite Sampler. You can also decide which logical operator(AND, OR) will be used when combining the samplers. You can use Composite Sampler in any plugin. Just give Composite Sampler to the sampler config of one of Thundra Agents plugin configs. Below example shows how to configure a CompositeSampler which combines CountAwareSampler and TimeAwareSampler with an AND operation. CompositeSampler is given to trace plugin.

const thundra = require("@thundra/core");

// Imports
const CompositeSampler = thundra.samplers.CompositeSampler;
const CountAwareSampler = thundra.samplers.CountAwareSampler;
const TimeAwareSampler = thundra.samplers.TimeAwareSampler;
const SamplerCompositionOperator = thundra.samplers.SamplerCompositionOperator;

// Init two separate samplers
const sampler1 = new CountAwareSampler(2); // Samples every 2th.
const sampler2 = new TimeAwareSampler(3000); // Samples every 3 seconds.

// Create a composite sampler with count and time aware and combine them with AND // operator, default is OR

const sampler = new CompositeSampler([sampler1, sampler2], SamplerCompositionOperator.AND)

const compositeConfig = {
    traceConfig: {
        sampler
    },
};

exports.handler = thundra(compositeConfig)((event, context, callback) => {
    callback(null, {msg: event.msg});
});

Metric Sampling

Metric plugin provides three built-in samplers or you can provide your custom or composite sampler.

  • Count Aware Sampler
  • Time Aware Sampler
  • Error Aware Sampler
  • Custom Sampler

Count Aware Sampler

Count Aware Sampler enables sampling metric data with a count frequency. For example, if the count frequency is 50, metric data will be sampled with every 50 lambda invocation. Here is the configuration:

const thundra = require("@thundra/core");

const CountAwareSampler = thundra.samplers.CountAwareSampler;

const config = {
   metricConfig: {
      sampler: new CountAwareSampler(50) // Sample metrics every 50th invocation
    }
};

exports.handler = thundra(config)((event, context, callback) => {
    callback(null, {msg : 'hello world'});    
});

You can update count frequency without re-deploying Lambda functions. After enabling Count Aware Sampler with programmatic config, you can change the count frequency by setting thundra_agent_lambda_sampler_countAware_countFreq environment variable in AWS Lambda.

Time Aware Sampler

Time Aware Sampler enables sampling metric data with a time frequency. For example, if the time frequency is 300 000, metric data will be sampled with every 300 seconds within consecutive lambda invocations. Here is the configuration:

const thundra = require("@thundra/core");

const TimeAwareSampler = thundra.samplers.TimeAwareSampler;

const config = {
   metricConfig: {
      sampler: new TimeAwareSampler(300000) // Sample metrics every 300s
    }
};

exports.handler = thundra(config)((event, context, callback) => {
    callback(null, {msg : 'hello world'});    
});

You can update time-frequency without re-deploying lambda functions. After enabling Time Aware Sampler with programmatic config, you can change the time-frequency by setting thundra_agent_lambda_sampler_timeAware_timeFreq' environment variable in AWS Lambda.

Error Aware Sampler

Error Aware Sampler enables sampling metric data according to the erroneous invocation of the lambda. For example, you want to send metric data only the lambda execution results with an error.

const thundra = require("@thundra/core");

const ErrorAwareSampler = thundra.samplers.ErrorAwareSampler;

const config = {
   metricConfig: {
      sampler: new ErrorAwareSampler() // Sample metrics when Lambda fails
    }
};

exports.handler = thundra(config)((event, context, callback) => {
    callback(null, {msg : 'hello world'});    
});

Custom Sampler

You can implement your custom sampler. A custom sampler is an Object with isSampled function.
isSampled function should return true if you want to send metric data to Thundra and should return false if you do not want to send the data.

const customSamplerConfig = {
   metricConfig: {
        sampler: {
            isSampled: () => {
                // Decide what to do yourself here. return true/false.
                return true;
            }
        }
    }, 
};

const thundra = require("@thundra/core");

exports.handler = thundra(customSamplerConfig)((event, context, callback) => {
    callback(null, {msg : 'hello world'});    
});

Trace Sampling

Trace plugin provides four built-in samplers or you can provide your custom or composite sampler.

  • Duration Aware Sampler
  • Error Aware Sampler
  • Count Aware Sampler
  • Time Aware Sampler
  • Custom Sampler

Duration Aware Sampler

Duration Aware Sampler enables sampling of trace data according to the duration of the lambda. For example, you want to send trace data only if the duration of the lambda is longer than 500 milliseconds. Here is the configuration:

const thundra = require("@thundra/core");

const DurationAwareSampler = thundra.samplers.DurationAwareSampler;

const config = {
   traceConfig: {
      sampler: new DurationAwareSampler() // Sample traces when Lambda fails
    }
};

exports.handler = thundra(config)((event, context, callback) => {
    callback(null, {msg : 'hello world'});    
});

Error Aware Sampler

Error Aware Sampler enables sampling trace data according to the erroneous invocation of the lambda. For example, you want to send trace data only the lambda execution results with an error.

const thundra = require("@thundra/core");

const ErrorAwareSampler = thundra.samplers.ErrorAwareSampler;

const config = {
   traceConfig: {
      sampler: new ErrorAwareSampler() // Sample traces when Lambda fails
    }
};

exports.handler = thundra(config)((event, context, callback) => {
    callback(null, {msg : 'hello world'});    
});

Count Aware Sampler

Count Aware Sampler enables sampling of trace data with a count frequency. For example, if the count frequency is 50, trace data will be sampled with every 50 lambda invocation. Here is the configuration:

const thundra = require("@thundra/core");

const CountAwareSampler = thundra.samplers.CountAwareSampler;

const config = {
   traceConfig: {
      sampler: new CountAwareSampler(50) // Sample traces every 50th invocation
    }
};

exports.handler = thundra(config)((event, context, callback) => {
    callback(null, {msg : 'hello world'});    
});

You can update count frequency without re-deploying Lambda functions. After enabling Count Aware Sampler with programmatic config, you can change the count frequency by setting thundra_agent_lambda_sampler_countAware_countFreq environment variable in AWS Lambda.

Time Aware Sampler

Time Aware Sampler enables sampling of trace data with a time frequency. For example, if the time frequency is 300 000, trace data will be sampled with every 300 seconds within consecutive lambda invocations. Here is the configuration:

const thundra = require("@thundra/core");

const TimeAwareSampler = thundra.samplers.TimeAwareSampler;

const config = {
    traceConfig: {
      sampler: new TimeAwareSampler(300000) // Sample traces every 300s
    }
};

exports.handler = thundra(config)((event, context, callback) => {
    callback(null, {msg : 'hello world'});    
});

You can update time-frequency without re-deploying lambda functions. After enabling Time Aware Sampler with programmatic config, you can change the time-frequency by setting thundra_agent_lambda_sampler_timeAware_timeFreq' environment variable in AWS Lambda.

Custom sampler

You can implement your custom sampler. A custom sampler is an Object with isSampled function.
isSampled function should return true if you want to send trace data to Thundra and should return false if you do not want to send the data.

const customSamplerConfig = {
   traceConfig: {
        sampler: {
            isSampled: (span) => {
                // Decide what to do yourself here. return true/false.
                return true;
            }
        }
    }, 
};

const thundra = require("@thundra/core");

exports.handler = thundra(customSamplerConfig)((event, context, callback) => {
    callback(null, {msg : 'hello world'});    
});

Log Sampling

Log plugin provides three built-in samplers or you can provide your custom or composite sampler.

  • Error Aware Sampler
  • Count Aware Sampler
  • Time Aware Sampler
  • Custom Sampler
  • Log Level Filtering

Error Aware Sampler

Error Aware Sampler enables sampling log data according to the erroneous invocation of the lambda. For example, you want to send log data only the lambda execution results with an error.

const thundra = require("@thundra/core");

const ErrorAwareSampler = thundra.samplers.ErrorAwareSampler;

const config = {
   logConfig: {
      sampler: new ErrorAwareSampler() // Sample logs when Lambda fails
    }
};

exports.handler = thundra(config)((event, context, callback) => {
    callback(null, {msg : 'hello world'});    
});

Count Aware Sampler

Count Aware Sampler enables sampling of log data with a count frequency. For example, if the count frequency is 50, log data will be sampled with every 50 lambda invocation. Here is the configuration:

const thundra = require("@thundra/core");

const CountAwareSampler = thundra.samplers.CountAwareSampler;

const config = {
   logConfig: {
      sampler: new CountAwareSampler(50) // Sample logs every 50th invocation
    }
};

exports.handler = thundra(config)((event, context, callback) => {
    callback(null, {msg : 'hello world'});    
});

You can update count frequency without re-deploying Lambda functions. After enabling Count Aware Sampler with programmatic config, you can change the count frequency by setting thundra_agent_lambda_sampler_countAware_countFreq environment variable in AWS Lambda

Time Aware Sampler

Time Aware Sampler enables sampling of log data with a time frequency. For example, if the time frequency is 300 000, log data will be sampled with every 300 seconds within consecutive lambda invocations. Here is the configuration:

const thundra = require("@thundra/core");

const TimeAwareSampler = thundra.samplers.TimeAwareSampler;

const config = {
    logConfig: {
      sampler: new TimeAwareSampler(300000) // Sample logs every 300s
    }
};

exports.handler = thundra(config)((event, context, callback) => {
    callback(null, {msg : 'hello world'});    
});

You can update time-frequency without re-deploying lambda functions. After enabling Time Aware Sampler with programmatic config, you can change the time-frequency by setting thundra_agent_lambda_sampler_timeAware_timeFreq' environment variable in AWS Lambda.

Custom sampler

You can implement your custom sampler. A custom sampler is an Object with isSampled function.
isSampled function should return true if you want to send trace data to Thundra and should return false if you do not want to send the data.

const customSamplerConfig = {
   logConfig: {
        sampler: {
            isSampled: () => {
                // Decide what to do yourself here. return true/false.
                return true;
            }
        }
    }, 
};

const thundra = require("@thundra/core");

exports.handler = thundra(customSamplerConfig)((event, context, callback) => {
    callback(null, {msg : 'hello world'});    
});

Log Level Filtering

Thundra Log Levels in increasing precedence: Trace, debug, info, warn, error, fatal.
You can set the log level by setting the environment variablethundra_agent_lambda_log_loglevel to one of the following:

  • Trace
  • debug
  • info
  • warn
  • error
  • fatal
  • none

For instance, if thundra_agent_lambda_log_loglevel is debug, only debug and higher precedence logs will be reported. None of the logs lower in precedence will be reported, such as Trace.

Sampling Support


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.