@tracelumo/node 0.1.0 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,37 +1,71 @@
1
- # TRACELUMO for Node.js
1
+ # TraceLumo for Node.js
2
2
 
3
- `@tracelumo/node` adds automatic tracing to Node.js applications. It instruments Node HTTP and HTTPS, Express, and built-in `fetch`. It sends traces to your TRACELUMO project over OTLP/HTTP protobuf with request batching and W3C trace propagation. Requires Node.js 22.15 or later.
3
+ `@tracelumo/node` connects a Node.js app to TraceLumo. It traces Node HTTP and HTTPS, Express and built-in `fetch`, sends `console` output as logs linked to the active trace, reports errors to error tracking, sends system and runtime metrics, and announces the service when it starts. No separate agent is needed. Requires Node.js 22.15 or later.
4
4
 
5
- ## Set up
5
+ ## Quick setup
6
6
 
7
- Install the SDK in your application.
7
+ Create a token on your project's **Agent tokens** page, then run this in your app's folder:
8
+
9
+ ```sh
10
+ npx @tracelumo/node init --endpoint https://your-tracelumo.vercel.app --token tl_agent_your_project_token
11
+ ```
12
+
13
+ `init` installs the SDK, saves the endpoint and token to `.env.local` (and makes sure Git ignores it), and hooks the SDK into the app's normal start-up:
14
+
15
+ - **Next.js:** creates `instrumentation.ts`, which Next.js runs whenever the server starts.
16
+ - **Other Node.js apps:** adds the preload to the `dev` and `start` scripts.
17
+
18
+ Start your app as usual. It shows as **Connected** in TraceLumo as soon as it boots. Running `init` again is safe.
19
+
20
+ ## Manual setup
8
21
 
9
22
  ```sh
10
23
  npm install @tracelumo/node
11
24
  ```
12
25
 
13
- Create a project token in **Agent tokens**. Set two environment variables in your app's environment or in its `.env.local`.
26
+ Set the endpoint and token in the app's environment or `.env.local`:
14
27
 
15
28
  ```dotenv
16
- TRACELUMO_OTLP_ENDPOINT=http://127.0.0.1:8080
29
+ TRACELUMO_OTLP_ENDPOINT=https://your-tracelumo.vercel.app
17
30
  TRACELUMO_AGENT_TOKEN=tl_agent_your_project_token
18
31
  ```
19
32
 
20
- With the package installed, preload it before your application starts.
33
+ Then load the SDK before the app starts. In Next.js, add `instrumentation.ts`:
21
34
 
22
- ```sh
23
- node --require @tracelumo/node/register server.js
35
+ ```ts
36
+ export async function register() {
37
+ if (process.env.NEXT_RUNTIME === "nodejs") await import("@tracelumo/node/register");
38
+ }
24
39
  ```
25
40
 
26
- For an existing npm script, pass the preload through `NODE_OPTIONS`.
41
+ For other apps, preload it:
27
42
 
28
43
  ```sh
44
+ node --require @tracelumo/node/register server.js
29
45
  NODE_OPTIONS="--require @tracelumo/node/register" npm run dev
30
46
  ```
31
47
 
32
- Make a request and open your project's **Traces Explorer**. The service defaults to the `name` in your app's `package.json`. Set `TRACELUMO_SERVICE_NAME` to label it explicitly. Endpoint URLs accept an origin or the full trace endpoint. Remote endpoints use HTTPS.
48
+ ## Settings
49
+
50
+ | Variable | Default | Purpose |
51
+ | --- | --- | --- |
52
+ | `TRACELUMO_OTLP_ENDPOINT` | — | API address. Remote endpoints must use HTTPS. |
53
+ | `TRACELUMO_AGENT_TOKEN` | — | Project agent token. |
54
+ | `TRACELUMO_SERVICE_NAME` | `name` in package.json | Service name shown in TraceLumo. |
55
+ | `TRACELUMO_LOGS` | `true` | Set to `false` to stop sending console output as logs and errors. |
56
+ | `TRACELUMO_METRICS` | `true` | Set to `false` to stop sending system metrics. |
57
+ | `TRACELUMO_METRICS_INTERVAL` | `15` | Seconds between metric samples (5 to 300). |
58
+ | `TRACELUMO_ENABLED` | `true` | Set to `false` to turn the SDK off. |
59
+
60
+ Logs are batched (up to 100 per request, sent every second) and capped at 8 KiB per line. Node.js process warnings are sent as `warn`, not `error`.
61
+
62
+ **Errors:** uncaught exceptions, unhandled promise rejections and any `Error` passed to `console.error` are sent to error tracking, where the same error from the same place is grouped into one issue. After an uncaught exception the SDK keeps Node's default behaviour — print the error and exit with code 1 — once the report is sent (at most 2 seconds), unless your app has its own `uncaughtException` handler. The SDK never traces or logs its own requests. Use a single OpenTelemetry setup per app: if you already register a tracer, replace it with this package.
33
63
 
34
- Use a single OpenTelemetry preload. If you already initialize a tracer, replace that startup hook when moving to this package. Your settings and tracing SDK can remain server-side. `TRACELUMO_ENABLED=false` disables the preload.
64
+ **System metrics:** every 15 seconds the SDK records the process's CPU, memory (RSS, heap), event loop delay and
65
+ utilization, garbage collection pauses and open handles, plus the machine's CPU, memory, load average, disk and (on
66
+ Linux) network. It also records the host name, OS, CPU model, memory limit and Node.js version. Everything uses Node.js
67
+ built-ins inside your app: no agent or extra process. Samples are sent in batches every 30 seconds, and the timers never
68
+ keep your process alive. They appear on the project's **Infrastructure** page, one row per running instance.
35
69
 
36
70
  ## Lifecycle hooks
37
71
 
@@ -51,4 +85,4 @@ From the TRACELUMO repository, run
51
85
  (cd packages/node && npm pack --pack-destination /tmp)
52
86
  ```
