|
5 | 5 |
|
6 | 6 | The `@baselime/lambda-node-opentelemetry` package instruments your lambda functions and automatically ships OTEL compatible trace data to Baselime. This is the most powerful and flexible way to instrument your node service. |
7 | 7 |
|
| 8 | + |
8 | 9 |
|
9 | | -## Getting started |
| 10 | +This can be applied completely automatically to your lambda functions using our automatic instrumentation. |
10 | 11 |
|
11 | | -Wrap your handlers with the `baselime.wrap(handler)` method. |
| 12 | +To enroll a lambda tag it with `baselime:tracing` `true` |
12 | 13 |
|
13 | | -Example |
14 | | - |
15 | | -```javascript |
16 | | -import baselime from '@baselime/lambda-node-opentelemetry' |
17 | | - |
18 | | -async function main(event, context) { |
19 | | - // your lambda handler |
20 | | -} |
21 | | - |
22 | | -export const handler = baselime.wrap(main); |
23 | | - |
24 | | -``` |
25 | | - |
26 | | -For production systems you should remove the latency overhead of sending open telemetry data by adding the baselime-extension layer. |
27 | | - |
28 | | -```javascript |
29 | | -`arn:aws:lambda:${region}:097948374213:layer:baselime-extension-${'x86_64' || 'arm64'}:1` |
30 | | -``` |
31 | | - |
32 | | -## Adding Custom Events |
33 | | - |
34 | | -Our simple but powerful OTEL compatible logging extension lets you add context rich events to your traces. These events can be useful to show more detailed context on errors, add steps that you want recorded for a business process or simply add extra debug information. |
35 | | - |
36 | | -```javascript |
37 | | -const { logger } = require("@baselime/lambda-node-opentelemetry"); |
38 | | - |
39 | | -logger.info("This is an informational message", { |
40 | | - operation: "copy-paste-replace", |
41 | | - count: 9000, |
42 | | -}); |
43 | | -``` |
44 | | - |
45 | | -The extension provides an object that includes four logging functions - info, warn, debug, and error - enabling you to log messages with varying levels of severity. By setting the LOG_LEVEL environment variable, you can control the visibility of the logs. |
46 | | - |
47 | | -```javascript |
48 | | -const { logger } = require("@baselime/lambda-node-opentelemetry"); |
49 | | - |
50 | | -logger.info("This is an informational message", { payload: { foo: "bar" } }); |
51 | | -logger.warn("This is a warning message", { payload: { foo: "bar" } }); |
52 | | -logger.debug("This is a debug message", { payload: { foo: "bar" } }); |
53 | | -logger.error("This is an error message", { payload: { foo: "bar" } }); |
54 | | -``` |
55 | | - |
56 | | -It shares the same interface as `@baselime/lambda-logger` so if you are moving from cloudwatch to open telemetry this makes the transision seamless. |
57 | | - |
58 | | - |
59 | | -## Manual Installation |
60 | | - |
61 | | -Install the `@baselime/lambda-node-opentelemetry` package |
62 | | - |
63 | | -```bash |
64 | | -npm install @baselime/lambda-node-opentelemetry |
65 | | -``` |
66 | | - |
67 | | -Add the following environment variables to your service |
68 | | - |
69 | | -| Key | Example | Description | |
70 | | -| ------------------ | ------------------------------- | ----------------------------------------------------------------------------------- | |
71 | | -| BASELIME_KEY | nora-is-the-cutest-baselime-dog | Get this key from the [cli](https://github.com/Baselime/cli) running `baselime iam` | |
72 | | -| NODE_OPTIONS | --require @baselime/lambda-node-opentelemetry | Preloads the tracing sdk at startup | |
73 | | - |
74 | | -Get the baselime key using our [cli](https://github.com/Baselime/cli) |
75 | | - |
76 | | -```bash |
77 | | -baselime iam |
78 | | -``` |
79 | | - |
80 | | -You need to make sure the lambda-wrapper file is included in the .zip file that is used by aws-lambda. The exact steps depend on the packaging step of the framework you are using. |
81 | | - |
82 | | -> If you use `export const` `export function` or `export default` for your handler you need to rename it to a cjs export like `module.exports = ` or `exports.handler =`. Even if you use esbuild. We are tracking issues in [esbuild](https://github.com/evanw/esbuild/issues/1079) and [open-telemetry](https://github.com/open-telemetry/opentelemetry-js/issues/1946) and are looking to see how we can help out. |
83 | | -
|
84 | | - |
85 | | -### Architect |
86 | | - |
87 | | -Copy the lambda-wrapper.js file from our node modules to the shared folder of your architect project, this way it is automatically included in all of your lambdas bundles. |
88 | | - |
89 | | -```bash |
90 | | -cp node_modules/@baselime/lambda-node-opentelemetry/lambda-wrapper.js src/shared/ |
91 | | -``` |
92 | | - |
93 | | -Add the environment variables to your architect project |
94 | | - |
95 | | -```bash |
96 | | -arc env -e production --add BASELIME_KEY tux-is-the-smartest-baselime-dog |
97 | | -arc env -e production --add -- NODE_OPTIONS '--require @architect/shared/lambda-wrapper' |
98 | | -``` |
99 | | - |
100 | | -> Watch out for the '--' in the NODE_OPTIONS command. This is required to escape options parsing. |
101 | | -
|
102 | | - |
103 | | -### Serverless |
104 | | - |
105 | | -By default the serverless framework includes your whole node_module directory in the .zip file. If you are using the `serverless-esbuild` plugin to avoid this then you need to add the following configuration to your project. |
106 | | - |
107 | | -https://www.serverless.com/framework/docs/providers/aws/guide/packaging |
108 | | - |
109 | | -Add the following line to the `package.patterns` block of your serverless.yml |
110 | | - |
111 | | -```yaml |
112 | | -- 'node_modules/@baselime/lambda-node-opentelemetry/lambda-wrapper.js' |
113 | | -``` |
114 | | -
|
115 | | -Example |
116 | | -
|
117 | | -```yaml |
118 | | -package: |
119 | | - patterns: |
120 | | - - 'node_modules/@baselime/lambda-node-opentelemetry' |
121 | | -``` |
122 | | -
|
123 | | -Add the following environment variables |
124 | | -```yaml |
125 | | - BASELIME_KEY: ${env:BASELIME_KEY} |
126 | | - NODE_OPTIONS: '--require @baselime/lambda-node-opentelemetry' |
127 | | -``` |
128 | | -
|
129 | | -### SST |
130 | | -
|
131 | | -> Fun fact Baselime is built using SST :) |
132 | | -
|
133 | | -Copy the lambda-wrapper file to your srcPath directory |
134 | | -
|
135 | | -```bash |
136 | | -cp node_modules/@baselime/lambda-node-opentelemetry/lambda-wrapper.js services |
137 | | -``` |
138 | | - |
139 | | -Then add the default props to include the wrapper in your bundle and add your environment variables |
140 | | - |
141 | | - |
142 | | -```javascript |
143 | | -app.setDefaultFunctionProps({ |
144 | | - runtime: "nodejs16.x", |
145 | | - srcPath: "services", |
146 | | - environment: { |
147 | | - NODE_OPTIONS: '--require lambda-wrapper.js', |
148 | | - BASELIME_SERVICE: stack.stackName, |
149 | | - BASELIME_KEY: process.env.BASELIME_KEY |
150 | | - }, |
151 | | - bundle: { |
152 | | - format: "esm", |
153 | | - copyFiles: [{ from: "./lambda-wrapper.js", to: "./lambda-wrapper.js" }], |
154 | | - }, |
155 | | -}); |
156 | | -``` |
157 | | - |
158 | | -## Automatic Instrumentation |
159 | | - |
160 | | -### Manual Setup |
161 | | - |
162 | | -1. Add the baselime-node layer - `arn:aws:lambda:${region:097948374213:layer:baselime-node:4` |
163 | | -2. Add the baselime-extension layer - `arn:aws:lambda:${region}:097948374213:layer:baselime-extension-${'x86_64' || 'arm64'}:1` |
164 | | -3. Set the handler to `/opt/nodejs/node_modules/@baselime/lambda-node-opentelemetry/handler.handler` |
165 | | -4. Set the BASELIME_ACTUAL_HANDLER environment variable to the original path of your lambda |
166 | | -5. Set the BASELIME_KEY environment variable with the value of your environments baselime api key |
167 | | - |
168 | | -### SST |
169 | | - |
170 | | -```typescript |
171 | | -import { LayerVersion } from "aws-cdk-lib/aws-lambda"; |
172 | | - |
173 | | -const baselime = LayerVersion.fromLayerVersionArn( |
174 | | - stack, |
175 | | - "BaselimeLayer", |
176 | | - `arn:aws:lambda:${stack.region}:097948374213:layer:baselime-node:4` |
177 | | -); |
178 | | - |
179 | | -if (!scope.local) { |
180 | | - stack.addDefaultFunctionLayers([baselime]); |
181 | | - stack.addDefaultFunctionEnv({ |
182 | | - AWS_LAMBDA_EXEC_WRAPPER: '/opt/baselime', |
183 | | - BASELIME_KEY: process.env.BASELIME_KEY |
184 | | - }); |
185 | | -} |
186 | | -``` |
187 | | - |
188 | | -### Serverless |
189 | | - |
190 | | -```yml |
191 | | -provider: |
192 | | - ... |
193 | | - layers: |
194 | | - - arn:aws:lambda:${opt:region}:097948374213:layer:baselime-node:4 |
195 | | - environment: |
196 | | - AWS_LAMBDA_EXEC_WRAPPER: '/opt/baselime', |
197 | | - BASELIME_KEY: ${env:BASELIME_KEY} |
198 | | -``` |
199 | | -
|
200 | | -### Architect |
201 | | -
|
202 | | -``` |
203 | | -// app.arc |
204 | | -@aws |
205 | | -layers |
206 | | - arn:aws:lambda:{{ region }}:097948374213:layer:BASElIME-node:4 |
207 | | -``` |
208 | | - |
209 | | -Add the environment variables to your architect project |
210 | | - |
211 | | -```bash |
212 | | -arc env -e production --add BASELIME_KEY tux-is-the-smartest-baselime-dog |
213 | | -arc env -e production --add AWS_LAMBDA_EXEC_WRAPPER /opt/baselime |
214 | | -``` |
215 | | - |
216 | | -## Send data to another OpenTelemetry Backend |
217 | | - |
218 | | -Add the environment variable `COLLECTOR_URL` to send the spans somewhere else. |
| 14 | +If you would rather instrument the lambda manually follow this [guide](./ManualInstrumentation) |
219 | 15 |
|
220 | 16 | ## License |
221 | 17 |
|
|
0 commit comments