1 | # Thundra Lambda Node.js Agent
|
2 |
|
3 | [![OpenTracing Badge](https://img.shields.io/badge/OpenTracing-enabled-blue.svg)](http://opentracing.io)
|
4 | [![Coverage Status](https://coveralls.io/repos/github/thundra-io/thundra-lambda-agent-nodejs/badge.svg?branch=master)](https://coveralls.io/github/thundra-io/thundra-lambda-agent-nodejs?branch=master)
|
5 | [![CircleCI](https://circleci.com/gh/thundra-io/thundra-lambda-agent-nodejs.svg?style=svg)](https://circleci.com/gh/thundra-io/thundra-lambda-agent-nodejs)
|
6 |
|
7 | Instrument and profile your AWS lambda functions with zero overhead.
|
8 |
|
9 | Check out [example projects](https://github.com/thundra-io/thundra-examples-lambda-nodejs) for a quick start and [Thundra docs](https://docs.thundra.io/) for more information.
|
10 |
|
11 | ## Installation
|
12 |
|
13 | ```bash
|
14 | npm install @thundra/core --save
|
15 | ```
|
16 |
|
17 | ## Usage
|
18 |
|
19 | Just require this module, pass your api key to it and wrap your handler:
|
20 |
|
21 | ```js
|
22 | const thundra = require("@thundra/core")({ apiKey: "MY_APIKEY" });
|
23 |
|
24 | exports.handler = thundra((event, context,callback) => {
|
25 | callback(null, "Hello Thundra!");
|
26 | });
|
27 | ```
|
28 |
|
29 | Thundra will monitor your AWS lambda function and report automatically!
|
30 |
|
31 | `context.done`, `context.succeed` and `context.fail` are also supported:
|
32 |
|
33 | ```js
|
34 | const thundra = require("@thundra/core")({ apiKey: "MY_APIKEY" });
|
35 |
|
36 | exports.handler = thundra((event, context) => {
|
37 | context.succeed("Hello Thundra!");
|
38 | });
|
39 | ```
|
40 |
|
41 | ## Configuration
|
42 | You can configure Thundra using **environment variables** or **module initialization parameters**.
|
43 |
|
44 | Environment variables have **higher precedence** over initialization parameters.
|
45 |
|
46 | Check out the [configuration part](https://thundra.readme.io/docs/nodejs-configuration) of our docs for more detailed information.
|
47 |
|
48 | #### 1. Environment variables
|
49 |
|
50 | | Name | Type | Default Value |
|
51 | |:------------------------------------------------------------------------ |:------:|:-------------:|
|
52 | | thundra_apiKey | string | - |
|
53 | | thundra_agent_lambda_warmup_warmupAware | bool | false |
|
54 | | thundra_agent_lambda_application_stage | string | empty |
|
55 | | thundra_agent_lambda_application_domainName | string | API |
|
56 | | thundra_agent_lambda_application_className | string | AWS-Lambda |
|
57 | | thundra_agent_lambda_disable | bool | false |
|
58 | | thundra_agent_lambda_timeout_margin | number | 200 |
|
59 | | thundra_agent_lambda_report_rest_baseUrl | string | https<nolink>://api.thundra.io/v1 |
|
60 | | thundra_agent_lambda_report_cloudwatch_enable | bool | false |
|
61 | | thundra_agent_lambda_trace_disable | bool | false |
|
62 | | thundra_agent_lambda_metric_disable | bool | false |
|
63 | | thundra_agent_lambda_log_disable | bool | false |
|
64 | | thundra_agent_lambda_trace_request_skip | bool | false |
|
65 | | thundra_agent_lambda_trace_response_skip | bool | false |
|
66 | | thundra_agent_lambda_trace_instrument_disable | bool | false |
|
67 | | thundra_agent_lambda_trace_instrument_traceableConfig | string | empty |
|
68 | | thundra_agent_lambda_trace_instrument_file_prefix | string | empty |
|
69 | | thundra_agent_lambda_log_loglevel | string | TRACE |
|
70 | | thundra_agent_lambda_integrations | string | empty |
|
71 | | thundra_agent_lambda_debug_enable | bool | false |
|
72 | | thundra_agent_lambda_trace_instrument_integrations_disable | array | [] |
|
73 | | thundra_agent_lambda_sampler_timeAware_timeFreq | number | 300000 |
|
74 | | thundra_agent_lambda_sampler_countAware_countFreq | number | 10 |
|
75 | | thundra_agent_lambda_log_console_shim_disable | bool | false |
|
76 | | thundra_agent_trace_instrument_integrations_spanContext_disable | bool | false |
|
77 | | thundra_agent_lambda_xray_disable | bool | false |
|
78 | | thundra_agent_lambda_trace_span_listener | string | empty |
|
79 | | thundra_agent_lambda_sample_timed_out_invocations | bool | false |
|
80 | | thundra_agent_lambda_trace_integrations_redis_command_mask | bool | false |
|
81 | | thundra_agent_lambda_trace_integrations_rdb_statement_mask | bool | false |
|
82 | | thundra_agent_lambda_trace_integrations_aws_dynamodb_statement_mask | bool | false |
|
83 | | thundra_agent_lambda_trace_integrations_elastic_statement_mask | bool | false |
|
84 | | thundra_agent_lambda_trace_kinesis_request_enable | bool | false |
|
85 | | thundra_agent_lambda_trace_firehose_request_enable | bool | false |
|
86 | | thundra_agent_lambda_trace_cloudwatchlog_request_enable | bool | false |
|
87 | | thundra_agent_lambda_trace_integrations_aws_sns_message_mask | bool | false |
|
88 | | thundra_agent_lambda_trace_integrations_aws_sqs_message_mask | bool | false |
|
89 | | thundra_agent_lambda_trace_integrations_aws_lambda_payload_mask | bool | false |
|
90 | | thundra_agent_lambda_trace_integrations_aws_http_body_mask | bool | false |
|
91 | | thundra_agent_lambda_report_rest_composite_enabled | bool | false |
|
92 | | thundra_agent_lambda_error_stacktrace_mask | bool | false |
|
93 |
|
94 |
|
95 | #### 2. Module initialization parameters
|
96 |
|
97 | | Name | Type | Default Value |
|
98 | |:---------------|:------:|:-------------:|
|
99 | | apiKey | string | - |
|
100 | | disableThundra | bool | false |
|
101 | | plugins | array | [ ] |
|
102 |
|
103 |
|
104 | ## Async Monitoring with Zero Overhead
|
105 | By default, Thundra agent reports by making an HTTPS request. This adds an overhead to your lambda function.
|
106 |
|
107 | Instead, you can [setup async monitoring](https://docs.thundra.io/docs/how-to-setup-async-monitoring) in **2 minutes** and monitor your lambda functions with **zero overhead**!
|
108 |
|
109 | Check out our async monitoring example at our [example projects](https://github.com/thundra-io/thundra-examples-lambda-nodejs) for a quick start.
|
110 |
|
111 |
|
112 | ## Log Support
|
113 | You can monitor your logs using Thundra and enjoy the three pillars of observability in one place!
|
114 |
|
115 | ```js
|
116 | const thundra = require("@thundra/core");
|
117 |
|
118 | const logger = thundra.createLogger();
|
119 |
|
120 | exports.handler = thundra({
|
121 | apiKey: "MY_APIKEY",
|
122 | })((event, context, callback) => {
|
123 | logger.info("Hello %s", "Thundra");
|
124 | callback(null, "Hello Thundra!");
|
125 | });
|
126 | ```
|
127 |
|
128 | You can also set the name of a logger while creating it (default name is `default`):
|
129 |
|
130 | ```js
|
131 | const logger = thundra.createLogger({loggerName: "Bob"});
|
132 | ```
|
133 |
|
134 | Logger's name will be visible in Thundra's trace chart.
|
135 |
|
136 | ## How to use Thundra loggers
|
137 |
|
138 | You can log by two different ways.
|
139 |
|
140 | ### 1. Using `trace`, `debug`, `info`, `warn`, `error`, `fatal` methods
|
141 |
|
142 | All these methods support `printf`-like format. Same as Node's [`util.format`](https://nodejs.org/api/util.html#util_util_format_format_args).
|
143 | ```js
|
144 | const thundra = require("@thundra/core");
|
145 | const logger = thundra.createLogger();
|
146 |
|
147 | logger.trace("Hey, I %s things", "trace");
|
148 | logger.debug("Someone is %s %d"," debugging", 2);
|
149 | logger.info("Get some info","and more");
|
150 | logger.warn("I am warning you %s", "!!!");
|
151 | logger.error("Error Error Error...");
|
152 | logger.fatal("FATALITY");
|
153 | ```
|
154 |
|
155 | ### 2. Using `log` method
|
156 |
|
157 | Pass an object with `level` and `message` fields:
|
158 | ```js
|
159 | const thundra = require("@thundra/core");
|
160 | const logger = thundra.createLogger();
|
161 |
|
162 | logger.log({
|
163 | level: "trace",
|
164 | message: "Hey, I am tracing."
|
165 | });
|
166 | ```
|
167 |
|
168 | You can also pass `level` as a string, this way you can use `printf`-like formatting:
|
169 |
|
170 | ```js
|
171 | logger.log("trace", "Hey, I am %s", "tracing.");
|
172 | ```
|
173 | `level` can be one of the following: `"trace"`, `"debug"`, `"info"`, `"warn"`, `"error"`, `"fatal"`
|
174 |
|
175 | ## Log Levels
|
176 |
|
177 | In increasing precedence: **`trace`**, **`debug`**, **`info`**, **`warn`**, **`error`**, **`fatal`**.
|
178 |
|
179 | You can set the log level by setting the environment variable `thundra_log_logLevel` to one of the following:
|
180 | * `trace`
|
181 | * `debug`
|
182 | * `info`
|
183 | * `warn`
|
184 | * `error`
|
185 | * `fatal`
|
186 | * `none`
|
187 |
|
188 | For instance, if `thundra_log_logLevel` is:
|
189 | * `debug`, only `debug` and higher precedence logs will be reported.
|
190 | * `none`, none of the logs will be reported.
|
191 |
|
192 | ## Warmup Support
|
193 | You can cut down cold starts easily by deploying our lambda function [`thundra-lambda-warmup`](https://github.com/thundra-io/thundra-lambda-warmup).
|
194 |
|
195 | Our agent handles warmup requests automatically so you don't need to make any code changes.
|
196 |
|
197 | You just need to deploy `thundra-lambda-warmup` once, then you can enable warming up for your lambda by
|
198 | * setting its environment variable `thundra_agent_lambda_warmup_warmupAware` **true** OR
|
199 | * adding its name to `thundra-lambda-warmup`'s environment variable `thundra_agent_lambda_warmup_function`.
|
200 |
|
201 | Check out [this part](https://thundra.readme.io/docs/how-to-warmup) in our docs for more information.
|
202 |
|
203 | ## How to build
|
204 | [Webpack](https://webpack.js.org/) is used as a module bundler.
|
205 |
|
206 | To build the project,
|
207 | ```bash
|
208 | npm install
|
209 | npm run build
|
210 | ```
|
211 |
|
212 | ## How to test
|
213 | Tests are written using [Jest](https://facebook.github.io/jest/).
|
214 |
|
215 | To run tests,
|
216 | ```bash
|
217 | npm run test
|
218 | ```
|
219 |
|
220 | ## Changelog
|
221 |
|
222 | Please see the [CHANGELOG](https://github.com/thundra-io/thundra-lambda-agent-nodejs/blob/master/CHANGELOG.md) file.
|
223 |
|
\ | No newline at end of file |