53
87
 
54
- Then run `npm install /tmp/tracelumo-node-0.1.0.tgz` in the application directory.
88
+ Then run `npm install /tmp/tracelumo-node-0.2.0.tgz` in the application directory.
package/package.json CHANGED
@@ -1,9 +1,12 @@
1
1
  {
2
2
  "name": "@tracelumo/node",
3
- "version": "0.1.0",
4
- "description": "Automatic Node.js tracing for TRACELUMO",
3
+ "version": "0.4.0",
4
+ "description": "Connect Node.js apps to TraceLumo: automatic traces, logs, errors and system metrics",
5
5
  "type": "commonjs",
6
6
  "main": "./src/index.cjs",
7
+ "bin": {
8
+ "tracelumo-node": "src/init.cjs"
9
+ },
7
10
  "exports": {
8
11
  ".": {
9
12
  "import": {
package/src/config.cjs CHANGED
@@ -57,7 +57,17 @@ function configuration(options = {}, cwd = process.cwd(), environment = process.
57
57
  if (!service || Buffer.byteLength(service) > 128 || /[\0\r\n]/.test(service)) {
58
58
  throw new Error('TRACELUMO_SERVICE_NAME must contain 1 to 128 bytes on a single line.');
59
59
  }
60
- return { url: traceURL(endpoint), token, service };
60
+ const url = traceURL(endpoint);
61
+ const logs = options.logs ?? setting('TRACELUMO_LOGS') !== 'false';
62
+ const metrics = options.metrics ?? setting('TRACELUMO_METRICS') !== 'false';
63
+ // Seconds between metric samples: 15 by default, 5 to 300.
64
+ const requested = Number(options.metricsInterval ?? setting('TRACELUMO_METRICS_INTERVAL') ?? 15);
65
+ const metricsInterval = Number.isFinite(requested) ? Math.min(300, Math.max(5, Math.round(requested))) : 15;
66
+ const base = url.replace(/\/v1\/traces$/, '');
67
+ return {
68
+ url, logsUrl: `${base}/v1/ingest/logs`, errorsUrl: `${base}/v1/ingest/errors`, metricsUrl: `${base}/v1/ingest/metrics`,
69
+ token, service, logs, metrics, metricsInterval,
70
+ };
61
71
  }
62
72
 
63
- module.exports = { configuration };
73
+ module.exports = { configuration, traceURL };
package/src/index.cjs CHANGED
@@ -10,9 +10,9 @@ function start(options) {
10
10
  const config = configuration(options);
11
11
  if (!config) return;
12
12
 
13
- const { context, propagation, trace } = require('@opentelemetry/api');
13
+ const { context, isSpanContextValid, propagation, trace } = require('@opentelemetry/api');
14
14
  const { AsyncLocalStorageContextManager } = require('@opentelemetry/context-async-hooks');
15
- const { W3CTraceContextPropagator } = require('@opentelemetry/core');
15
+ const { suppressTracing, W3CTraceContextPropagator } = require('@opentelemetry/core');
16
16
  const { registerInstrumentations } = require('@opentelemetry/instrumentation');
17
17
  const { ExpressInstrumentation } = require('@opentelemetry/instrumentation-express');
18
18
  const { HttpInstrumentation } = require('@opentelemetry/instrumentation-http');
@@ -59,12 +59,37 @@ function start(options) {
59
59
  require('node:http');
60
60
  require('node:https');
61
61
  syncBuiltinESMExports();
62
- globalThis[instance] = { provider, stopInstrumentation };
62
+
63
+ let logs = null;
64
+ let errors = null;
65
+ let restoreConsole = () => {};
66
+ let restoreCrashes = () => {};
67
+ if (config.logs) {
68
+ const { captureConsole, captureCrashes, createErrorShipper, createLogShipper } = require('./logs.cjs');
69
+ const options = { suppress: (fn) => context.with(suppressTracing(context.active()), fn) };
70
+ const activeTrace = () => {
71
+ const span = trace.getSpanContext(context.active());
72
+ return span && isSpanContextValid(span) ? span.traceId : undefined;
73
+ };
74
+ logs = createLogShipper(config, options);
75
+ errors = createErrorShipper(config, options);
76
+ restoreConsole = captureConsole(logs, activeTrace, errors);
77
+ restoreCrashes = captureCrashes(errors, activeTrace);
78
+ // Announce the service as soon as it starts, so the project shows as connected before any request.
79
+ logs.add('info', `TraceLumo connected: ${config.service} started (Node.js ${process.version}, pid ${process.pid})`);
80
+ setImmediate(logs.flush);
81
+ }
82
+ let metrics = null;
83
+ if (config.metrics) {
84
+ const { startMetrics } = require('./metrics.cjs');
85
+ metrics = startMetrics(config, { suppress: (fn) => context.with(suppressTracing(context.active()), fn) });
86
+ }
87
+ globalThis[instance] = { provider, stopInstrumentation, logs, errors, metrics, restoreConsole, restoreCrashes };
63
88
  }
64
89
 
65
90
  async function flush() {
66
91
  const sdk = globalThis[instance];
67
- if (sdk) await (sdk.stopping ?? sdk.provider.forceFlush());
92
+ if (sdk) await Promise.all([sdk.stopping ?? sdk.provider.forceFlush(), sdk.logs?.flush(), sdk.errors?.flush(), sdk.metrics?.flush()]);
68
93
  }
69
94
 
70
95
  async function shutdown() {
@@ -72,8 +97,10 @@ async function shutdown() {
72
97
  if (!sdk) return;
73
98
  if (!sdk.stopping) {
74
99
  sdk.stopInstrumentation();
100
+ sdk.restoreConsole();
101
+ sdk.restoreCrashes();
75
102
  syncBuiltinESMExports();
76
- sdk.stopping = sdk.provider.shutdown();
103
+ sdk.stopping = Promise.all([sdk.provider.shutdown(), sdk.logs?.close(), sdk.errors?.close(), sdk.metrics?.close()]).then(() => {});
77
104
  }
78
105
  await sdk.stopping;
79
106
  }
package/src/index.d.cts CHANGED
@@ -3,6 +3,12 @@ export interface TracingOptions {
3
3
  token?: string;
4
4
  serviceName?: string;
5
5
  enabled?: boolean;
6
+ /** Send console output as logs. Defaults to true; TRACELUMO_LOGS=false turns it off. */
7
+ logs?: boolean;
8
+ /** Send system and runtime metrics (CPU, memory, event loop, GC, disk). Defaults to true; TRACELUMO_METRICS=false turns it off. */
9
+ metrics?: boolean;
10
+ /** Seconds between metric samples, 5 to 300. Defaults to 15 (TRACELUMO_METRICS_INTERVAL). */
11
+ metricsInterval?: number;
6
12
  }
7
13
 
8
14
  export function start(options?: TracingOptions): void;
package/src/init.cjs ADDED
@@ -0,0 +1,273 @@
1
+ #!/usr/bin/env node
2
+ 'use strict';
3
+
4
+ // `npx @tracelumo/node init` connects an app to TraceLumo in one step: it installs the SDK, wires
5
+ // it into the app's normal start-up, and saves the endpoint and token. Running it again is safe.
6
+
7
+ const { execFileSync } = require('node:child_process');
8
+ const { chmodSync, existsSync, readFileSync, writeFileSync } = require('node:fs');
9
+ const { join } = require('node:path');
10
+ const { parseArgs, parseEnv } = require('node:util');
11
+ const { traceURL } = require('./config.cjs');
12
+
13
+ const PACKAGE = '@tracelumo/node';
14
+ const PRELOAD = `${PACKAGE}/register`;
15
+ const TOKEN = /^tl_agent_[A-Za-z0-9_-]{23,119}$/;
16
+ const { version } = require('../package.json');
17
+
18
+ const usage = `Connect this app to TraceLumo.
19
+
20
+ Usage: npx @tracelumo/node init --endpoint <url> --token <tl_agent_…> [options]
21
+
22
+ Options:
23
+ --endpoint <url> TraceLumo address, e.g. https://tracelumo.vercel.app
24
+ --token <token> Project agent token from the Agent tokens page
25
+ --service <name> Service name shown in TraceLumo (default: package.json name)
26
+ --package <spec> Install the SDK from this spec instead of npm (e.g. a local .tgz)
27
+ --skip-install Don't install the SDK
28
+ --dir <path> App directory (default: current directory)
29
+ -h, --help Show this help`;
30
+
31
+ function readText(path) {
32
+ try {
33
+ return readFileSync(path, 'utf8');
34
+ } catch (error) {
35
+ if (error.code === 'ENOENT') return null;
36
+ throw error;
37
+ }
38
+ }
39
+
40
+ function readJSON(path) {
41
+ const text = readText(path);
42
+ if (text === null) return null;
43
+ const indent = /^(\s+)"/m.exec(text)?.[1] ?? ' ';
44
+ return { data: JSON.parse(text), indent };
45
+ }
46
+
47
+ function writeJSON(path, { data, indent }) {
48
+ writeFileSync(path, `${JSON.stringify(data, null, indent)}\n`);
49
+ }
50
+
51
+ function packageManager(dir) {
52
+ if (existsSync(join(dir, 'pnpm-lock.yaml'))) return ['pnpm', ['add']];
53
+ if (existsSync(join(dir, 'yarn.lock'))) return ['yarn', ['add']];
54
+ if (existsSync(join(dir, 'bun.lockb')) || existsSync(join(dir, 'bun.lock'))) return ['bun', ['add']];
55
+ return ['npm', ['install']];
56
+ }
57
+
58
+ function installedVersion(dir) {
59
+ const manifest = readJSON(join(dir, 'node_modules', PACKAGE, 'package.json'));
60
+ return manifest?.data.version ?? null;
61
+ }
62
+
63
+ function newer(a, b) {
64
+ const pa = a.split('.').map(Number);
65
+ const pb = b.split('.').map(Number);
66
+ for (let i = 0; i < 3; i += 1) if ((pa[i] || 0) !== (pb[i] || 0)) return (pa[i] || 0) > (pb[i] || 0);
67
+ return false;
68
+ }
69
+
70
+ /** Sets KEY=value lines in a dotenv file, replacing existing assignments and keeping everything else. */
71
+ function upsertEnv(path, entries) {
72
+ const original = readText(path);
73
+ const lines = original === null ? [] : original.replace(/\n$/, '').split('\n');
74
+ const missing = new Map(Object.entries(entries));
75
+ const updated = lines.map((line) => {
76
+ const key = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=/.exec(line)?.[1];
77
+ if (key && missing.has(key)) {
78
+ const value = missing.get(key);
79
+ missing.delete(key);
80
+ return `${key}=${value}`;
81
+ }
82
+ return line;
83
+ });
84
+ if (missing.size) {
85
+ if (updated.length && updated.at(-1) !== '') updated.push('');
86
+ updated.push('# TraceLumo');
87
+ for (const [key, value] of missing) updated.push(`${key}=${value}`);
88
+ }
89
+ const next = `${updated.join('\n')}\n`;
90
+ if (next === original) return false;
91
+ writeFileSync(path, next, { mode: 0o600 });
92
+ chmodSync(path, 0o600); // The file holds a token, so keep it private even if it already existed.
93
+ return true;
94
+ }
95
+
96
+ function gitIgnores(dir, file) {
97
+ try {
98
+ execFileSync('git', ['rev-parse', '--is-inside-work-tree'], { cwd: dir, stdio: 'ignore' });
99
+ } catch {
100
+ return null;
101
+ }
102
+ try {
103
+ execFileSync('git', ['check-ignore', '-q', file], { cwd: dir, stdio: 'ignore' });
104
+ return true;
105
+ } catch {
106
+ return false;
107
+ }
108
+ }
109
+
110
+ const INSTRUMENTATION = `// Sends this app's traces and logs to TraceLumo. Added by \`npx @tracelumo/node init\`.
111
+ export async function register() {
112
+ if (process.env.NEXT_RUNTIME === "nodejs") {
113
+ await import("${PRELOAD}");
114
+ }
115
+ }
116
+ `;
117
+
118
+ function setupNext(dir, report) {
119
+ const base = existsSync(join(dir, 'src', 'app')) || existsSync(join(dir, 'src', 'pages')) ? join(dir, 'src') : dir;
120
+ const label = base === dir ? '' : 'src/';
121
+ const existing = ['ts', 'js', 'mjs'].map((ext) => join(base, `instrumentation.${ext}`)).find(existsSync);
122
+ if (existing) {
123
+ const name = `${label}${existing.split(/[\\/]/).at(-1)}`;
124
+ if (readText(existing).includes(PACKAGE)) {
125
+ report.ok(`${name} already loads TraceLumo`);
126
+ } else {
127
+ report.todo(`${name} already exists. Add this inside its register() function:\n` +
128
+ ` if (process.env.NEXT_RUNTIME === "nodejs") await import("${PRELOAD}");`);
129
+ }
130
+ return;
131
+ }
132
+ const ext = existsSync(join(dir, 'tsconfig.json')) ? 'ts' : 'js';
133
+ writeFileSync(join(base, `instrumentation.${ext}`), INSTRUMENTATION);
134
+ report.ok(`Created ${label}instrumentation.${ext} (Next.js runs it whenever the server starts)`);
135
+ }
136
+
137
+ function setupNode(dir, report) {
138
+ const path = join(dir, 'package.json');
139
+ const manifest = readJSON(path);
140
+ const scripts = manifest.data.scripts ?? {};
141
+ const changed = [];
142
+ for (const name of ['dev', 'start']) {
143
+ const script = scripts[name];
144
+ if (typeof script !== 'string' || script.includes(PRELOAD)) continue;
145
+ scripts[name] = /^node\s/.test(script)
146
+ ? script.replace(/^node\s+/, `node --require ${PRELOAD} `)
147
+ : `NODE_OPTIONS='--require ${PRELOAD}' ${script}`;
148
+ changed.push(name);
149
+ }
150
+ if (changed.length) {
151
+ manifest.data.scripts = scripts;
152
+ writeJSON(path, manifest);
153
+ report.ok(`Added TraceLumo to the ${changed.map((name) => `"${name}"`).join(' and ')} script${changed.length > 1 ? 's' : ''}`);
154
+ } else if (Object.values(scripts).some((script) => typeof script === 'string' && script.includes(PRELOAD))) {
155
+ report.ok('Start scripts already load TraceLumo');
156
+ } else {
157
+ report.todo(`No "dev" or "start" script found. Start your app with: node --require ${PRELOAD} <entry file>`);
158
+ }
159
+ }
160
+
161
+ async function verify(endpoint, token) {
162
+ try {
163
+ const response = await fetch(traceURL(endpoint), {
164
+ method: 'POST',
165
+ headers: { 'Content-Type': 'application/x-protobuf', Authorization: `Bearer ${token}` },
166
+ body: new Uint8Array(0),
167
+ signal: AbortSignal.timeout(5000),
168
+ });
169
+ return response.ok ? 'ok' : response.status === 401 ? 'rejected' : `HTTP ${response.status}`;
170
+ } catch {
171
+ return 'unreachable';
172
+ }
173
+ }
174
+
175
+ async function main(argv = process.argv.slice(2)) {
176
+ const { values, positionals } = parseArgs({
177
+ args: argv,
178
+ allowPositionals: true,
179
+ options: {
180
+ endpoint: { type: 'string' },
181
+ token: { type: 'string' },
182
+ service: { type: 'string' },
183
+ package: { type: 'string' },
184
+ 'skip-install': { type: 'boolean' },
185
+ dir: { type: 'string' },
186
+ help: { type: 'boolean', short: 'h' },
187
+ },
188
+ });
189
+ if (values.help || (positionals.length && positionals[0] !== 'init')) {
190
+ console.log(usage);
191
+ return values.help ? 0 : 1;
192
+ }
193
+
194
+ const dir = values.dir ?? process.cwd();
195
+ const report = {
196
+ lines: [],
197
+ todos: [],
198
+ ok(text) { this.lines.push(` ✓ ${text}`); },
199
+ todo(text) { this.todos.push(` ! ${text}`); },
200
+ };
201
+ const fail = (message) => { console.error(`TraceLumo setup stopped: ${message}`); return 1; };
202
+
203
+ if (!readJSON(join(dir, 'package.json'))) return fail(`no package.json in ${dir}. Run this in your app's folder.`);
204
+
205
+ const envPath = join(dir, '.env.local');
206
+ const current = parseEnv(readText(envPath) ?? '');
207
+ const endpoint = (values.endpoint ?? current.TRACELUMO_OTLP_ENDPOINT ?? '').trim().replace(/\/+$/, '');
208
+ const token = (values.token ?? current.TRACELUMO_AGENT_TOKEN ?? '').trim();
209
+ if (!endpoint) return fail('pass --endpoint with your TraceLumo API address.');
210
+ try {
211
+ traceURL(endpoint);
212
+ } catch (error) {
213
+ return fail(error.message);
214
+ }
215
+ if (!TOKEN.test(token)) return fail('pass --token with an agent token from the Agent tokens page (it starts with tl_agent_).');
216
+
217
+ console.log('Connecting this app to TraceLumo…\n');
218
+
219
+ // 1. Install the SDK unless a current version is already there.
220
+ const have = installedVersion(dir);
221
+ if (values['skip-install']) {
222
+ report.ok('Skipped installing the SDK');
223
+ } else if (have && !values.package && !newer(version, have)) {
224
+ report.ok(`${PACKAGE} ${have} is already installed`);
225
+ } else {
226
+ const [command, args] = packageManager(dir);
227
+ const spec = values.package ?? `${PACKAGE}@^${version}`;
228
+ console.log(` Installing ${spec} with ${command}…`);
229
+ try {
230
+ execFileSync(command, [...args, spec], { cwd: dir, stdio: ['ignore', 'ignore', 'inherit'] });
231
+ } catch {
232
+ return fail(`${command} could not install ${spec}.`);
233
+ }
234
+ report.ok(`Installed ${PACKAGE} ${installedVersion(dir) ?? ''}`.trim());
235
+ }
236
+
237
+ // 2. Save the endpoint and token where the SDK reads them.
238
+ const settings = { TRACELUMO_OTLP_ENDPOINT: endpoint, TRACELUMO_AGENT_TOKEN: token };
239
+ if (values.service) settings.TRACELUMO_SERVICE_NAME = values.service;
240
+ report.ok(upsertEnv(envPath, settings) ? 'Saved the endpoint and token to .env.local' : '.env.local already has these settings');
241
+ const ignored = gitIgnores(dir, '.env.local');
242
+ if (ignored === false) {
243
+ const gitignore = join(dir, '.gitignore');
244
+ writeFileSync(gitignore, `${(readText(gitignore) ?? '').replace(/\n?$/, '\n')}.env.local\n`);
245
+ report.ok('Added .env.local to .gitignore so the token is never committed');
246
+ }
247
+
248
+ // 3. Load the SDK whenever the app starts.
249
+ const manifest = readJSON(join(dir, 'package.json')).data;
250
+ const deps = { ...manifest.dependencies, ...manifest.devDependencies };
251
+ if (deps.next) setupNext(dir, report);
252
+ else setupNode(dir, report);
253
+
254
+ // 4. Check the token against the API.
255
+ const check = await verify(endpoint, token);
256
+ if (check === 'ok') report.ok(`Token accepted by ${endpoint}`);
257
+ else if (check === 'rejected') report.todo('The API rejected this token. Create a new one on the Agent tokens page and run init again.');
258
+ else if (check === 'unreachable') report.todo(`Couldn't reach ${endpoint}. Make sure TraceLumo is running; the app will connect once it is.`);
259
+ else report.todo(`The API answered ${check} when checking the token.`);
260
+
261
+ console.log([...report.lines, ...report.todos].join('\n'));
262
+ console.log(`\nDone. Start your app as usual${deps.next ? ' (npm run dev)' : ''}. It shows as Connected in TraceLumo as soon as it starts.`);
263
+ return 0;
264
+ }
265
+
266
+ if (require.main === module) {
267
+ main().then((code) => { process.exitCode = code; }, (error) => {
268
+ console.error(`TraceLumo setup failed: ${error.message}`);
269
+ process.exitCode = 1;
270
+ });
271
+ }
272
+
273
+ module.exports = { main, upsertEnv };
package/src/logs.cjs ADDED
@@ -0,0 +1,199 @@
1
+ 'use strict';
2
+
3
+ const { randomUUID } = require('node:crypto');
4
+ const http = require('node:http');
5
+ const https = require('node:https');
6
+ const { format, inspect } = require('node:util');
7
+ const { gzipSync } = require('node:zlib');
8
+
9
+ // Limits match the TraceLumo log ingest API.
10
+ const MAX_BATCH = 100;
11
+ const MAX_BODY = 8192;
12
+ const MAX_QUEUE = 2000;
13
+ const INTERVAL = 1000;
14
+ const ANSI = /\u001b\[[0-?]*[ -/]*[@-~]/g;
15
+ const METHODS = { debug: 'debug', trace: 'debug', log: 'info', info: 'info', warn: 'warn', error: 'error' };
16
+
17
+ function clip(text) {
18
+ if (Buffer.byteLength(text) <= MAX_BODY) return text;
19
+ return `${Buffer.from(text).subarray(0, MAX_BODY - 3).toString('utf8').replace(/�+$/, '')}…`;
20
+ }
21
+
22
+ /**
23
+ * A batching queue that sends JSON events to one ingest API. Requests run with tracing suppressed so the SDK
24
+ * never traces or logs its own traffic. Transient failures are retried on the next tick; a rejected token is
25
+ * reported once and its events are dropped.
26
+ */
27
+ function createQueue({ url, token, maxBatch, kind, interval = INTERVAL }, { suppress }) {
28
+ const target = new URL(url);
29
+ const transport = target.protocol === 'https:' ? https : http;
30
+ let queue = [];
31
+ let inflight = null;
32
+ let warned = false;
33
+
34
+ function post(batch) {
35
+ const data = gzipSync(JSON.stringify(batch));
36
+ return new Promise((resolve) => {
37
+ suppress(() => {
38
+ const request = transport.request(target, {
39
+ method: 'POST',
40
+ timeout: 5000,
41
+ headers: {
42
+ 'Content-Type': 'application/json',
43
+ 'Content-Encoding': 'gzip',
44
+ 'Content-Length': data.length,
45
+ Authorization: `Bearer ${token}`,
46
+ },
47
+ }, (response) => {
48
+ response.on('error', () => resolve(0));
49
+ response.on('end', () => resolve(response.statusCode ?? 0));
50
+ response.resume();
51
+ });
52
+ request.on('timeout', () => request.destroy());
53
+ request.on('error', () => resolve(0));
54
+ request.end(data);
55
+ });
56
+ });
57
+ }
58
+
59
+ async function drain() {
60
+ while (queue.length) {
61
+ const batch = queue.splice(0, maxBatch);
62
+ const status = await post(batch);
63
+ if (status >= 200 && status < 300) continue;
64
+ if (status === 0 || status === 429 || status >= 500) {
65
+ queue = batch.concat(queue).slice(-MAX_QUEUE);
66
+ return;
67
+ }
68
+ if (!warned) {
69
+ warned = true;
70
+ process.emitWarning(`TraceLumo rejected a ${kind} batch (HTTP ${status}). Check TRACELUMO_AGENT_TOKEN.`, { code: 'TRACELUMO_LOGS' });
71
+ }
72
+ }
73
+ }
74
+
75
+ function flush() {
76
+ inflight ??= drain().finally(() => { inflight = null; });
77
+ return inflight;
78
+ }
79
+
80
+ function push(event) {
81
+ if (queue.length >= MAX_QUEUE) queue.shift();
82
+ queue.push(event);
83
+ if (queue.length >= maxBatch) setImmediate(flush);
84
+ }
85
+
86
+ const timer = setInterval(flush, interval);
87
+ timer.unref();
88
+ process.once('beforeExit', () => { void flush(); });
89
+
90
+ return {
91
+ push,
92
+ flush,
93
+ async close() {
94
+ clearInterval(timer);
95
+ await flush();
96
+ },
97
+ };
98
+ }
99
+
100
+ /** Sends console output as log events. */
101
+ function createLogShipper({ logsUrl, token, service }, options) {
102
+ const queue = createQueue({ url: logsUrl, token, maxBatch: MAX_BATCH, kind: 'log' }, options);
103
+ return {
104
+ add(severity, body, traceId) {
105
+ const event = { event_id: randomUUID(), timestamp: new Date().toISOString(), service, severity, body: clip(body) };
106
+ if (traceId) event.trace_id = traceId;
107
+ queue.push(event);
108
+ },
109
+ flush: queue.flush,
110
+ close: queue.close,
111
+ };
112
+ }
113
+
114
+ /** Sends exceptions to error tracking, where they are grouped into issues. */
115
+ function createErrorShipper({ errorsUrl, token, service }, options) {
116
+ const queue = createQueue({ url: errorsUrl, token, maxBatch: 50, kind: 'error' }, options);
117
+ return {
118
+ add(error, { handled, traceId }) {
119
+ const isError = error instanceof Error;
120
+ const name = isError ? (error.name || error.constructor?.name || 'Error') : 'UnhandledRejection';
121
+ const event = {
122
+ event_id: randomUUID(),
123
+ timestamp: new Date().toISOString(),
124
+ service,
125
+ type: String(name).slice(0, 200),
126
+ message: String(isError ? error.message : inspect(error)).slice(0, 4000),
127
+ stack: isError && typeof error.stack === 'string' ? error.stack.slice(0, 32000) : '',
128
+ handled,
129
+ };
130
+ if (!event.message && !event.type) return;
131
+ if (traceId) event.trace_id = traceId;
132
+ queue.push(event);
133
+ },
134
+ flush: queue.flush,
135
+ close: queue.close,
136
+ };
137
+ }
138
+
139
+ // Node.js prints its own process warnings through console.error, e.g.
140
+ // "(node:7) ExperimentalWarning: …" or "(node:7) [DEP0040] DeprecationWarning: …". They are warnings, not errors.
141
+ const NODE_WARNING = /^\(node:\d+\)\s+(?:\[[A-Z0-9]+\]\s+)?[A-Za-z]*Warning:/;
142
+
143
+ /** The severity for a console call, correcting Node.js process warnings that arrive through console.error. */
144
+ function severityOf(severity, body) {
145
+ return severity === 'error' && NODE_WARNING.test(body) ? 'warn' : severity;
146
+ }
147
+
148
+ /** Mirrors console output to the shipper, tagged with the active trace. Returns a restore function. */
149
+ function captureConsole(shipper, traceId, errors) {
150
+ const originals = {};
151
+ let busy = false;
152
+ for (const [method, severity] of Object.entries(METHODS)) {
153
+ const original = console[method];
154
+ if (typeof original !== 'function') continue;
155
+ originals[method] = original;
156
+ console[method] = function tracelumoConsole(...args) {
157
+ original.apply(this, args);
158
+ if (busy) return;
159
+ busy = true;
160
+ try {
161
+ let body = format(...args).replace(ANSI, '').trim();
162
+ if (method === 'trace') body = `Trace: ${body}`;
163
+ const trace = traceId();
164
+ if (body) shipper.add(severityOf(severity, body), body, trace);
165
+ // An Error passed to console.error (how frameworks such as Next.js report request errors) is also an error event.
166
+ if (errors && method === 'error') {
167
+ const error = args.find((arg) => arg instanceof Error);
168
+ if (error) errors.add(error, { handled: true, traceId: trace });
169
+ }
170
+ } catch {
171
+ // Logging must never break the application.
172
+ } finally {
173
+ busy = false;
174
+ }
175
+ };
176
+ }
177
+ return () => {
178
+ for (const [method, original] of Object.entries(originals)) console[method] = original;
179
+ };
180
+ }
181
+
182
+ /**
183
+ * Reports uncaught exceptions and unhandled rejections. When TraceLumo's handler is the only one, it keeps
184
+ * Node's default behaviour — print the error and exit with code 1 — after giving the report up to 2 seconds.
185
+ */
186
+ function captureCrashes(errors, traceId) {
187
+ async function onCrash(error, origin) {
188
+ errors.add(error, { handled: false, traceId: traceId() });
189
+ if (process.listenerCount('uncaughtException') > 1) return;
190
+ await Promise.race([errors.flush(), new Promise((resolve) => setTimeout(resolve, 2000).unref())]);
191
+ const label = origin === 'unhandledRejection' ? 'Unhandled rejection' : 'Uncaught exception';
192
+ process.stderr.write(`${label}: ${error instanceof Error ? error.stack ?? error.message : inspect(error)}\n`);
193
+ process.exit(1);
194
+ }
195
+ process.on('uncaughtException', onCrash);
196
+ return () => process.off('uncaughtException', onCrash);
197
+ }
198
+
199
+ module.exports = { createQueue, createLogShipper, createErrorShipper, captureConsole, captureCrashes, clip, severityOf };
@@ -0,0 +1,184 @@
1
+ 'use strict';
2
+
3
+ const { randomUUID } = require('node:crypto');
4
+ const { existsSync, readFileSync, statfsSync } = require('node:fs');
5
+ const os = require('node:os');
6
+ const { monitorEventLoopDelay, performance, PerformanceObserver } = require('node:perf_hooks');
7
+ const { createQueue } = require('./logs.cjs');
8
+
9
+ /**
10
+ * System and runtime metrics, collected inside the application with Node.js built-ins only — no agent, no extra
11
+ * process, no dependencies. Every interval it records one sample: process CPU and memory, heap, event loop delay
12
+ * and utilization, garbage collection, open handles, and the machine's CPU, memory, load, disk and (on Linux)
13
+ * network. Samples are batched and sent to TraceLumo; the timers never keep the process alive.
14
+ */
15
+
16
+ const SEND_EVERY = 30_000;
17
+ const round = (value, digits = 2) => (Number.isFinite(value) ? Number(value.toFixed(digits)) : undefined);
18
+ const ms = (ns) => ns / 1e6;
19
+
20
+ /** Where the process runs, so the dashboard can explain what the machine numbers mean. */
21
+ function runtime(env = process.env) {
22
+ if (env.VERCEL) return 'vercel';
23
+ if (env.AWS_LAMBDA_FUNCTION_NAME) return 'aws-lambda';
24
+ if (env.K_SERVICE) return 'cloud-run';
25
+ if (env.KUBERNETES_SERVICE_HOST) return 'kubernetes';
26
+ if (existsSync('/.dockerenv')) return 'docker';
27
+ return 'host';
28
+ }
29
+
30
+ /** Facts about the machine and process that rarely change. */
31
+ function hostInfo(service) {
32
+ const cpus = os.cpus();
33
+ const limit = typeof process.constrainedMemory === 'function' ? process.constrainedMemory() : 0;
34
+ return {
35
+ hostname: os.hostname().slice(0, 128),
36
+ service,
37
+ os: `${os.type()} ${os.release()}`.slice(0, 128),
38
+ platform: process.platform,
39
+ arch: process.arch,
40
+ cpu_model: (cpus[0]?.model ?? '').trim().slice(0, 128),
41
+ cpus: os.availableParallelism?.() ?? cpus.length,
42
+ memory_total: os.totalmem(),
43
+ // A container or cgroup memory limit, when one is set below the machine's memory.
44
+ ...(limit > 0 && limit < os.totalmem() ? { memory_limit: limit } : {}),
45
+ node: process.version,
46
+ pid: process.pid,
47
+ runtime: runtime(),
48
+ started: new Date(Date.now() - process.uptime() * 1000).toISOString(),
49
+ };
50
+ }
51
+
52
+ function cpuTimes() {
53
+ let idle = 0;
54
+ let total = 0;
55
+ for (const cpu of os.cpus()) {
56
+ const { user, nice, sys, irq, idle: free } = cpu.times;
57
+ idle += free;
58
+ total += user + nice + sys + irq + free;
59
+ }
60
+ return { idle, total };
61
+ }
62
+
63
+ /** Network bytes received and sent by all non-loopback interfaces (Linux only). */
64
+ function networkBytes() {
65
+ if (process.platform !== 'linux') return null;
66
+ try {
67
+ let rx = 0;
68
+ let tx = 0;
69
+ for (const line of readFileSync('/proc/net/dev', 'utf8').split('\n').slice(2)) {
70
+ const [name, data] = line.split(':');
71
+ if (!data || name.trim() === 'lo') continue;
72
+ const fields = data.trim().split(/\s+/).map(Number);
73
+ rx += fields[0];
74
+ tx += fields[8];
75
+ }
76
+ return { rx, tx };
77
+ } catch {
78
+ return null;
79
+ }
80
+ }
81
+
82
+ function disk(path) {
83
+ try {
84
+ const stats = statfsSync(path);
85
+ const total = stats.blocks * stats.bsize;
86
+ return total > 0 ? { total, free: stats.bavail * stats.bsize } : null;
87
+ } catch {
88
+ return null;
89
+ }
90
+ }
91
+
92
+ /** Measures one process. `sample()` returns the values since the previous call. */
93
+ function createSampler({ service, cwd = process.cwd() } = {}) {
94
+ const info = hostInfo(service);
95
+ const delay = monitorEventLoopDelay({ resolution: 20 });
96
+ delay.enable();
97
+ let gcCount = 0;
98
+ let gcPause = 0;
99
+ let gc = null;
100
+ try {
101
+ gc = new PerformanceObserver((list) => {
102
+ for (const entry of list.getEntries()) {
103
+ gcCount += 1;
104
+ gcPause += entry.duration;
105
+ }
106
+ });
107
+ gc.observe({ entryTypes: ['gc'] });
108
+ } catch {
109
+ gc = null;
110
+ }
111
+ let last = { at: performance.now(), cpu: process.cpuUsage(), system: cpuTimes(), elu: performance.eventLoopUtilization(), net: networkBytes() };
112
+
113
+ function sample() {
114
+ const now = { at: performance.now(), cpu: process.cpuUsage(), system: cpuTimes(), elu: performance.eventLoopUtilization(), net: networkBytes() };
115
+ const elapsedMs = Math.max(1, now.at - last.at);
116
+ const cores = info.cpus || 1;
117
+ const processCpu = ((now.cpu.user - last.cpu.user + now.cpu.system - last.cpu.system) / 1000 / elapsedMs / cores) * 100;
118
+ const systemTotal = now.system.total - last.system.total;
119
+ const systemCpu = systemTotal > 0 ? (1 - (now.system.idle - last.system.idle) / systemTotal) * 100 : undefined;
120
+ const elu = performance.eventLoopUtilization(now.elu, last.elu).utilization * 100;
121
+ const memory = process.memoryUsage();
122
+ const free = os.freemem();
123
+ const [load1, load5, load15] = os.loadavg();
124
+ const space = disk(cwd);
125
+ const values = {
126
+ process_cpu: round(Math.min(100, Math.max(0, processCpu))),
127
+ system_cpu: round(systemCpu),
128
+ rss: memory.rss,
129
+ heap_used: memory.heapUsed,
130
+ heap_total: memory.heapTotal,
131
+ external: memory.external,
132
+ system_memory_used: os.totalmem() - free,
133
+ event_loop_p50: round(ms(delay.percentile(50))),
134
+ event_loop_p99: round(ms(delay.percentile(99))),
135
+ event_loop_max: round(ms(delay.max)),
136
+ event_loop_utilization: round(elu),
137
+ gc_count: gcCount,
138
+ gc_pause: round(gcPause),
139
+ handles: typeof process.getActiveResourcesInfo === 'function' ? process.getActiveResourcesInfo().length : undefined,
140
+ ...(info.platform === 'win32' ? {} : { load_1: round(load1), load_5: round(load5), load_15: round(load15) }),
141
+ ...(space ? { disk_total: space.total, disk_used: space.total - space.free } : {}),
142
+ uptime: Math.round(process.uptime()),
143
+ };
144
+ if (now.net && last.net) {
145
+ values.network_rx = round(Math.max(0, now.net.rx - last.net.rx) / (elapsedMs / 1000), 0);
146
+ values.network_tx = round(Math.max(0, now.net.tx - last.net.tx) / (elapsedMs / 1000), 0);
147
+ }
148
+ for (const key of Object.keys(values)) if (values[key] === undefined) delete values[key];
149
+ delay.reset();
150
+ gcCount = 0;
151
+ gcPause = 0;
152
+ last = now;
153
+ return values;
154
+ }
155
+
156
+ return { info, sample, stop: () => { delay.disable(); gc?.disconnect(); } };
157
+ }
158
+
159
+ /** Samples every `interval` seconds and sends the samples to TraceLumo in batches. */
160
+ function startMetrics({ metricsUrl, token, service, metricsInterval }, options) {
161
+ const sampler = createSampler({ service });
162
+ const instance = randomUUID();
163
+ const queue = createQueue({ url: metricsUrl, token, maxBatch: 100, kind: 'metrics', interval: SEND_EVERY }, options);
164
+ const record = () => {
165
+ try {
166
+ queue.push({ instance, timestamp: new Date().toISOString(), info: sampler.info, values: sampler.sample() });
167
+ } catch {
168
+ // Metrics must never break the application.
169
+ }
170
+ };
171
+ const timer = setInterval(record, metricsInterval * 1000);
172
+ timer.unref();
173
+ return {
174
+ flush: queue.flush,
175
+ async close() {
176
+ clearInterval(timer);
177
+ record();
178
+ sampler.stop();
179
+ await queue.close();
180
+ },
181
+ };
182
+ }
183
+
184
+ module.exports = { createSampler, startMetrics, hostInfo, runtime };