@tracelumo/node 0.5.0 → 0.6.2
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 +7 -0
- package/package.json +1 -1
- package/src/config.cjs +4 -1
- package/src/index.d.cts +2 -0
- package/src/metrics.cjs +104 -6
package/README.md
CHANGED
|
@@ -55,6 +55,7 @@ NODE_OPTIONS="--require @tracelumo/node/register" npm run dev
|
|
|
55
55
|
| `TRACELUMO_LOGS` | `true` | Set to `false` to stop sending console output as logs and errors. |
|
|
56
56
|
| `TRACELUMO_METRICS` | `true` | Set to `false` to stop sending system metrics. |
|
|
57
57
|
| `TRACELUMO_METRICS_INTERVAL` | `15` | Seconds between metric samples (5 to 300). |
|
|
58
|
+
| `TRACELUMO_HEARTBEAT_INTERVAL` | `1` | Seconds between heartbeats (1 to 60); `0` turns them off. |
|
|
58
59
|
| `TRACELUMO_ENABLED` | `true` | Set to `false` to turn the SDK off. |
|
|
59
60
|
|
|
60
61
|
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`.
|
|
@@ -68,6 +69,12 @@ built-ins inside your app: no agent or extra process. The first sample is taken
|
|
|
68
69
|
sent right away, so serverless functions (Vercel, AWS Lambda), which pause between requests, report while they run. The
|
|
69
70
|
timers never keep your process alive.
|
|
70
71
|
|
|
72
|
+
**Heartbeat:** every second the SDK also sends a tiny heartbeat with the current CPU, memory and event loop use. The
|
|
73
|
+
Infrastructure page shows each instance online and current within a second. Heartbeats reuse one connection, never
|
|
74
|
+
overlap, update the instance in place (they add no rows to the database), and stop if the server doesn't support them.
|
|
75
|
+
On serverless platforms each heartbeat is a function call to TraceLumo; raise `TRACELUMO_HEARTBEAT_INTERVAL` (for
|
|
76
|
+
example to `5`) if that matters for your plan.
|
|
77
|
+
|
|
71
78
|
**Containers (Docker, Kubernetes, ECS, Fargate):** inside a container, Node.js reports the host's CPUs and memory, so
|
|
72
79
|
the SDK also reads the container's own cgroup (v2, or v1 on older nodes). It reports:
|
|
73
80
|
- CPU against the container's limit, and CPU throttling.
|
package/package.json
CHANGED
package/src/config.cjs
CHANGED
|
@@ -65,10 +65,13 @@ function configuration(options = {}, cwd = process.cwd(), environment = process.
|
|
|
65
65
|
// Seconds between metric samples: 15 by default, 5 to 300.
|
|
66
66
|
const requested = Number(options.metricsInterval ?? setting('TRACELUMO_METRICS_INTERVAL') ?? 15);
|
|
67
67
|
const metricsInterval = Number.isFinite(requested) ? Math.min(300, Math.max(5, Math.round(requested))) : 15;
|
|
68
|
+
// Seconds between heartbeats: 1 by default, up to 60; 0 turns them off (metrics samples still go out).
|
|
69
|
+
const beat = Number(options.heartbeatInterval ?? setting('TRACELUMO_HEARTBEAT_INTERVAL') ?? 1);
|
|
70
|
+
const heartbeatInterval = Number.isFinite(beat) ? (beat <= 0 ? 0 : Math.min(60, Math.max(1, Math.round(beat)))) : 1;
|
|
68
71
|
const base = url.replace(/\/v1\/traces$/, '');
|
|
69
72
|
return {
|
|
70
73
|
url, logsUrl: `${base}/v1/ingest/logs`, errorsUrl: `${base}/v1/ingest/errors`, metricsUrl: `${base}/v1/ingest/metrics`,
|
|
71
|
-
token, service, logs, metrics, metricsInterval,
|
|
74
|
+
heartbeatUrl: `${base}/v1/ingest/heartbeat`, token, service, logs, metrics, metricsInterval, heartbeatInterval,
|
|
72
75
|
};
|
|
73
76
|
}
|
|
74
77
|
|
package/src/index.d.cts
CHANGED
|
@@ -9,6 +9,8 @@ export interface TracingOptions {
|
|
|
9
9
|
metrics?: boolean;
|
|
10
10
|
/** Seconds between metric samples, 5 to 300. Defaults to 15 (TRACELUMO_METRICS_INTERVAL). */
|
|
11
11
|
metricsInterval?: number;
|
|
12
|
+
/** Seconds between heartbeats (current CPU and memory, online status), 1 to 60; 0 turns them off. Defaults to 1 (TRACELUMO_HEARTBEAT_INTERVAL). */
|
|
13
|
+
heartbeatInterval?: number;
|
|
12
14
|
}
|
|
13
15
|
|
|
14
16
|
export function start(options?: TracingOptions): void;
|
package/src/metrics.cjs
CHANGED
|
@@ -6,6 +6,8 @@ const os = require('node:os');
|
|
|
6
6
|
const { monitorEventLoopDelay, performance, PerformanceObserver } = require('node:perf_hooks');
|
|
7
7
|
const { containerValues, createCgroup, ecsDetails, platform } = require('./container.cjs');
|
|
8
8
|
const { createQueue } = require('./logs.cjs');
|
|
9
|
+
const http = require('node:http');
|
|
10
|
+
const https = require('node:https');
|
|
9
11
|
|
|
10
12
|
/**
|
|
11
13
|
* System and runtime metrics, collected inside the application with Node.js built-ins only — no agent, no extra
|
|
@@ -120,7 +122,8 @@ function createSampler({ service, cwd = process.cwd(), cgroup } = {}) {
|
|
|
120
122
|
}
|
|
121
123
|
let last = { at: performance.now(), cpu: process.cpuUsage(), system: cpuTimes(), elu: performance.eventLoopUtilization(), net: networkBytes() };
|
|
122
124
|
|
|
123
|
-
|
|
125
|
+
/** One sample. `paused`: the process was suspended (serverless between requests), so delay readings are void. */
|
|
126
|
+
function sample({ paused = false } = {}) {
|
|
124
127
|
const now = { at: performance.now(), cpu: process.cpuUsage(), system: cpuTimes(), elu: performance.eventLoopUtilization(), net: networkBytes() };
|
|
125
128
|
const elapsedMs = Math.max(1, now.at - last.at);
|
|
126
129
|
const cores = info.cpus || 1;
|
|
@@ -161,6 +164,13 @@ function createSampler({ service, cwd = process.cwd(), cgroup } = {}) {
|
|
|
161
164
|
values.network_rx = round(Math.max(0, now.net.rx - last.net.rx) / (elapsedMs / 1000), 0);
|
|
162
165
|
values.network_tx = round(Math.max(0, now.net.tx - last.net.tx) / (elapsedMs / 1000), 0);
|
|
163
166
|
}
|
|
167
|
+
// A paused process (Vercel and Lambda freeze functions between requests) records the whole pause as event loop
|
|
168
|
+
// delay when it resumes. That's not a delay the app had, so leave those readings out.
|
|
169
|
+
if (paused) {
|
|
170
|
+
delete values.event_loop_p50;
|
|
171
|
+
delete values.event_loop_p99;
|
|
172
|
+
delete values.event_loop_max;
|
|
173
|
+
}
|
|
164
174
|
for (const key of Object.keys(values)) if (values[key] === undefined) delete values[key];
|
|
165
175
|
delay.reset();
|
|
166
176
|
gcCount = 0;
|
|
@@ -169,11 +179,89 @@ function createSampler({ service, cwd = process.cwd(), cgroup } = {}) {
|
|
|
169
179
|
return values;
|
|
170
180
|
}
|
|
171
181
|
|
|
172
|
-
|
|
182
|
+
// The heartbeat's quick reading: CPU, memory and event loop use since the previous beat. It keeps its own
|
|
183
|
+
// baseline, so it doesn't disturb the full samples.
|
|
184
|
+
let lastBeat = { at: performance.now(), cpu: process.cpuUsage(), elu: performance.eventLoopUtilization(), group: lastGroup };
|
|
185
|
+
function beat() {
|
|
186
|
+
const now = { at: performance.now(), cpu: process.cpuUsage(), elu: performance.eventLoopUtilization(), group: group?.read() ?? null };
|
|
187
|
+
const elapsedMs = Math.max(1, now.at - lastBeat.at);
|
|
188
|
+
const cpu = ((now.cpu.user - lastBeat.cpu.user + now.cpu.system - lastBeat.cpu.system) / 1000 / elapsedMs / (info.cpus || 1)) * 100;
|
|
189
|
+
const memory = process.memoryUsage();
|
|
190
|
+
const values = {
|
|
191
|
+
process_cpu: round(Math.min(100, Math.max(0, cpu))),
|
|
192
|
+
rss: memory.rss,
|
|
193
|
+
heap_used: memory.heapUsed,
|
|
194
|
+
event_loop_utilization: round(performance.eventLoopUtilization(now.elu, lastBeat.elu).utilization * 100),
|
|
195
|
+
uptime: Math.round(process.uptime()),
|
|
196
|
+
};
|
|
197
|
+
if (group) {
|
|
198
|
+
const container = containerValues(lastBeat.group, now.group, elapsedMs, info.cpus);
|
|
199
|
+
for (const key of ['container_cpu', 'container_cpu_cores', 'container_memory', 'container_memory_pct']) {
|
|
200
|
+
if (container[key] !== undefined) values[key] = container[key];
|
|
201
|
+
}
|
|
202
|
+
}
|
|
203
|
+
lastBeat = now;
|
|
204
|
+
return values;
|
|
205
|
+
}
|
|
206
|
+
|
|
207
|
+
return { info, sample, beat, stop: () => { delay.disable(); gc?.disconnect(); } };
|
|
173
208
|
}
|
|
174
209
|
|
|
175
210
|
/** Samples every `interval` seconds and sends the samples to TraceLumo in batches. */
|
|
176
|
-
|
|
211
|
+
/**
|
|
212
|
+
* A heartbeat every `seconds`: a tiny request with the instance's current CPU and memory, so the dashboard shows
|
|
213
|
+
* it online and current within a second. One kept-alive connection, never more than one request at a time, no
|
|
214
|
+
* retries (the next beat replaces a lost one). It stops for good if the server doesn't know heartbeats (an older
|
|
215
|
+
* TraceLumo) or rejects the token.
|
|
216
|
+
*/
|
|
217
|
+
function startHeartbeat({ heartbeatUrl, token }, { instance, sampler, seconds, suppress }) {
|
|
218
|
+
const target = new URL(heartbeatUrl);
|
|
219
|
+
const transport = target.protocol === 'https:' ? https : http;
|
|
220
|
+
const agent = new transport.Agent({ keepAlive: true, maxSockets: 1 });
|
|
221
|
+
let busy = false;
|
|
222
|
+
let stopped = false;
|
|
223
|
+
let beats = 0;
|
|
224
|
+
const send = () => {
|
|
225
|
+
if (busy || stopped) return;
|
|
226
|
+
let body;
|
|
227
|
+
try {
|
|
228
|
+
// The first beat (and every 30th) carries the instance's details, so even a function that lives only a few
|
|
229
|
+
// seconds shows its platform and runtime.
|
|
230
|
+
const withInfo = beats % 30 === 0;
|
|
231
|
+
beats += 1;
|
|
232
|
+
body = JSON.stringify({
|
|
233
|
+
instance, timestamp: new Date().toISOString(), every: seconds,
|
|
234
|
+
service: sampler.info.service, hostname: sampler.info.hostname, values: sampler.beat(),
|
|
235
|
+
...(withInfo ? { info: sampler.info } : {}),
|
|
236
|
+
});
|
|
237
|
+
} catch {
|
|
238
|
+
return;
|
|
239
|
+
}
|
|
240
|
+
busy = true;
|
|
241
|
+
suppress(() => {
|
|
242
|
+
const request = transport.request(target, {
|
|
243
|
+
method: 'POST', agent, timeout: 4000,
|
|
244
|
+
headers: { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(body), Authorization: `Bearer ${token}` },
|
|
245
|
+
}, (response) => {
|
|
246
|
+
if (response.statusCode === 404 || response.statusCode === 401 || response.statusCode === 403) stopped = true;
|
|
247
|
+
response.resume();
|
|
248
|
+
response.on('end', () => { busy = false; });
|
|
249
|
+
response.on('error', () => { busy = false; });
|
|
250
|
+
});
|
|
251
|
+
request.on('timeout', () => request.destroy());
|
|
252
|
+
request.on('error', () => { busy = false; });
|
|
253
|
+
request.end(body);
|
|
254
|
+
});
|
|
255
|
+
};
|
|
256
|
+
const timer = setInterval(send, seconds * 1000);
|
|
257
|
+
timer.unref();
|
|
258
|
+
return () => {
|
|
259
|
+
clearInterval(timer);
|
|
260
|
+
agent.destroy();
|
|
261
|
+
};
|
|
262
|
+
}
|
|
263
|
+
|
|
264
|
+
function startMetrics({ metricsUrl, heartbeatUrl, token, service, metricsInterval, heartbeatInterval = 0 }, options) {
|
|
177
265
|
const sampler = createSampler({ service });
|
|
178
266
|
const instance = randomUUID();
|
|
179
267
|
// On ECS, the task metadata endpoint adds the cluster, task, launch type (EC2 or Fargate) and zone.
|
|
@@ -181,20 +269,30 @@ function startMetrics({ metricsUrl, token, service, metricsInterval }, options)
|
|
|
181
269
|
if (details) Object.assign(sampler.info, defined(details));
|
|
182
270
|
}).catch(() => {});
|
|
183
271
|
const queue = createQueue({ url: metricsUrl, token, maxBatch: 100, kind: 'metrics' }, options);
|
|
272
|
+
// Serverless functions may live only seconds, so their first full sample comes after one second.
|
|
273
|
+
const firstSample = NOT_CONTAINERS.has(sampler.info.runtime) && sampler.info.runtime !== 'host' ? 1000 : Math.min(FIRST_SAMPLE, metricsInterval * 1000);
|
|
274
|
+
// When the sample timer fires far later than planned, the process was paused rather than busy.
|
|
275
|
+
let due = Date.now() + firstSample;
|
|
184
276
|
const record = () => {
|
|
185
277
|
try {
|
|
186
|
-
|
|
278
|
+
const late = Date.now() - due;
|
|
279
|
+
due = Date.now() + metricsInterval * 1000;
|
|
280
|
+
queue.push({ instance, timestamp: new Date().toISOString(), info: sampler.info, values: sampler.sample({ paused: late > Math.max(2000, metricsInterval * 500) }) });
|
|
187
281
|
} catch {
|
|
188
282
|
// Metrics must never break the application.
|
|
189
283
|
}
|
|
190
284
|
};
|
|
191
|
-
const first = setTimeout(record,
|
|
285
|
+
const first = setTimeout(record, firstSample);
|
|
192
286
|
first.unref();
|
|
193
287
|
const timer = setInterval(record, metricsInterval * 1000);
|
|
194
288
|
timer.unref();
|
|
289
|
+
const stopHeartbeat = heartbeatInterval > 0 && heartbeatUrl
|
|
290
|
+
? startHeartbeat({ heartbeatUrl, token }, { instance, sampler, seconds: heartbeatInterval, suppress: options.suppress })
|
|
291
|
+
: () => {};
|
|
195
292
|
return {
|
|
196
293
|
flush: queue.flush,
|
|
197
294
|
async close() {
|
|
295
|
+
stopHeartbeat();
|
|
198
296
|
clearTimeout(first);
|
|
199
297
|
clearInterval(timer);
|
|
200
298
|
record();
|
|
@@ -204,4 +302,4 @@ function startMetrics({ metricsUrl, token, service, metricsInterval }, options)
|
|
|
204
302
|
};
|
|
205
303
|
}
|
|
206
304
|
|
|
207
|
-
module.exports = { createSampler, startMetrics, hostInfo, runtime, defined };
|
|
305
|
+
module.exports = { createSampler, startMetrics, startHeartbeat, hostInfo, runtime, defined };
|