@tracelumo/node 0.4.0 → 0.6.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
@@ -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`.
@@ -64,8 +65,44 @@ Logs are batched (up to 100 per request, sent every second) and capped at 8 KiB
64
65
  **System metrics:** every 15 seconds the SDK records the process's CPU, memory (RSS, heap), event loop delay and
65
66
  utilization, garbage collection pauses and open handles, plus the machine's CPU, memory, load average, disk and (on
66
67
  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.
68
+ built-ins inside your app: no agent or extra process. The first sample is taken 5 seconds after start and each sample is
69
+ sent right away, so serverless functions (Vercel, AWS Lambda), which pause between requests, report while they run. The
70
+ timers never keep your process alive.
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
+
78
+ **Containers (Docker, Kubernetes, ECS, Fargate):** inside a container, Node.js reports the host's CPUs and memory, so
79
+ the SDK also reads the container's own cgroup (v2, or v1 on older nodes). It reports:
80
+ - CPU against the container's limit, and CPU throttling.
81
+ - Working-set memory against the memory limit, out-of-memory kills, and the number of processes.
82
+
83
+ It also detects where it runs:
84
+ - Docker and Podman.
85
+ - Kubernetes on EKS (including EKS on Fargate), AKS and GKE, with namespace, pod and container ID.
86
+ - ECS on EC2 or Fargate, with cluster, task, task definition and availability zone, from the ECS task metadata endpoint.
87
+ - Cloud Run, Azure Container Apps and App Service.
88
+
89
+ Kubernetes doesn't tell a pod its cluster or node name. To show them, add these to the container's `env`:
90
+
91
+ ```yaml
92
+ env:
93
+ - name: CLUSTER_NAME
94
+ value: production
95
+ - name: NODE_NAME
96
+ valueFrom: { fieldRef: { fieldPath: spec.nodeName } }
97
+ ```
98
+
99
+ The SDK measures the process it runs in and its container. Containers that don't run the SDK, and cluster-wide
100
+ numbers such as every node's capacity, need a cluster-level collector, because nothing inside one container can
101
+ see them.
102
+
103
+ **Service name on serverless:** Vercel and similar platforms usually deploy without `package.json`, so the SDK names the
104
+ service after the deployment (for example `studio.naar.io`). Set `TRACELUMO_SERVICE_NAME` in the platform's environment
105
+ variables to choose the name yourself. They appear on the project's **Infrastructure** page, one row per running instance.
69
106
 
70
107
  ## Lifecycle hooks
71
108
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@tracelumo/node",
3
- "version": "0.4.0",
3
+ "version": "0.6.0",
4
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",
package/src/config.cjs CHANGED
@@ -13,9 +13,11 @@ function readIfPresent(path) {
13
13
  }
14
14
  }
15
15
 
16
- function appName(cwd) {
16
+ function appName(cwd, environment = process.env) {
17
17
  const manifest = readIfPresent(resolve(cwd, 'package.json'));
18
- if (!manifest) return 'node-app';
18
+ // Serverless platforms often deploy without package.json; name the service after the deployment instead.
19
+ const deployed = environment.VERCEL_PROJECT_PRODUCTION_URL || environment.AWS_LAMBDA_FUNCTION_NAME || environment.K_SERVICE;
20
+ if (!manifest) return typeof deployed === 'string' && deployed.trim() ? deployed.trim().slice(0, 128) : 'node-app';
19
21
  const name = JSON.parse(manifest)?.name;
20
22
  return typeof name === 'string' && name.trim() ? name : 'node-app';
21
23
  }
@@ -49,7 +51,7 @@ function configuration(options = {}, cwd = process.cwd(), environment = process.
49
51
 
50
52
  const endpoint = options.endpoint ?? setting('TRACELUMO_OTLP_ENDPOINT');
51
53
  const token = (options.token ?? setting('TRACELUMO_AGENT_TOKEN') ?? '').trim();
52
- const service = (options.serviceName ?? setting('TRACELUMO_SERVICE_NAME') ?? appName(cwd)).trim();
54
+ const service = (options.serviceName ?? setting('TRACELUMO_SERVICE_NAME') ?? appName(cwd, environment)).trim();
53
55
  if (!endpoint || !token) throw new Error('Set TRACELUMO_OTLP_ENDPOINT and TRACELUMO_AGENT_TOKEN.');
54
56
  if (!/^tl_agent_[A-Za-z0-9_-]{23,119}$/.test(token)) {
55
57
  throw new Error('TRACELUMO_AGENT_TOKEN must be an active project agent token.');
@@ -63,10 +65,13 @@ function configuration(options = {}, cwd = process.cwd(), environment = process.
63
65
  // Seconds between metric samples: 15 by default, 5 to 300.
64
66
  const requested = Number(options.metricsInterval ?? setting('TRACELUMO_METRICS_INTERVAL') ?? 15);
65
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;
66
71
  const base = url.replace(/\/v1\/traces$/, '');
67
72
  return {
68
73
  url, logsUrl: `${base}/v1/ingest/logs`, errorsUrl: `${base}/v1/ingest/errors`, metricsUrl: `${base}/v1/ingest/metrics`,
69
- token, service, logs, metrics, metricsInterval,
74
+ heartbeatUrl: `${base}/v1/ingest/heartbeat`, token, service, logs, metrics, metricsInterval, heartbeatInterval,
70
75
  };
71
76
  }
72
77
 
@@ -0,0 +1,243 @@
1
+ 'use strict';
2
+
3
+ const { existsSync, readFileSync } = require('node:fs');
4
+ const http = require('node:http');
5
+ const { join } = require('node:path');
6
+
7
+ /**
8
+ * Container awareness, from inside the container with no agent:
9
+ * - cgroup v2 (and v1 on older nodes) for the container's own CPU and memory use, its limits, CPU throttling,
10
+ * out-of-memory kills and process count. Inside a container, Node's `os` module reports the host, so these are
11
+ * the numbers that matter.
12
+ * - Where it runs: Docker, Kubernetes (EKS, AKS, GKE, EKS on Fargate), ECS (EC2 or Fargate), Cloud Run, Azure
13
+ * Container Apps and App Service, with cluster, namespace, pod, node, task and container ID when available.
14
+ */
15
+
16
+ const read = (path) => {
17
+ try {
18
+ return readFileSync(path, 'utf8').trim();
19
+ } catch {
20
+ return null;
21
+ }
22
+ };
23
+ const int = (text) => {
24
+ const value = Number(text);
25
+ return Number.isFinite(value) ? value : null;
26
+ };
27
+ /** `key value` lines, as in cpu.stat and memory.stat. */
28
+ function stats(text) {
29
+ const result = {};
30
+ for (const line of (text ?? '').split('\n')) {
31
+ const [key, value] = line.trim().split(/\s+/);
32
+ if (key && value !== undefined && Number.isFinite(Number(value))) result[key] = Number(value);
33
+ }
34
+ return result;
35
+ }
36
+ // Anything at or above this is "no limit" in cgroup v1.
37
+ const UNLIMITED = 2 ** 60;
38
+
39
+ /**
40
+ * Finds this process's cgroup. Returns a reader for the raw counters, or null when there is none (not Linux).
41
+ * `root` and `self` can point at a copy of /sys/fs/cgroup and /proc/self/cgroup for tests.
42
+ */
43
+ function createCgroup({ root = '/sys/fs/cgroup', self = '/proc/self/cgroup' } = {}) {
44
+ const lines = (read(self) ?? '').split('\n').filter(Boolean).map((line) => {
45
+ const [, controllers = '', path = '/'] = line.match(/^\d+:([^:]*):(.*)$/) ?? [];
46
+ return { controllers: controllers.split(','), path };
47
+ });
48
+ if (lines.length === 0) return null;
49
+ // The process's own directory when visible, otherwise the mount root (with a cgroup namespace they are the same).
50
+ const pick = (base, path, probe) => [join(base, path), base].find((dir) => existsSync(join(dir, probe))) ?? null;
51
+
52
+ const unified = lines.find((line) => line.controllers.length === 1 && line.controllers[0] === '');
53
+ if (unified && existsSync(join(root, 'cgroup.controllers'))) {
54
+ const dir = pick(root, unified.path, 'cpu.stat');
55
+ if (!dir) return null;
56
+ return {
57
+ version: 2,
58
+ read() {
59
+ const cpu = stats(read(join(dir, 'cpu.stat')));
60
+ const [quota, period] = (read(join(dir, 'cpu.max')) ?? 'max').split(/\s+/);
61
+ const memoryMax = read(join(dir, 'memory.max'));
62
+ const memory = stats(read(join(dir, 'memory.stat')));
63
+ const current = int(read(join(dir, 'memory.current')));
64
+ return {
65
+ cpuUsec: cpu.usage_usec ?? null,
66
+ periods: cpu.nr_periods ?? null,
67
+ throttled: cpu.nr_throttled ?? null,
68
+ throttledUsec: cpu.throttled_usec ?? null,
69
+ cpuLimit: quota && quota !== 'max' && int(quota) > 0 && int(period) > 0 ? int(quota) / int(period) : null,
70
+ memory: current,
71
+ // Working set, as Kubernetes counts it: usage minus inactive file cache, which the kernel can reclaim.
72
+ workingSet: current === null ? null : Math.max(0, current - (memory.inactive_file ?? 0)),
73
+ memoryLimit: memoryMax && memoryMax !== 'max' ? int(memoryMax) : null,
74
+ oomKills: stats(read(join(dir, 'memory.events'))).oom_kill ?? null,
75
+ pids: int(read(join(dir, 'pids.current'))),
76
+ };
77
+ },
78
+ };
79
+ }
80
+
81
+ const controller = (name) => lines.find((line) => line.controllers.includes(name));
82
+ const dirFor = (name, mounts, probe) => {
83
+ const line = controller(name);
84
+ if (!line) return null;
85
+ for (const mount of mounts) {
86
+ const dir = pick(join(root, mount), line.path, probe);
87
+ if (dir) return dir;
88
+ }
89
+ return null;
90
+ };
91
+ const cpuDir = dirFor('cpu', ['cpu,cpuacct', 'cpu', 'cpuacct,cpu'], 'cpu.cfs_period_us');
92
+ const acctDir = dirFor('cpuacct', ['cpu,cpuacct', 'cpuacct', 'cpuacct,cpu'], 'cpuacct.usage');
93
+ const memDir = dirFor('memory', ['memory'], 'memory.usage_in_bytes');
94
+ const pidsDir = dirFor('pids', ['pids'], 'pids.current');
95
+ if (!cpuDir && !acctDir && !memDir) return null;
96
+ return {
97
+ version: 1,
98
+ read() {
99
+ const cpu = cpuDir ? stats(read(join(cpuDir, 'cpu.stat'))) : {};
100
+ const quota = cpuDir ? int(read(join(cpuDir, 'cpu.cfs_quota_us'))) : null;
101
+ const period = cpuDir ? int(read(join(cpuDir, 'cpu.cfs_period_us'))) : null;
102
+ const usageNs = acctDir ? int(read(join(acctDir, 'cpuacct.usage'))) : null;
103
+ const usage = memDir ? int(read(join(memDir, 'memory.usage_in_bytes'))) : null;
104
+ const limit = memDir ? int(read(join(memDir, 'memory.limit_in_bytes'))) : null;
105
+ const memory = memDir ? stats(read(join(memDir, 'memory.stat'))) : {};
106
+ const oom = memDir ? stats(read(join(memDir, 'memory.oom_control'))) : {};
107
+ return {
108
+ cpuUsec: usageNs === null ? null : usageNs / 1000,
109
+ periods: cpu.nr_periods ?? null,
110
+ throttled: cpu.nr_throttled ?? null,
111
+ throttledUsec: cpu.throttled_time === undefined ? null : cpu.throttled_time / 1000,
112
+ cpuLimit: quota !== null && quota > 0 && period ? quota / period : null,
113
+ memory: usage,
114
+ workingSet: usage === null ? null : Math.max(0, usage - (memory.total_inactive_file ?? memory.inactive_file ?? 0)),
115
+ memoryLimit: limit !== null && limit < UNLIMITED ? limit : null,
116
+ oomKills: oom.oom_kill ?? null,
117
+ pids: pidsDir ? int(read(join(pidsDir, 'pids.current'))) : null,
118
+ };
119
+ },
120
+ };
121
+ }
122
+
123
+ /** Container metrics for one interval, from two cgroup readings `elapsedMs` apart. */
124
+ function containerValues(previous, current, elapsedMs, hostCpus) {
125
+ if (!current) return {};
126
+ const values = {};
127
+ const limit = current.cpuLimit ?? hostCpus;
128
+ if (previous?.cpuUsec != null && current.cpuUsec != null) {
129
+ const cores = Math.max(0, current.cpuUsec - previous.cpuUsec) / 1000 / elapsedMs;
130
+ values.container_cpu_cores = Number(cores.toFixed(3));
131
+ if (limit) values.container_cpu = Number(Math.min(100, (cores / limit) * 100).toFixed(2));
132
+ }
133
+ if (previous?.periods != null && current.periods != null && current.throttled != null && previous.throttled != null) {
134
+ const periods = current.periods - previous.periods;
135
+ values.cpu_throttled = periods > 0 ? Number((((current.throttled - previous.throttled) / periods) * 100).toFixed(2)) : 0;
136
+ }
137
+ if (previous?.throttledUsec != null && current.throttledUsec != null) {
138
+ values.cpu_throttled_time = Number((Math.max(0, current.throttledUsec - previous.throttledUsec) / 1000).toFixed(1));
139
+ }
140
+ if (current.workingSet != null) values.container_memory = current.workingSet;
141
+ if (current.memoryLimit != null && current.workingSet != null) {
142
+ values.container_memory_pct = Number(((current.workingSet / current.memoryLimit) * 100).toFixed(2));
143
+ }
144
+ if (previous?.oomKills != null && current.oomKills != null) values.oom_kills = Math.max(0, current.oomKills - previous.oomKills);
145
+ if (current.pids != null) values.pids = current.pids;
146
+ return values;
147
+ }
148
+
149
+ /** The container ID (12 characters), from the cgroup path or the mount table. */
150
+ function containerId({ self = '/proc/self/cgroup', mountinfo = '/proc/self/mountinfo' } = {}) {
151
+ const fromCgroup = (read(self) ?? '').match(/[0-9a-f]{64}/);
152
+ if (fromCgroup) return fromCgroup[0].slice(0, 12);
153
+ // cgroup v2 with a namespace hides the path; Docker and containerd still mount /etc/hostname from the container's folder.
154
+ const fromMounts = (read(mountinfo) ?? '').match(/\/(?:containers|sandboxes)\/([0-9a-f]{64})\//);
155
+ return fromMounts ? fromMounts[1].slice(0, 12) : undefined;
156
+ }
157
+
158
+ /** Which cloud the machine belongs to, from its firmware (readable inside most containers). */
159
+ function cloudVendor(dmi = '/sys/class/dmi/id') {
160
+ const text = `${read(join(dmi, 'sys_vendor')) ?? ''} ${read(join(dmi, 'board_vendor')) ?? ''} ${read(join(dmi, 'product_name')) ?? ''}`.toLowerCase();
161
+ if (/amazon|ec2/.test(text)) return 'aws';
162
+ if (/microsoft/.test(text)) return 'azure';
163
+ if (/google/.test(text)) return 'gcp';
164
+ return undefined;
165
+ }
166
+
167
+ /** Where this process runs, with orchestration details. Synchronous; ECS details are added by `ecsDetails`. */
168
+ function platform({ env = process.env, files = {} } = {}) {
169
+ const exists = (path) => existsSync(files[path] ?? path);
170
+ const text = (path) => read(files[path] ?? path);
171
+ const cloud = env.AWS_REGION || env.AWS_DEFAULT_REGION || env.AWS_EXECUTION_ENV ? 'aws'
172
+ : cloudVendor(files.dmi);
173
+ const region = env.AWS_REGION || env.AWS_DEFAULT_REGION || env.REGION_NAME || env.AZURE_REGION || undefined;
174
+ const id = containerId({ self: files['/proc/self/cgroup'], mountinfo: files['/proc/self/mountinfo'] });
175
+
176
+ if (env.VERCEL) return { runtime: 'vercel', cloud: 'vercel', region: env.VERCEL_REGION };
177
+ if (env.AWS_LAMBDA_FUNCTION_NAME) return { runtime: 'aws-lambda', cloud: 'aws', region };
178
+ if (env.ECS_CONTAINER_METADATA_URI_V4 || env.ECS_CONTAINER_METADATA_URI) {
179
+ // Fargate or EC2 is known once the task metadata answers; Fargate sets AWS_EXECUTION_ENV.
180
+ const fargate = env.AWS_EXECUTION_ENV === 'AWS_ECS_FARGATE';
181
+ return { runtime: fargate ? 'ecs-fargate' : 'ecs', cloud: 'aws', region, container_id: id };
182
+ }
183
+ if (env.KUBERNETES_SERVICE_HOST) {
184
+ const node = env.NODE_NAME || env.K8S_NODE_NAME || env.KUBE_NODE_NAME || env.MY_NODE_NAME || undefined;
185
+ const provider = cloud === 'aws' ? 'eks' : cloud === 'azure' ? 'aks' : cloud === 'gcp' ? 'gke' : 'kubernetes';
186
+ return {
187
+ runtime: provider === 'eks' && node?.startsWith('fargate-') ? 'eks-fargate' : provider,
188
+ cloud, region,
189
+ cluster: env.CLUSTER_NAME || env.TRACELUMO_CLUSTER || env.EKS_CLUSTER_NAME || env.AKS_CLUSTER_NAME || undefined,
190
+ namespace: env.POD_NAMESPACE || text('/var/run/secrets/kubernetes.io/serviceaccount/namespace') || undefined,
191
+ pod: env.POD_NAME || env.HOSTNAME || undefined,
192
+ // "node" is the Node.js version, so the Kubernetes node is k8s_node.
193
+ k8s_node: node,
194
+ container_id: id,
195
+ };
196
+ }
197
+ if (env.K_SERVICE) return { runtime: 'cloud-run', cloud: 'gcp', service_revision: env.K_REVISION, container_id: id };
198
+ if (env.CONTAINER_APP_NAME) return { runtime: 'azure-container-apps', cloud: 'azure', region, container_id: id };
199
+ if (env.WEBSITE_SITE_NAME) return { runtime: 'azure-app-service', cloud: 'azure', region: env.REGION_NAME, container_id: id };
200
+ if (exists('/run/.containerenv')) return { runtime: 'podman', cloud, region, container_id: id };
201
+ if (exists('/.dockerenv') || id) return { runtime: 'docker', cloud, region, container_id: id };
202
+ return { runtime: 'host', cloud, region };
203
+ }
204
+
205
+ /** ECS task details from the task metadata endpoint (local to the task, answered in milliseconds). */
206
+ function ecsDetails(env = process.env, suppress = (fn) => fn()) {
207
+ const base = env.ECS_CONTAINER_METADATA_URI_V4 || env.ECS_CONTAINER_METADATA_URI;
208
+ if (!base) return Promise.resolve(null);
209
+ const get = (url) => new Promise((resolve) => {
210
+ suppress(() => {
211
+ const request = http.get(url, { timeout: 2000 }, (response) => {
212
+ let body = '';
213
+ response.setEncoding('utf8');
214
+ response.on('data', (chunk) => { body += chunk; });
215
+ response.on('end', () => {
216
+ try {
217
+ resolve(response.statusCode === 200 ? JSON.parse(body) : null);
218
+ } catch {
219
+ resolve(null);
220
+ }
221
+ });
222
+ });
223
+ request.on('timeout', () => request.destroy());
224
+ request.on('error', () => resolve(null));
225
+ });
226
+ });
227
+ return Promise.all([get(`${base}/task`), get(base)]).then(([task, container]) => {
228
+ if (!task) return null;
229
+ const arn = String(task.TaskARN ?? '');
230
+ const cluster = String(task.Cluster ?? '').split('/').pop();
231
+ return {
232
+ runtime: task.LaunchType === 'FARGATE' ? 'ecs-fargate' : 'ecs',
233
+ cluster: cluster || undefined,
234
+ task: arn.split('/').pop() || undefined,
235
+ task_family: task.Family ? `${task.Family}:${task.Revision ?? ''}`.replace(/:$/, '') : undefined,
236
+ zone: task.AvailabilityZone || undefined,
237
+ container: container?.Name || undefined,
238
+ container_id: container?.DockerId ? String(container.DockerId).slice(0, 12) : undefined,
239
+ };
240
+ });
241
+ }
242
+
243
+ module.exports = { createCgroup, containerValues, containerId, cloudVendor, platform, ecsDetails, stats };
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
@@ -1,32 +1,36 @@
1
1
  'use strict';
2
2
 
3
3
  const { randomUUID } = require('node:crypto');
4
- const { existsSync, readFileSync, statfsSync } = require('node:fs');
4
+ const { readFileSync, statfsSync } = require('node:fs');
5
5
  const os = require('node:os');
6
6
  const { monitorEventLoopDelay, performance, PerformanceObserver } = require('node:perf_hooks');
7
+ const { containerValues, createCgroup, ecsDetails, platform } = require('./container.cjs');
7
8
  const { createQueue } = require('./logs.cjs');
9
+ const http = require('node:http');
10
+ const https = require('node:https');
8
11
 
9
12
  /**
10
13
  * System and runtime metrics, collected inside the application with Node.js built-ins only — no agent, no extra
11
14
  * process, no dependencies. Every interval it records one sample: process CPU and memory, heap, event loop delay
12
15
  * 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.
16
+ * network. Each sample is sent within a second, so serverless functions (which pause between requests) report
17
+ * while they run. The timers never keep the process alive.
14
18
  */
15
19
 
16
- const SEND_EVERY = 30_000;
20
+ // The first sample comes soon after start, so short-lived and serverless processes report too.
21
+ const FIRST_SAMPLE = 5_000;
17
22
  const round = (value, digits = 2) => (Number.isFinite(value) ? Number(value.toFixed(digits)) : undefined);
18
23
  const ms = (ns) => ns / 1e6;
19
24
 
20
- /** Where the process runs, so the dashboard can explain what the machine numbers mean. */
25
+ /** Where the process runs (see container.cjs), so the dashboard can explain what the machine numbers mean. */
21
26
  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';
27
+ return platform({ env }).runtime;
28
28
  }
29
29
 
30
+ // Platforms where the process has its own cgroup with its own limits.
31
+ const NOT_CONTAINERS = new Set(['host', 'vercel', 'aws-lambda']);
32
+ const defined = (object) => Object.fromEntries(Object.entries(object).filter(([, value]) => value !== undefined && value !== null && value !== ''));
33
+
30
34
  /** Facts about the machine and process that rarely change. */
31
35
  function hostInfo(service) {
32
36
  const cpus = os.cpus();
@@ -44,7 +48,7 @@ function hostInfo(service) {
44
48
  ...(limit > 0 && limit < os.totalmem() ? { memory_limit: limit } : {}),
45
49
  node: process.version,
46
50
  pid: process.pid,
47
- runtime: runtime(),
51
+ ...defined(platform()),
48
52
  started: new Date(Date.now() - process.uptime() * 1000).toISOString(),
49
53
  };
50
54
  }
@@ -90,8 +94,16 @@ function disk(path) {
90
94
  }
91
95
 
92
96
  /** Measures one process. `sample()` returns the values since the previous call. */
93
- function createSampler({ service, cwd = process.cwd() } = {}) {
97
+ function createSampler({ service, cwd = process.cwd(), cgroup } = {}) {
94
98
  const info = hostInfo(service);
99
+ // Inside a container, the container's own CPU and memory (and their limits) come from its cgroup.
100
+ const group = cgroup !== undefined ? cgroup : NOT_CONTAINERS.has(info.runtime) ? null : createCgroup();
101
+ let lastGroup = group?.read() ?? null;
102
+ const limits = (reading) => {
103
+ if (reading?.cpuLimit) info.cpu_limit = Number(reading.cpuLimit.toFixed(3));
104
+ if (reading?.memoryLimit) info.memory_limit = reading.memoryLimit;
105
+ };
106
+ limits(lastGroup);
95
107
  const delay = monitorEventLoopDelay({ resolution: 20 });
96
108
  delay.enable();
97
109
  let gcCount = 0;
@@ -141,6 +153,12 @@ function createSampler({ service, cwd = process.cwd() } = {}) {
141
153
  ...(space ? { disk_total: space.total, disk_used: space.total - space.free } : {}),
142
154
  uptime: Math.round(process.uptime()),
143
155
  };
156
+ if (group) {
157
+ const reading = group.read();
158
+ Object.assign(values, containerValues(lastGroup, reading, elapsedMs, info.cpus));
159
+ limits(reading);
160
+ lastGroup = reading;
161
+ }
144
162
  if (now.net && last.net) {
145
163
  values.network_rx = round(Math.max(0, now.net.rx - last.net.rx) / (elapsedMs / 1000), 0);
146
164
  values.network_tx = round(Math.max(0, now.net.tx - last.net.tx) / (elapsedMs / 1000), 0);
@@ -153,14 +171,90 @@ function createSampler({ service, cwd = process.cwd() } = {}) {
153
171
  return values;
154
172
  }
155
173
 
156
- return { info, sample, stop: () => { delay.disable(); gc?.disconnect(); } };
174
+ // The heartbeat's quick reading: CPU, memory and event loop use since the previous beat. It keeps its own
175
+ // baseline, so it doesn't disturb the full samples.
176
+ let lastBeat = { at: performance.now(), cpu: process.cpuUsage(), elu: performance.eventLoopUtilization(), group: lastGroup };
177
+ function beat() {
178
+ const now = { at: performance.now(), cpu: process.cpuUsage(), elu: performance.eventLoopUtilization(), group: group?.read() ?? null };
179
+ const elapsedMs = Math.max(1, now.at - lastBeat.at);
180
+ const cpu = ((now.cpu.user - lastBeat.cpu.user + now.cpu.system - lastBeat.cpu.system) / 1000 / elapsedMs / (info.cpus || 1)) * 100;
181
+ const memory = process.memoryUsage();
182
+ const values = {
183
+ process_cpu: round(Math.min(100, Math.max(0, cpu))),
184
+ rss: memory.rss,
185
+ heap_used: memory.heapUsed,
186
+ event_loop_utilization: round(performance.eventLoopUtilization(now.elu, lastBeat.elu).utilization * 100),
187
+ uptime: Math.round(process.uptime()),
188
+ };
189
+ if (group) {
190
+ const container = containerValues(lastBeat.group, now.group, elapsedMs, info.cpus);
191
+ for (const key of ['container_cpu', 'container_cpu_cores', 'container_memory', 'container_memory_pct']) {
192
+ if (container[key] !== undefined) values[key] = container[key];
193
+ }
194
+ }
195
+ lastBeat = now;
196
+ return values;
197
+ }
198
+
199
+ return { info, sample, beat, stop: () => { delay.disable(); gc?.disconnect(); } };
157
200
  }
158
201
 
159
202
  /** Samples every `interval` seconds and sends the samples to TraceLumo in batches. */
160
- function startMetrics({ metricsUrl, token, service, metricsInterval }, options) {
203
+ /**
204
+ * A heartbeat every `seconds`: a tiny request with the instance's current CPU and memory, so the dashboard shows
205
+ * it online and current within a second. One kept-alive connection, never more than one request at a time, no
206
+ * retries (the next beat replaces a lost one). It stops for good if the server doesn't know heartbeats (an older
207
+ * TraceLumo) or rejects the token.
208
+ */
209
+ function startHeartbeat({ heartbeatUrl, token }, { instance, sampler, seconds, suppress }) {
210
+ const target = new URL(heartbeatUrl);
211
+ const transport = target.protocol === 'https:' ? https : http;
212
+ const agent = new transport.Agent({ keepAlive: true, maxSockets: 1 });
213
+ let busy = false;
214
+ let stopped = false;
215
+ const send = () => {
216
+ if (busy || stopped) return;
217
+ let body;
218
+ try {
219
+ body = JSON.stringify({
220
+ instance, timestamp: new Date().toISOString(), every: seconds,
221
+ service: sampler.info.service, hostname: sampler.info.hostname, values: sampler.beat(),
222
+ });
223
+ } catch {
224
+ return;
225
+ }
226
+ busy = true;
227
+ suppress(() => {
228
+ const request = transport.request(target, {
229
+ method: 'POST', agent, timeout: 4000,
230
+ headers: { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(body), Authorization: `Bearer ${token}` },
231
+ }, (response) => {
232
+ if (response.statusCode === 404 || response.statusCode === 401 || response.statusCode === 403) stopped = true;
233
+ response.resume();
234
+ response.on('end', () => { busy = false; });
235
+ response.on('error', () => { busy = false; });
236
+ });
237
+ request.on('timeout', () => request.destroy());
238
+ request.on('error', () => { busy = false; });
239
+ request.end(body);
240
+ });
241
+ };
242
+ const timer = setInterval(send, seconds * 1000);
243
+ timer.unref();
244
+ return () => {
245
+ clearInterval(timer);
246
+ agent.destroy();
247
+ };
248
+ }
249
+
250
+ function startMetrics({ metricsUrl, heartbeatUrl, token, service, metricsInterval, heartbeatInterval = 0 }, options) {
161
251
  const sampler = createSampler({ service });
162
252
  const instance = randomUUID();
163
- const queue = createQueue({ url: metricsUrl, token, maxBatch: 100, kind: 'metrics', interval: SEND_EVERY }, options);
253
+ // On ECS, the task metadata endpoint adds the cluster, task, launch type (EC2 or Fargate) and zone.
254
+ ecsDetails(process.env, options.suppress).then((details) => {
255
+ if (details) Object.assign(sampler.info, defined(details));
256
+ }).catch(() => {});
257
+ const queue = createQueue({ url: metricsUrl, token, maxBatch: 100, kind: 'metrics' }, options);
164
258
  const record = () => {
165
259
  try {
166
260
  queue.push({ instance, timestamp: new Date().toISOString(), info: sampler.info, values: sampler.sample() });
@@ -168,11 +262,18 @@ function startMetrics({ metricsUrl, token, service, metricsInterval }, options)
168
262
  // Metrics must never break the application.
169
263
  }
170
264
  };
265
+ const first = setTimeout(record, Math.min(FIRST_SAMPLE, metricsInterval * 1000));
266
+ first.unref();
171
267
  const timer = setInterval(record, metricsInterval * 1000);
172
268
  timer.unref();
269
+ const stopHeartbeat = heartbeatInterval > 0 && heartbeatUrl
270
+ ? startHeartbeat({ heartbeatUrl, token }, { instance, sampler, seconds: heartbeatInterval, suppress: options.suppress })
271
+ : () => {};
173
272
  return {
174
273
  flush: queue.flush,
175
274
  async close() {
275
+ stopHeartbeat();
276
+ clearTimeout(first);
176
277
  clearInterval(timer);
177
278
  record();
178
279
  sampler.stop();
@@ -181,4 +282,4 @@ function startMetrics({ metricsUrl, token, service, metricsInterval }, options)
181
282
  };
182
283
  }
183
284
 
184
- module.exports = { createSampler, startMetrics, hostInfo, runtime };
285
+ module.exports = { createSampler, startMetrics, startHeartbeat, hostInfo, runtime, defined };