@watchtowerobservability/node 0.7.4 → 0.7.5
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/CHANGELOG.md +36 -1
- package/README.md +96 -12
- package/dist/cjs/attach.d.ts +7 -0
- package/dist/cjs/attach.js +29 -0
- package/dist/cjs/checkin.js +4 -13
- package/dist/cjs/cron/monitor.d.ts +47 -0
- package/dist/cjs/cron/monitor.js +95 -0
- package/dist/cjs/cron/schedulers.d.ts +36 -0
- package/dist/cjs/cron/schedulers.js +65 -0
- package/dist/cjs/env.d.ts +10 -0
- package/dist/cjs/env.js +98 -1
- package/dist/cjs/index.d.ts +50 -6
- package/dist/cjs/index.js +114 -37
- package/dist/cjs/instrument-for.d.ts +17 -0
- package/dist/cjs/instrument-for.js +44 -0
- package/dist/cjs/instrument.d.ts +4 -0
- package/dist/cjs/instrument.js +32 -1
- package/dist/cjs/integrations/bullmq.d.ts +8 -2
- package/dist/cjs/integrations/bullmq.js +32 -5
- package/dist/cjs/integrations/db.d.ts +7 -2
- package/dist/cjs/integrations/db.js +32 -4
- package/dist/cjs/integrations/fastify.d.ts +1 -1
- package/dist/cjs/integrations/fastify.js +3 -2
- package/dist/cjs/integrations/logs.js +16 -5
- package/dist/cjs/integrations/next-build.d.ts +25 -8
- package/dist/cjs/integrations/next-build.js +159 -34
- package/dist/cjs/integrations/next-tunnel.d.ts +6 -1
- package/dist/cjs/integrations/next-tunnel.js +13 -2
- package/dist/cjs/integrations/postgres.d.ts +2 -0
- package/dist/cjs/integrations/postgres.js +43 -1
- package/dist/cjs/integrations/temporal.d.ts +97 -0
- package/dist/cjs/integrations/temporal.js +144 -0
- package/dist/cjs/integrations/util.d.ts +17 -0
- package/dist/cjs/integrations/util.js +38 -0
- package/dist/cjs/load.d.ts +6 -0
- package/dist/cjs/load.js +28 -4
- package/dist/cjs/next-doctor-cli.d.ts +2 -0
- package/dist/cjs/next-doctor-cli.js +15 -0
- package/dist/cjs/next-doctor.d.ts +2 -0
- package/dist/cjs/next-doctor.js +50 -0
- package/dist/cjs/redact-presets.d.ts +16 -0
- package/dist/cjs/redact-presets.js +66 -0
- package/dist/cjs/register.js +19 -6
- package/dist/cjs/version.d.ts +1 -1
- package/dist/cjs/version.js +1 -1
- package/dist/esm/attach.d.ts +7 -0
- package/dist/esm/attach.js +25 -0
- package/dist/esm/checkin.js +4 -13
- package/dist/esm/cron/monitor.d.ts +47 -0
- package/dist/esm/cron/monitor.js +85 -0
- package/dist/esm/cron/schedulers.d.ts +36 -0
- package/dist/esm/cron/schedulers.js +61 -0
- package/dist/esm/env.d.ts +10 -0
- package/dist/esm/env.js +62 -0
- package/dist/esm/index.d.ts +50 -6
- package/dist/esm/index.js +109 -39
- package/dist/esm/instrument-for.d.ts +17 -0
- package/dist/esm/instrument-for.js +41 -0
- package/dist/esm/instrument.d.ts +4 -0
- package/dist/esm/instrument.js +30 -1
- package/dist/esm/integrations/bullmq.d.ts +8 -2
- package/dist/esm/integrations/bullmq.js +32 -5
- package/dist/esm/integrations/db.d.ts +7 -2
- package/dist/esm/integrations/db.js +29 -4
- package/dist/esm/integrations/fastify.d.ts +1 -1
- package/dist/esm/integrations/fastify.js +4 -3
- package/dist/esm/integrations/logs.js +16 -5
- package/dist/esm/integrations/next-build.d.ts +25 -8
- package/dist/esm/integrations/next-build.js +158 -34
- package/dist/esm/integrations/next-tunnel.d.ts +6 -1
- package/dist/esm/integrations/next-tunnel.js +13 -2
- package/dist/esm/integrations/postgres.d.ts +2 -0
- package/dist/esm/integrations/postgres.js +43 -2
- package/dist/esm/integrations/temporal.d.ts +97 -0
- package/dist/esm/integrations/temporal.js +139 -0
- package/dist/esm/integrations/util.d.ts +17 -0
- package/dist/esm/integrations/util.js +35 -0
- package/dist/esm/load.d.ts +6 -0
- package/dist/esm/load.js +21 -3
- package/dist/esm/next-doctor-cli.d.ts +2 -0
- package/dist/esm/next-doctor-cli.js +13 -0
- package/dist/esm/next-doctor.d.ts +2 -0
- package/dist/esm/next-doctor.js +14 -0
- package/dist/esm/redact-presets.d.ts +16 -0
- package/dist/esm/redact-presets.js +58 -0
- package/dist/esm/register.js +20 -7
- package/dist/esm/version.d.ts +1 -1
- package/dist/esm/version.js +1 -1
- package/package.json +42 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,6 +1,41 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
-
##
|
|
3
|
+
## 0.7.5 (2026-11-15)
|
|
4
|
+
|
|
5
|
+
- Telemetry that is off is now visible: the `register` preload prints `[watchtower] telemetry is OFF: <reason>` when `WT_INGEST_KEY` is unset or the SDK cannot start, and the first helper call that is dropped (`log`, `observe`, `checkin` ...) prints it once more with the reason.
|
|
6
|
+
- `tsx` / `ts-node`: the preload's ESM hook skips `.ts`/`.tsx` sources, which it used to re-parse as JavaScript, printing an `Error:` per file.
|
|
7
|
+
- The `register` preload and peer loader search the SDK location, then the cwd, then the entry script's directory (pnpm monorepos). README: use `node --import .../register`, not `NODE_OPTIONS=--import`.
|
|
8
|
+
- `log`, `observe`, `checkIn`, `checkin`, `withMonitor`, `getPrompt`, `score`, `evaluate` are no-ops before `init()` (no throw); `observe` and `withMonitor` still run the function.
|
|
9
|
+
- New `/temporal`: `temporalInterceptors()` (activity spans, final-attempt failure capture) and `watchTemporalSchedules(client)` (Schedule check-ins, slug `temporal-<scheduleId>`).
|
|
10
|
+
- New `/tunnel` subpath for `tunnelHandler` (framework-neutral); `/next` still re-exports it.
|
|
11
|
+
|
|
12
|
+
- Privacy: log bridges (`pinoStream`, `watchtowerTransport`) flatten nested objects into dotted attributes (`req.url`, `req.remoteAddress`, depth 4; arrays of primitives stay arrays, deeper values are JSON strings). `redact(key, value)` now also runs per leaf with the leaf name (after the dotted key), so a hook on `url` or `remoteAddress` fires and the `strict`/`pii` presets see the leaves; URL scrubbing applies to `*.url` / `*.uri` / `*.target` log attributes. Behavior change: `user: {id: 1}` is now `user.id` = 1, not the JSON string `user`.
|
|
13
|
+
- `init` logs one warning naming OpenTelemetry peers that cannot be loaded, with the Next standalone fix. New `wt-next-doctor [dir]` bin: reports SDK peers missing from `.next/standalone/node_modules` (npm and pnpm layouts), exit 1.
|
|
14
|
+
- `/fastify` plugin enriches the active http-instrumentation server span (name, `http.route`, status) instead of starting a second server span; without one it still makes its own.
|
|
15
|
+
- README: postgres.js >= 4, Fastify plugin with http instrumentation, `captureProcessErrors`, Next standalone recipe.
|
|
16
|
+
|
|
17
|
+
- Check-ins go to the edge host (`ingest.x` becomes `edge.x`; `WT_CHECKIN_URL` overrides) because the ingest gateway has no `/v1/checkins` route. They are fire and forget with a 5 s cap and never throw; `wt.checkin()` still awaits. New `checkIn(slug, status, { wait, durationMs })`.
|
|
18
|
+
- `withMonitor(slug, fn, { schedule, timezone, checkinMargin, maxRuntime, failureThreshold, wait })`: `in_progress`, then `ok`/`error` with the duration; the schedule goes in the check-in body as `monitor_config` so the server can create the monitor. Its own HTTP call is not traced.
|
|
19
|
+
- `instrumentNestSchedule(registry)` (`@nestjs/schedule` `@Cron` jobs) and `instrumentNodeCron(cron)` run each named job as a monitor.
|
|
20
|
+
- `instrumentBullMQ(bullmq, { captureFailures, cronMonitors })`: final-attempt failures become errors with queue, job name and id, attempt, attempts; repeatable jobs become cron monitors.
|
|
21
|
+
- `redact: 'strict' | 'pii' | 'off'` (default `'strict'`): secret-shaped attribute keys become `[redacted]` on spans, events, logs; `pii` also masks emails, phones, Luhn cards and IPs; `off` also disables URL scrubbing. A function still works and runs after the `strict` preset (behaviour change: `authorization`, `cookie`, `password`, `token` ... string attributes are now redacted by default).
|
|
22
|
+
- `otel: 'auto' | 'own' | 'attach'` (default `'auto'`): when another library (Sentry) already registered the global tracer provider, the exporter is attached to it as a span processor and our context manager and propagator are not installed.
|
|
23
|
+
- `init()` result carries `traces`, `metrics`, `logs`, `blocked`, `warnings` (type `InitStatus`).
|
|
24
|
+
- New `instrument(name)` for `nest`, `express`, `next`, `bullmq`, `pg`, `postgres`, `ioredis`. node:http server spans are renamed `METHOD /route/:param` from the matched Express/Nest route (`WT_ROUTE_NAMES=0` to opt out).
|
|
25
|
+
- Release also falls back to `WT_BUILD_STAMP` / `BUILD_STAMP`, then to the `.git/HEAD` commit found upward from the working directory (no child process).
|
|
26
|
+
- Counter `wt.sdk.db.dropped_spans` and a one-time warning when `requireParent` drops a datastore span; `droppedDbSpans()`.
|
|
27
|
+
- README: "Keys: which key goes where" table.
|
|
28
|
+
|
|
29
|
+
- `tunnelHandler` forwards the visitor's `Origin` and `Referer` (and `x-wt-sdk`, `x-wt-mask`) to the edge, so a browser key no longer gets 403 `origin_not_allowed` through the tunnel; add your site's origin to the key's allowed origins. A same-origin GET without `Origin` gets the `Referer`'s origin. New `allowKey` option (string or list): beacons whose `?k=` / `wtp_` bearer is not listed get 403.
|
|
30
|
+
- `withWatchtower(config, opts)` now makes `output: 'standalone'` work with no other config: the node SDK and its OpenTelemetry peers are added to `serverExternalPackages` and (npm and pnpm layouts) `outputFileTracingIncludes`; `NEXT_PUBLIC_WT_RELEASE` is set from `opts.release` or the CI git sha. `sourcemaps` also takes `{ upload: true, deleteAfterUpload: true, ... }`: the webpack client build uploads `.next/static/**/*.map` (bundle route, 429 honored) and deletes them. Turbopack: keep `wt-next-sourcemaps`.
|
|
31
|
+
- New subpath exports `@watchtowerobservability/node/next-build` and `/next-tunnel` (no SDK import; used by `@watchtowerobservability/next`).
|
|
32
|
+
- `service.version` also falls back to the first set of `GITHUB_SHA`, `CI_COMMIT_SHA`, `VERCEL_GIT_COMMIT_SHA`, `SOURCE_VERSION`, `BUILD_SHA`, `RENDER_GIT_COMMIT`, `HEROKU_SLUG_COMMIT` (after `release`, `WT_RELEASE` and `OTEL_RESOURCE_ATTRIBUTES`; empty and `unknown` are ignored).
|
|
33
|
+
- Behaviour change: datastore `requireParent` now defaults to true only when HTTP server instrumentation is active, so queue workers (BullMQ) record their queries as root spans. `WATCHTOWER_DB_REQUIRE_PARENT=0/1` still overrides.
|
|
34
|
+
- `instrumentPostgres()` logs one warning when `postgres` is installed but `diagnostics_channel.tracingChannel` is unavailable (needs `postgres@>=4`).
|
|
35
|
+
|
|
36
|
+
## 0.7.5
|
|
37
|
+
|
|
38
|
+
- `wt-next-sourcemaps` / `uploadSourcemaps()` send the maps in one `POST /v1/projects/{prj}/artifacts/bundle?release=` request per ~120 MB (tar.gz plus a manifest) instead of one request per map. A server without the bundle route is detected and the batch falls back to the concurrent, gzipped single uploads (429/5xx retried with backoff). The final line is still `{uploaded, skipped, failed}`; a failed map is logged with its reason. Re-posting the same bytes returns 200 and counts as `skipped`.
|
|
4
39
|
|
|
5
40
|
## 0.7.4
|
|
6
41
|
|
package/README.md
CHANGED
|
@@ -30,7 +30,7 @@ wt.init({ apiKey: process.env.WT_INGEST_KEY, project: process.env.WT_PROJECT_ID,
|
|
|
30
30
|
|
|
31
31
|
```ts
|
|
32
32
|
import * as wt from '@watchtowerobservability/node'; // or: const wt = require('@watchtowerobservability/node');
|
|
33
|
-
wt.init({}); // WT_INGEST_KEY, WT_SERVICE, WT_ENVIRONMENT, WT_RELEASE from env
|
|
33
|
+
wt.init({}); // WT_INGEST_KEY, WT_SERVICE, WT_ENVIRONMENT, WT_RELEASE from env (release also falls back to the CI commit sha: GITHUB_SHA, CI_COMMIT_SHA, VERCEL_GIT_COMMIT_SHA, ...)
|
|
34
34
|
const traceId = wt.captureException(new Error('oops')); // also: uncaught errors and unhandled rejections
|
|
35
35
|
wt.log('info', 'started', { port: 3000 }); // OTLP log, linked to the active trace
|
|
36
36
|
```
|
|
@@ -50,10 +50,27 @@ Pass `urlScrubbing: false` to record URLs as the instrumentation produced them.
|
|
|
50
50
|
(`@opentelemetry/instrumentation-mysql2`) is installed, and prints one line (`[watchtower] instrumented: http, undici, pg, better-sqlite3`);
|
|
51
51
|
silence it with `instrumentLog: false` or `WT_INSTRUMENT_LOG=0`.
|
|
52
52
|
|
|
53
|
+
Start the preload in the start command: `node --import @watchtowerobservability/node/register app.js` (or `node -r ...` for CommonJS).
|
|
54
|
+
Do not use `NODE_OPTIONS=--import ...`: it leaks into healthchecks and `pnpm` itself, which cannot resolve the package from the image root.
|
|
55
|
+
OpenTelemetry peers are looked up from the SDK's location, then the working directory, then the directory of the entry script, so in a pnpm
|
|
56
|
+
monorepo the app that runs the script is enough.
|
|
57
|
+
|
|
53
58
|
`wt.checkin('nightly-report', async () => { ... })` wraps a cron or scheduler job in check-ins to the monitor with that slug
|
|
54
59
|
(`in_progress`, then `ok` or `error` with the duration; the key needs scope `ingest:checkins`; the edge accepts 6 a minute per monitor;
|
|
55
60
|
failed check-ins never affect the job).
|
|
56
61
|
|
|
62
|
+
## Cron monitors and check-ins
|
|
63
|
+
|
|
64
|
+
Check-ins go to the edge host (`ingest.example.net` becomes `edge.example.net`; set `WT_CHECKIN_URL` to override) and need the `ingest:checkins` key scope. The edge accepts 6 a minute per monitor.
|
|
65
|
+
|
|
66
|
+
- `checkIn('nightly-report', 'ok', { durationMs })`: one check-in. Fire and forget with a 5 s cap, never throws; add `wait: true` to await it (short-lived processes).
|
|
67
|
+
- `withMonitor('nightly-report', async () => {...}, { schedule: '0 3 * * *', timezone: 'UTC', checkinMargin: 5, maxRuntime: 30, failureThreshold: 2 })` sends `in_progress`, then `ok` or `error` with the duration, returns your result and rethrows your error. The schedule is sent as `monitor_config` so the monitor is created or updated on first check-in. A 6-field cron with `0` seconds is sent as 5 fields. Its own request is not traced.
|
|
68
|
+
- Nest: after `app.init()`, `instrumentNestSchedule(app.get(SchedulerRegistry))`. Every `@Cron(expr, { name: 'Nightly Report' })` job becomes the monitor `nightly-report` with its expression and timezone. Name your jobs: unnamed ones get a uuid and are skipped.
|
|
69
|
+
- node-cron: `import cron from 'node-cron'; instrumentNodeCron(cron)` before scheduling; `cron.schedule(expr, fn, { name: 'sync-users' })` (or a named function) becomes a monitor.
|
|
70
|
+
- BullMQ: `instrumentBullMQ(bullmq, { captureFailures: true, cronMonitors: true })`. `captureFailures` reports a job's last failed attempt as an error (attributes `bullmq.queue`, `bullmq.job.name`, `bullmq.job.id`, `bullmq.job.attempt`, `bullmq.job.attempts_made`, `bullmq.job.attempts`); `cronMonitors` runs repeatable jobs (`repeat.pattern`) as monitors named `<queue>-<job name>`.
|
|
71
|
+
|
|
72
|
+
Set `captureProcessErrors: false` when your app already drains and exits on `uncaughtException` / `unhandledRejection`, so the two handlers do not race. The process error hooks (`captureProcessErrors`, default true) report `uncaughtException` and `unhandledRejection` and then exit with code 1 (after a 2 s flush) only when the SDK is the sole listener for that event; if your app or framework registers its own, the SDK only reports and leaves the exit to you.
|
|
73
|
+
|
|
57
74
|
`init` patches `node:http`, `fetch` (undici), `pg` and `ioredis` for each `@opentelemetry/instrumentation-*` package you have installed (the list above); pass `instrument: false` or set `WT_INSTRUMENT=0` to skip. Patching only reaches modules loaded after it runs, so load the SDK first:
|
|
58
75
|
|
|
59
76
|
```sh
|
|
@@ -82,9 +99,9 @@ spans and errored spans are always kept; children of a dropped internal span sta
|
|
|
82
99
|
**Source maps.** `next.config.js`: `module.exports = withWatchtower(nextConfig, { sourcemaps: true })` (from
|
|
83
100
|
`@watchtowerobservability/node/next`) turns on `productionBrowserSourceMaps`. Build with
|
|
84
101
|
`"build": "next build && wt-next-sourcemaps"`: the `wt-next-sourcemaps` bin (or `uploadSourcemaps()`) uploads every `.map` under
|
|
85
|
-
`.next/static` as `_next/static/<path>` for release `$WT_RELEASE` (
|
|
102
|
+
`.next/static` as `_next/static/<path>` for release `$WT_RELEASE` (the upload creates the release when it does not exist; it must equal
|
|
86
103
|
the browser SDK's `release`), with `$WT_API_KEY` and `$WT_PROJECT` (and `$WT_API_URL`, default `https://watchtowerops.net`; the old `$WT_API` still works with a warning), then deletes the `.map` files so they are
|
|
87
|
-
never served.
|
|
104
|
+
never served. Maps go up in one `POST /artifacts/bundle` request (a tar.gz plus manifest; about 120 MB per request) and fall back to single uploads, 8 at a time, when the server has no bundle route. Requests retry 429/5xx with backoff (honoring `Retry-After`) and continue past failures; the run prints `{uploaded, skipped, failed}` (`skipped`: the server already had the same bytes, HTTP 200) and exits 1 when any failed, leaving the files. Each map is sent with `for=<chunk path>` read from the chunk's `//# sourceMappingURL=` comment or the map's `file` field. A wrong host fails at once with a message naming it. Bodies are sent gzipped. **Key scope: `ci:write`** (it covers releases and
|
|
88
105
|
artifacts; `admin:write` also works). Ingest keys cannot upload. Turbopack and webpack both emit these maps; Next does not inject
|
|
89
106
|
debug ids, so maps match by release and file name.
|
|
90
107
|
|
|
@@ -99,7 +116,9 @@ registered it re-sends the signal so the exit is unchanged. Under `next start`,
|
|
|
99
116
|
the server and calls `process.exit`; our flush starts first (the `register` hook runs before) and gets the time the server takes
|
|
100
117
|
to close, so a very slow export can still be cut.
|
|
101
118
|
|
|
102
|
-
Install the OpenTelemetry peers above in the app itself (with pnpm, as direct dependencies). The SDK loads peers at run time through `createRequire`, which webpack does not follow, so a build prints no "Module not found" warning for peers you did not install. Next's standalone file tracer does not follow them either
|
|
119
|
+
Install the OpenTelemetry peers above in the app itself (with pnpm, as direct dependencies). The SDK loads peers at run time through `createRequire`, which webpack does not follow, so a build prints no "Module not found" warning for peers you did not install. Next's standalone file tracer does not follow them either.
|
|
120
|
+
|
|
121
|
+
Standalone recipe: wrap the config, `module.exports = withWatchtower(nextConfig)` (from `@watchtowerobservability/node/next-build`, or `@watchtowerobservability/next`). It adds the SDK and its OpenTelemetry peers to `serverExternalPackages` and `outputFileTracingIncludes` (npm and pnpm layouts). By hand, add the same packages to `serverExternalPackages` and `outputFileTracingIncludes: { '/*': ['./node_modules/@opentelemetry/**', './node_modules/@watchtowerobservability/node/**'] }`. If a peer is missing at run time, `init` logs one warning naming it; after `next build`, `npx wt-next-doctor` lists what `.next/standalone/node_modules` lacks and exits 1.
|
|
103
122
|
|
|
104
123
|
Bundling with esbuild or webpack (ESM or CommonJS output) works without warnings; mark the peers you use as externals (or ship `node_modules`), because they are resolved at run time. Declarations name optional peers behind `// @ts-ignore`, so `skipLibCheck: false` builds compile without them installed.
|
|
105
124
|
|
|
@@ -110,7 +129,7 @@ Each lives at its own subpath, so nothing is loaded that you do not import.
|
|
|
110
129
|
| Integration | Import | Use |
|
|
111
130
|
| --- | --- | --- |
|
|
112
131
|
| Express | `@watchtowerobservability/node/express` | `app.use(requestHandler())` first, `app.use(errorHandler())` last |
|
|
113
|
-
| Fastify | `.../fastify` | `await app.register(plugin)
|
|
132
|
+
| Fastify | `.../fastify` | `await app.register(plugin)`; use it or the plain http instrumentation, or both: with the http instrumentation active the plugin enriches its server span (route, status) instead of starting a second one |
|
|
114
133
|
| Koa | `.../koa` | `app.use(middleware())` first |
|
|
115
134
|
| NestJS | `.../nestjs` | `app.useGlobalInterceptors(new WatchtowerInterceptor())` (add express or fastify integration for spans) |
|
|
116
135
|
| Next.js server | `.../next` | `instrumentation.js`: `module.exports = require('@watchtowerobservability/node/next')` (exports `register`, `onRequestError`) |
|
|
@@ -171,9 +190,24 @@ messaging conventions: `messaging.system=bullmq`, `messaging.destination.name`,
|
|
|
171
190
|
Sandboxed processors (a file path instead of a function) run in a child process and get no consumer
|
|
172
191
|
span.
|
|
173
192
|
|
|
193
|
+
### Temporal
|
|
194
|
+
|
|
195
|
+
```ts
|
|
196
|
+
import { temporalInterceptors, watchTemporalSchedules } from '@watchtowerobservability/node/temporal';
|
|
197
|
+
const worker = await Worker.create({ /* ... */, interceptors: temporalInterceptors() }); // activity spans; failures captured on the final attempt
|
|
198
|
+
const stop = watchTemporalSchedules(client, { interval: 60_000 }); // Schedule check-ins
|
|
199
|
+
```
|
|
200
|
+
|
|
201
|
+
Activity spans carry `temporal.activity.type`, `temporal.attempt`, `temporal.workflow.id`. An activity failure becomes an error only on its final
|
|
202
|
+
attempt (a non-retryable failure, or `attempt >= maximumAttempts`; pass `temporalInterceptors({ maxAttempts })` when the activity info has no retry policy).
|
|
203
|
+
Workflow code runs in Temporal's sandbox, so nothing is injected there. `watchTemporalSchedules` lists schedules, describes each, and checks every
|
|
204
|
+
action's workflow: `in_progress` while running, `ok` when it completed, `error` when it failed, timed out, was terminated or cancelled. Each action is
|
|
205
|
+
reported once. The slug is `temporal-<scheduleId>` and `monitor_config` carries the cron when the spec is a cron expression or one calendar.
|
|
206
|
+
`@temporalio/*` is not imported by the SDK; you pass your own client. `namespaces` limits watching to those client namespaces.
|
|
207
|
+
|
|
174
208
|
### postgres.js
|
|
175
209
|
|
|
176
|
-
postgres.js has no OTel instrumentation; from 4.0 it publishes every query on the `postgres:query`
|
|
210
|
+
Needs postgres.js >= 4 for query spans (the tracing channel); on 3.x `instrumentPostgres()` records nothing and the SDK logs a warning. postgres.js has no OTel instrumentation; from 4.0 it publishes every query on the `postgres:query`
|
|
177
211
|
diagnostics tracing channel. `instrumentPostgres()` subscribes to it and records a CLIENT span per
|
|
178
212
|
query, child of the active span: `db.system=postgresql`, `db.operation.name`, `db.namespace`,
|
|
179
213
|
`server.address`/`server.port`, `db.query.summary` (operation and first table, e.g.
|
|
@@ -195,11 +229,13 @@ server and spans join the Datastores views. The algorithm is specified in
|
|
|
195
229
|
DDL summaries name the table: `CREATE TABLE IF NOT EXISTS forms` is `CREATE TABLE forms`, `CREATE [UNIQUE] INDEX x ON forms` is
|
|
196
230
|
`CREATE INDEX forms` (TEMP and VIRTUAL tables too).
|
|
197
231
|
|
|
198
|
-
**`requireParent
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
232
|
+
**`requireParent`:** defaults to true when node:http server instrumentation is active (a query is recorded only under a
|
|
233
|
+
request, job or `observe` span; startup DDL, migrations and polling loops would otherwise each become a root trace), and to
|
|
234
|
+
false otherwise. In a queue worker (BullMQ, pg-boss) with no HTTP server there are no request spans, so queries are recorded as
|
|
235
|
+
root spans. It applies to every datastore integration and postgres.js through the shared `DbOptions`; pass `{ requireParent }`
|
|
236
|
+
or set `WATCHTOWER_DB_REQUIRE_PARENT=0/1` to force either way. To see a background loop in an HTTP app, wrap it in
|
|
237
|
+
`observe('poll', fn)`. `instrumentPostgres()` needs `postgres@>=4` on a Node with `diagnostics_channel.tracingChannel`; otherwise
|
|
238
|
+
it records nothing and logs one warning.
|
|
203
239
|
|
|
204
240
|
Statement text and parameters are never recorded by default. Pass `{ queryText: true }` (or set
|
|
205
241
|
`WATCHTOWER_DB_QUERY_TEXT=1`) to add `db.query.text`, which is then the literal-free text. A
|
|
@@ -304,6 +340,19 @@ with `error.type`; the error message is not recorded.
|
|
|
304
340
|
|
|
305
341
|
- **kafkajs**: upstream `@opentelemetry/instrumentation-kafkajs` already covers it.
|
|
306
342
|
|
|
343
|
+
### Browser tunnel without Next
|
|
344
|
+
|
|
345
|
+
`tunnelHandler` takes a standard `Request` and returns a `Response`, so it works in any fetch-handler framework (TanStack Start, Remix, Hono, ...):
|
|
346
|
+
|
|
347
|
+
```ts
|
|
348
|
+
import { tunnelHandler } from '@watchtowerobservability/node/tunnel';
|
|
349
|
+
const { GET, POST } = tunnelHandler({ endpoint: process.env.WT_EDGE_URL!, basePath: '/api/wt' });
|
|
350
|
+
// TanStack Start: createFileRoute('/api/wt/$')({ server: { handlers: { GET: ({ request }) => GET(request), POST: ({ request }) => POST(request) } } })
|
|
351
|
+
// Hono: app.all('/api/wt/*', (c) => (c.req.method === 'GET' ? GET : POST)(c.req.raw))
|
|
352
|
+
```
|
|
353
|
+
|
|
354
|
+
`@watchtowerobservability/node/next` still re-exports it.
|
|
355
|
+
|
|
307
356
|
## Profiling
|
|
308
357
|
|
|
309
358
|
Set `WT_PROFILING=1` and `init()` starts the profiler with the same key, endpoint, service and
|
|
@@ -348,6 +397,17 @@ app.use(appsecMiddleware());
|
|
|
348
397
|
|
|
349
398
|
See `docs/product/security/app-api-protection.md`.
|
|
350
399
|
|
|
400
|
+
## Keys: which key goes where
|
|
401
|
+
|
|
402
|
+
| Prefix | Key | Use it in | Scopes / notes |
|
|
403
|
+
| --- | --- | --- | --- |
|
|
404
|
+
| `wti_` | Ingest key | Servers and workers (`WT_INGEST_KEY`), the Watchtower agent | Sends traces, logs, metrics; never ship it to a browser |
|
|
405
|
+
| `wtp_` | Publishable key | Browsers / RUM (browser SDK, the `/next` tunnel's `?k=`) | Public by design; limited to browser ingest and its allowed origins |
|
|
406
|
+
| `wta_` | Service-account key | CI and deploy scripts (`wt-next-sourcemaps`, release and event calls, monitors-as-code) | Pick the narrowest preset: `ci:write` (releases, deployments, test runs, source maps), `events:write`, `monitors:write` |
|
|
407
|
+
| `wtk_` | API key | MCP server and API clients, Grafana/Prometheus reads | `wtu_` personal access tokens and `wta_` keys also work for MCP |
|
|
408
|
+
|
|
409
|
+
Secrets are shown once when created and stored only as hashes. An ingest key cannot upload source maps or write monitors; a service-account key cannot ingest telemetry.
|
|
410
|
+
|
|
351
411
|
## Configuration
|
|
352
412
|
|
|
353
413
|
| Option | Env var | Default |
|
|
@@ -363,7 +423,7 @@ See `docs/product/security/app-api-protection.md`.
|
|
|
363
423
|
| `bufferDir` | | no offline buffer (spans, logs and metrics spool to `traces/`, `logs/` and `metrics/`, 500 batches each) |
|
|
364
424
|
| `logs` | `WATCHTOWER_LOGS` (`OTEL_LOGS_EXPORTER=none` also turns it off) | `on`: OTLP logs (`log()`, pino, winston) |
|
|
365
425
|
| `metrics` | `WATCHTOWER_METRICS` (`OTEL_METRICS_EXPORTER=none` also turns it off) | `on`: OTLP metrics, see below |
|
|
366
|
-
| `redact` | |
|
|
426
|
+
| `redact` | | `'strict'` (see Redaction presets); a function runs after the preset and after URL scrubbing; called for every span and log attribute, every span event's attributes (`exception.message`, `exception.stacktrace`), the span name (key `span.name`), the status message (`status.message`) and log bodies (`log.body`) |
|
|
367
427
|
|
|
368
428
|
Metrics: `init` sets the global meter provider, so `metrics.getMeter('app')` (re-exported from
|
|
369
429
|
`@opentelemetry/api`) records to Watchtower. A periodic reader exports to `/v1/metrics` every
|
|
@@ -375,6 +435,30 @@ Examples: [`examples/basic.ts`](examples/basic.ts), [`examples/express-app`](exa
|
|
|
375
435
|
|
|
376
436
|
Development: `npm install`, `npm run typecheck`, `npm test` (vitest), `npm run build` (`tsc` to `dist/cjs` and `dist/esm`).
|
|
377
437
|
|
|
438
|
+
### Redaction presets
|
|
439
|
+
|
|
440
|
+
`redact: 'strict' | 'pii' | 'off'` (default `'strict'`) runs on span attributes, span events (so `exception.message`), span names, status messages, log bodies and log attributes before export. `strict` replaces the string value of secret-shaped keys (`authorization`, `cookie`, `set-cookie`, `password`, `secret`, `token`, `api_key`, `session`, ...) with `[redacted]`, and the URL scrubber drops query strings entirely (stricter than keeping non-secret params) and turns token-shaped path segments (UUIDs, long hex, JWTs, opaque tokens) into `:redacted`. `pii` adds emails, phone numbers, Luhn-valid card numbers and IP addresses (`[redacted:email]`, ...). `off` disables both presets and URL scrubbing. Pass a function instead to run your own hook after `strict`. The rule names mirror the gateway's (`email`, `phone`, `card`, `ipv4`, `ipv6`); the gateway applies its own rules again as a backstop, so the SDK is the first line, not the only one.
|
|
441
|
+
|
|
442
|
+
### Coexisting with Sentry or another OTel setup
|
|
443
|
+
|
|
444
|
+
`otel: 'auto'` (default) attaches the Watchtower exporter to the tracer provider another library already registered (a span processor on that provider) and leaves its context manager and propagator alone; `'own'` always builds and registers our own; `'attach'` is `'auto'` with a warning when there is nothing to attach to. Attached spans carry the other provider's resource, so set `OTEL_SERVICE_NAME` and `OTEL_RESOURCE_ATTRIBUTES`; `remoteSampling` is not applied. Attaching needs the provider to accept processors (`addSpanProcessor`, or the sdk-trace 2.x internal list); otherwise `init` warns and uses its own.
|
|
445
|
+
|
|
446
|
+
### `init()` status
|
|
447
|
+
|
|
448
|
+
`init()` returns the client, which also carries `traces`, `metrics`, `logs` (`'ok' | 'disabled' | 'blocked'`), `blocked` (OTel globals that were already registered and kept: `tracer-provider`, `context-manager`, `propagator`, `meter-provider`) and `warnings`. Log `JSON.stringify({ traces: c.traces, blocked: c.blocked, warnings: c.warnings })` at startup to see why a signal is missing.
|
|
449
|
+
|
|
450
|
+
### One call per framework
|
|
451
|
+
|
|
452
|
+
`instrument('nest' | 'express' | 'next' | 'bullmq' | 'pg' | 'postgres' | 'ioredis')` after `init()` applies the right instrumentation and returns what it enabled. `nest`/`express` turn on node:http server spans, renamed `METHOD /route/:param` from the matched Express route (Nest on its Express adapter; Fastify routes come from the `/fastify` integration; `WT_ROUTE_NAMES=0` keeps the bare `METHOD`). `bullmq` and `postgres` patch classes or a diagnostics channel and work in any order. `pg` and `ioredis` use the OTel instrumentation, which hooks `require`, so call them (or `init` with `instrument`) before the first import of `pg` / `ioredis`; the `/register` preload does that for you.
|
|
453
|
+
|
|
454
|
+
### Datastore spans without a parent
|
|
455
|
+
|
|
456
|
+
With `requireParent` on, a query run outside any span is dropped. Each drop increments the counter `wt.sdk.db.dropped_spans` (exported with the SDK's metrics, readable in-process with `droppedDbSpans()`) and the first one logs a diag warning; a rising count means work (a cron, a worker) runs outside `observe`/a request span.
|
|
457
|
+
|
|
458
|
+
### Release detection order
|
|
459
|
+
|
|
460
|
+
`release` option, `WT_RELEASE`, `service.version` in `OTEL_RESOURCE_ATTRIBUTES`, the CI commit variables, the build stamp `WT_BUILD_STAMP` (then `BUILD_STAMP`; set it in your Dockerfile with `ARG`/`ENV`), then the commit `.git/HEAD` points at (searched upward from the working directory; plain file reads, loose ref or `packed-refs`, worktrees followed).
|
|
461
|
+
|
|
378
462
|
## Test reporters and resumable evals
|
|
379
463
|
|
|
380
464
|
Jest: `reporters: ['default', ['@watchtowerobservability/node/jest', {}]]`. Vitest: `reporters: ['default', ['@watchtowerobservability/node/vitest', {}]]`.
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
/** The real provider behind the global proxy, or undefined when none (or only the no-op one) is registered. */
|
|
2
|
+
export declare function foreignProvider(): any;
|
|
3
|
+
/**
|
|
4
|
+
* Add processors to `provider`: `addSpanProcessor` (sdk-trace v1) or the v2 `_activeSpanProcessor._spanProcessors` list.
|
|
5
|
+
* shortcut: v2+ has no public hook, so this reaches into a private field; replace when the SDK adds one.
|
|
6
|
+
*/
|
|
7
|
+
export declare function attachProcessors(provider: any, procs: unknown[]): boolean;
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.foreignProvider = foreignProvider;
|
|
4
|
+
exports.attachProcessors = attachProcessors;
|
|
5
|
+
// Coexistence with another OpenTelemetry setup (Sentry, a vendor agent): find the tracer provider already registered
|
|
6
|
+
// globally and add our span processors to it instead of replacing it.
|
|
7
|
+
const api_1 = require("@opentelemetry/api");
|
|
8
|
+
/** The real provider behind the global proxy, or undefined when none (or only the no-op one) is registered. */
|
|
9
|
+
function foreignProvider() {
|
|
10
|
+
const g = api_1.trace.getTracerProvider();
|
|
11
|
+
const d = typeof g?.getDelegate === 'function' ? g.getDelegate() : g;
|
|
12
|
+
return !d || d.constructor?.name === 'NoopTracerProvider' || d.constructor?.name === 'ProxyTracerProvider' ? undefined : d;
|
|
13
|
+
}
|
|
14
|
+
/**
|
|
15
|
+
* Add processors to `provider`: `addSpanProcessor` (sdk-trace v1) or the v2 `_activeSpanProcessor._spanProcessors` list.
|
|
16
|
+
* shortcut: v2+ has no public hook, so this reaches into a private field; replace when the SDK adds one.
|
|
17
|
+
*/
|
|
18
|
+
function attachProcessors(provider, procs) {
|
|
19
|
+
if (typeof provider.addSpanProcessor === 'function') {
|
|
20
|
+
for (const p of procs)
|
|
21
|
+
provider.addSpanProcessor(p);
|
|
22
|
+
return true;
|
|
23
|
+
}
|
|
24
|
+
const list = provider._activeSpanProcessor?._spanProcessors;
|
|
25
|
+
if (!Array.isArray(list))
|
|
26
|
+
return false;
|
|
27
|
+
list.push(...procs);
|
|
28
|
+
return true;
|
|
29
|
+
}
|
package/dist/cjs/checkin.js
CHANGED
|
@@ -1,18 +1,9 @@
|
|
|
1
1
|
"use strict";
|
|
2
2
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
3
|
exports.checkin = checkin;
|
|
4
|
+
// Cron / scheduler check-ins: POST /v1/checkins/{slug} (key scope `ingest:checkins`; the edge accepts 6 a minute per monitor).
|
|
5
|
+
const monitor_js_1 = require("./cron/monitor.js");
|
|
4
6
|
/** Send `in_progress`, run `fn`, then send `ok` or `error` with its duration. Check-in failures never affect `fn`; its result or error is passed through. */
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
await send('in_progress');
|
|
8
|
-
const t = Date.now();
|
|
9
|
-
try {
|
|
10
|
-
const r = await fn();
|
|
11
|
-
await send('ok', Date.now() - t);
|
|
12
|
-
return r;
|
|
13
|
-
}
|
|
14
|
-
catch (e) {
|
|
15
|
-
await send('error', Date.now() - t);
|
|
16
|
-
throw e;
|
|
17
|
-
}
|
|
7
|
+
function checkin(c, slug, fn) {
|
|
8
|
+
return (0, monitor_js_1.withMonitor)(c, slug, fn, { wait: true });
|
|
18
9
|
}
|
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
import type { CheckinTarget } from '../checkin.js';
|
|
2
|
+
export type CheckInStatus = 'in_progress' | 'ok' | 'error';
|
|
3
|
+
/** Sent in the check-in body so the server can create or update the monitor on first contact (Sentry's `monitor_config` shape, minutes). */
|
|
4
|
+
export interface MonitorConfig {
|
|
5
|
+
schedule: {
|
|
6
|
+
type: 'crontab';
|
|
7
|
+
value: string;
|
|
8
|
+
};
|
|
9
|
+
timezone?: string;
|
|
10
|
+
checkin_margin_m?: number;
|
|
11
|
+
max_runtime_m?: number;
|
|
12
|
+
failure_threshold?: number;
|
|
13
|
+
}
|
|
14
|
+
export interface MonitorOptions {
|
|
15
|
+
/** Crontab, 5 fields (or 6 with leading seconds, which are dropped when they are `0`). */
|
|
16
|
+
schedule?: string;
|
|
17
|
+
timezone?: string;
|
|
18
|
+
/** Minutes a check-in may be late before it counts as missed. */
|
|
19
|
+
checkinMargin?: number;
|
|
20
|
+
/** Minutes a run may stay `in_progress` before it counts as failed. */
|
|
21
|
+
maxRuntime?: number;
|
|
22
|
+
/** Consecutive failures before an issue opens. */
|
|
23
|
+
failureThreshold?: number;
|
|
24
|
+
/** Await the check-in requests (default false: fire and forget, capped at 5 s). Use it in short-lived processes. */
|
|
25
|
+
wait?: boolean;
|
|
26
|
+
}
|
|
27
|
+
export interface CheckInOptions {
|
|
28
|
+
wait?: boolean;
|
|
29
|
+
durationMs?: number;
|
|
30
|
+
monitorConfig?: MonitorConfig;
|
|
31
|
+
/** Default 5000. */
|
|
32
|
+
timeoutMs?: number;
|
|
33
|
+
}
|
|
34
|
+
/** The client `init()` made (the one per-process state `index.ts` keeps), without importing it. */
|
|
35
|
+
export declare function currentTarget(): CheckinTarget | undefined;
|
|
36
|
+
/** Check-ins are served by the edge host, not the OTLP gateway: `ingest.x` becomes `edge.x`. `WT_CHECKIN_URL` overrides. */
|
|
37
|
+
export declare function checkinBase(endpoint: string): string;
|
|
38
|
+
export declare function normalizeCron(expr: string): string;
|
|
39
|
+
export declare function toConfig(o: MonitorOptions): MonitorConfig | undefined;
|
|
40
|
+
/** Send one check-in. Never throws or rejects; without `wait` it returns at once and the request is capped at 5 s. */
|
|
41
|
+
export declare function checkIn(c: CheckinTarget, slug: string, status: CheckInStatus, o?: CheckInOptions): Promise<void>;
|
|
42
|
+
/** Run `fn` as a monitored job: `in_progress`, then `ok` or `error` with the duration. Returns fn's result or rethrows its error; check-in failures never reach it. */
|
|
43
|
+
export declare function withMonitor<T>(c: CheckinTarget, slug: string, fn: () => T | Promise<T>, o?: MonitorOptions): Promise<T>;
|
|
44
|
+
/** Lowercase kebab slug of a job or method name (`MyService.nightlyReport` -> `my-service-nightly-report`). Empty for a uuid. */
|
|
45
|
+
export declare function slugify(name: string): string;
|
|
46
|
+
/** `withMonitor` against the client `init()` made; just runs `fn` when there is none. */
|
|
47
|
+
export declare function monitorJob<T>(slug: string, fn: () => T | Promise<T>, o?: MonitorOptions): Promise<T>;
|
|
@@ -0,0 +1,95 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.currentTarget = currentTarget;
|
|
4
|
+
exports.checkinBase = checkinBase;
|
|
5
|
+
exports.normalizeCron = normalizeCron;
|
|
6
|
+
exports.toConfig = toConfig;
|
|
7
|
+
exports.checkIn = checkIn;
|
|
8
|
+
exports.withMonitor = withMonitor;
|
|
9
|
+
exports.slugify = slugify;
|
|
10
|
+
exports.monitorJob = monitorJob;
|
|
11
|
+
// Cron monitor check-ins: POST {edge}/v1/checkins/{slug} (key scope `ingest:checkins`; the edge accepts 6 a minute per monitor).
|
|
12
|
+
const api_1 = require("@opentelemetry/api");
|
|
13
|
+
/** The client `init()` made (the one per-process state `index.ts` keeps), without importing it. */
|
|
14
|
+
function currentTarget() {
|
|
15
|
+
const s = globalThis[Symbol.for('watchtower.node.state')];
|
|
16
|
+
return s?.current;
|
|
17
|
+
}
|
|
18
|
+
/** Check-ins are served by the edge host, not the OTLP gateway: `ingest.x` becomes `edge.x`. `WT_CHECKIN_URL` overrides. */
|
|
19
|
+
function checkinBase(endpoint) {
|
|
20
|
+
const env = process.env.WT_CHECKIN_URL;
|
|
21
|
+
if (env)
|
|
22
|
+
return env.replace(/\/+$/, '');
|
|
23
|
+
return endpoint.replace(/^(https?:\/\/)ingest\./i, '$1edge.');
|
|
24
|
+
}
|
|
25
|
+
// `0 */5 * * * *` -> `*/5 * * * *`; a 6-field expression with another seconds value stays as it is.
|
|
26
|
+
function normalizeCron(expr) {
|
|
27
|
+
const f = expr.trim().split(/\s+/);
|
|
28
|
+
return f.length === 6 && /^0+$/.test(f[0]) ? f.slice(1).join(' ') : f.join(' ');
|
|
29
|
+
}
|
|
30
|
+
function toConfig(o) {
|
|
31
|
+
if (typeof o.schedule !== 'string' || !o.schedule.trim())
|
|
32
|
+
return undefined;
|
|
33
|
+
const c = { schedule: { type: 'crontab', value: normalizeCron(o.schedule) } };
|
|
34
|
+
if (o.timezone)
|
|
35
|
+
c.timezone = o.timezone;
|
|
36
|
+
if (o.checkinMargin !== undefined)
|
|
37
|
+
c.checkin_margin_m = o.checkinMargin;
|
|
38
|
+
if (o.maxRuntime !== undefined)
|
|
39
|
+
c.max_runtime_m = o.maxRuntime;
|
|
40
|
+
if (o.failureThreshold !== undefined)
|
|
41
|
+
c.failure_threshold = o.failureThreshold;
|
|
42
|
+
return c;
|
|
43
|
+
}
|
|
44
|
+
// The OTel SDK's own key (`@opentelemetry/core` suppressTracing), so our HTTP call makes no span.
|
|
45
|
+
const SUPPRESS = Symbol.for('OpenTelemetry SDK Context Key SUPPRESS_TRACING');
|
|
46
|
+
/** Send one check-in. Never throws or rejects; without `wait` it returns at once and the request is capped at 5 s. */
|
|
47
|
+
function checkIn(c, slug, status, o = {}) {
|
|
48
|
+
const ms = o.durationMs === undefined ? undefined : Math.min(Math.max(Math.round(o.durationMs), 0), 86_400_000);
|
|
49
|
+
const url = `${checkinBase(c.endpoint)}/v1/checkins/${encodeURIComponent(slug)}?status=${status}${ms === undefined ? '' : `&duration_ms=${ms}`}`;
|
|
50
|
+
const body = { status };
|
|
51
|
+
if (ms !== undefined)
|
|
52
|
+
body.duration_ms = ms;
|
|
53
|
+
if (o.monitorConfig)
|
|
54
|
+
body.monitor_config = o.monitorConfig;
|
|
55
|
+
const ac = new AbortController();
|
|
56
|
+
const timer = setTimeout(() => ac.abort(), o.timeoutMs ?? 5000);
|
|
57
|
+
timer.unref?.();
|
|
58
|
+
let p;
|
|
59
|
+
try {
|
|
60
|
+
p = api_1.context.with(api_1.context.active().setValue(SUPPRESS, true), () => c.fetch(url, { method: 'POST', headers: { ...c.headers, 'Content-Type': 'application/json' }, body: JSON.stringify(body), signal: ac.signal }))
|
|
61
|
+
.then(() => undefined, () => undefined);
|
|
62
|
+
}
|
|
63
|
+
catch {
|
|
64
|
+
p = Promise.resolve();
|
|
65
|
+
}
|
|
66
|
+
p = p.finally(() => clearTimeout(timer));
|
|
67
|
+
return o.wait ? p : Promise.resolve();
|
|
68
|
+
}
|
|
69
|
+
/** Run `fn` as a monitored job: `in_progress`, then `ok` or `error` with the duration. Returns fn's result or rethrows its error; check-in failures never reach it. */
|
|
70
|
+
async function withMonitor(c, slug, fn, o = {}) {
|
|
71
|
+
const monitorConfig = toConfig(o);
|
|
72
|
+
const send = (status, durationMs) => checkIn(c, slug, status, { wait: o.wait, durationMs, monitorConfig });
|
|
73
|
+
await send('in_progress');
|
|
74
|
+
const t = Date.now();
|
|
75
|
+
try {
|
|
76
|
+
const r = await fn();
|
|
77
|
+
await send('ok', Date.now() - t);
|
|
78
|
+
return r;
|
|
79
|
+
}
|
|
80
|
+
catch (e) {
|
|
81
|
+
await send('error', Date.now() - t);
|
|
82
|
+
throw e;
|
|
83
|
+
}
|
|
84
|
+
}
|
|
85
|
+
/** Lowercase kebab slug of a job or method name (`MyService.nightlyReport` -> `my-service-nightly-report`). Empty for a uuid. */
|
|
86
|
+
function slugify(name) {
|
|
87
|
+
if (/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(name))
|
|
88
|
+
return '';
|
|
89
|
+
return name.replace(/([a-z0-9])([A-Z])/g, '$1-$2').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 64);
|
|
90
|
+
}
|
|
91
|
+
/** `withMonitor` against the client `init()` made; just runs `fn` when there is none. */
|
|
92
|
+
function monitorJob(slug, fn, o = {}) {
|
|
93
|
+
const c = currentTarget();
|
|
94
|
+
return c ? withMonitor(c, slug, fn, o) : Promise.resolve().then(fn);
|
|
95
|
+
}
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
type Fn = (...a: any[]) => unknown;
|
|
2
|
+
declare const DONE: unique symbol;
|
|
3
|
+
interface CronJobLike {
|
|
4
|
+
cronTime?: {
|
|
5
|
+
source?: unknown;
|
|
6
|
+
zone?: unknown;
|
|
7
|
+
timeZone?: unknown;
|
|
8
|
+
};
|
|
9
|
+
_callbacks?: Fn[];
|
|
10
|
+
[DONE]?: boolean;
|
|
11
|
+
}
|
|
12
|
+
interface SchedulerRegistryLike {
|
|
13
|
+
addCronJob: (name: string, job: CronJobLike) => unknown;
|
|
14
|
+
getCronJobs: () => Map<string, CronJobLike>;
|
|
15
|
+
[DONE]?: boolean;
|
|
16
|
+
}
|
|
17
|
+
/**
|
|
18
|
+
* `instrumentNestSchedule(app.get(SchedulerRegistry))` after `app.init()` (or in `onApplicationBootstrap`): every `@Cron`
|
|
19
|
+
* job, already registered or added later, runs as a monitor named after its `@Cron(expr, { name })` (kebab-cased) with its
|
|
20
|
+
* cron expression and timezone as the schedule. Give jobs a name; unnamed ones (uuid) are skipped. Returns how many were wrapped now.
|
|
21
|
+
* shortcut: reads the `cron` package's private `_callbacks` (cron 3 and 4); a version that moves it wraps nothing.
|
|
22
|
+
*/
|
|
23
|
+
export declare function instrumentNestSchedule(registry: SchedulerRegistryLike): number;
|
|
24
|
+
interface NodeCronLike {
|
|
25
|
+
schedule: (expr: string, fn: Fn, opts?: {
|
|
26
|
+
name?: string;
|
|
27
|
+
timezone?: string;
|
|
28
|
+
}) => unknown;
|
|
29
|
+
}
|
|
30
|
+
/**
|
|
31
|
+
* `import cron from 'node-cron'; instrumentNodeCron(cron)`: tasks scheduled afterwards with `cron.schedule(expr, fn, { name })`
|
|
32
|
+
* run as monitors (a function's own name is not used: bundlers rename them). Pass the default export (a CommonJS object), not an ESM namespace.
|
|
33
|
+
* Returns false when it cannot patch it.
|
|
34
|
+
*/
|
|
35
|
+
export declare function instrumentNodeCron(cron: NodeCronLike): boolean;
|
|
36
|
+
export {};
|
|
@@ -0,0 +1,65 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.instrumentNestSchedule = instrumentNestSchedule;
|
|
4
|
+
exports.instrumentNodeCron = instrumentNodeCron;
|
|
5
|
+
// Cron monitors for `@nestjs/schedule` (`@Cron`) and `node-cron`: each job becomes a monitor via `withMonitor`.
|
|
6
|
+
const monitor_js_1 = require("./monitor.js");
|
|
7
|
+
const DONE = Symbol.for('watchtower.cron.wrapped');
|
|
8
|
+
/** Wrap one `cron` CronJob's callbacks. False when this `cron` version keeps them elsewhere than `_callbacks`. */
|
|
9
|
+
function wrapJob(name, job) {
|
|
10
|
+
const slug = (0, monitor_js_1.slugify)(name); // a Nest job without `{ name }` gets a uuid: nothing stable to monitor
|
|
11
|
+
if (!slug || job[DONE] || !Array.isArray(job._callbacks))
|
|
12
|
+
return false;
|
|
13
|
+
job[DONE] = true;
|
|
14
|
+
const src = job.cronTime?.source;
|
|
15
|
+
const tz = job.cronTime?.zone ?? job.cronTime?.timeZone;
|
|
16
|
+
const o = { schedule: typeof src === 'string' ? src : undefined, timezone: typeof tz === 'string' ? tz : undefined };
|
|
17
|
+
job._callbacks = job._callbacks.map((cb) => function (...a) { return (0, monitor_js_1.monitorJob)(slug, () => cb.apply(this, a), o); });
|
|
18
|
+
return true;
|
|
19
|
+
}
|
|
20
|
+
/**
|
|
21
|
+
* `instrumentNestSchedule(app.get(SchedulerRegistry))` after `app.init()` (or in `onApplicationBootstrap`): every `@Cron`
|
|
22
|
+
* job, already registered or added later, runs as a monitor named after its `@Cron(expr, { name })` (kebab-cased) with its
|
|
23
|
+
* cron expression and timezone as the schedule. Give jobs a name; unnamed ones (uuid) are skipped. Returns how many were wrapped now.
|
|
24
|
+
* shortcut: reads the `cron` package's private `_callbacks` (cron 3 and 4); a version that moves it wraps nothing.
|
|
25
|
+
*/
|
|
26
|
+
function instrumentNestSchedule(registry) {
|
|
27
|
+
let n = 0;
|
|
28
|
+
for (const [name, job] of registry.getCronJobs())
|
|
29
|
+
if (wrapJob(name, job))
|
|
30
|
+
n++;
|
|
31
|
+
if (!registry[DONE]) {
|
|
32
|
+
registry[DONE] = true;
|
|
33
|
+
const add = registry.addCronJob;
|
|
34
|
+
registry.addCronJob = function (name, job) {
|
|
35
|
+
wrapJob(name, job);
|
|
36
|
+
return add.call(this, name, job);
|
|
37
|
+
};
|
|
38
|
+
}
|
|
39
|
+
return n;
|
|
40
|
+
}
|
|
41
|
+
/**
|
|
42
|
+
* `import cron from 'node-cron'; instrumentNodeCron(cron)`: tasks scheduled afterwards with `cron.schedule(expr, fn, { name })`
|
|
43
|
+
* run as monitors (a function's own name is not used: bundlers rename them). Pass the default export (a CommonJS object), not an ESM namespace.
|
|
44
|
+
* Returns false when it cannot patch it.
|
|
45
|
+
*/
|
|
46
|
+
function instrumentNodeCron(cron) {
|
|
47
|
+
const orig = cron.schedule;
|
|
48
|
+
if (typeof orig !== 'function' || orig[DONE])
|
|
49
|
+
return false;
|
|
50
|
+
const wrapped = function (expr, fn, opts, ...rest) {
|
|
51
|
+
const slug = typeof fn === 'function' ? (0, monitor_js_1.slugify)(opts?.name || '') : '';
|
|
52
|
+
if (!slug)
|
|
53
|
+
return orig.call(this, expr, fn, opts, ...rest);
|
|
54
|
+
const o = { schedule: expr, timezone: opts?.timezone };
|
|
55
|
+
return orig.call(this, expr, function (...a) { return (0, monitor_js_1.monitorJob)(slug, () => fn.apply(this, a), o); }, opts, ...rest);
|
|
56
|
+
};
|
|
57
|
+
wrapped[DONE] = true;
|
|
58
|
+
try {
|
|
59
|
+
cron.schedule = wrapped;
|
|
60
|
+
}
|
|
61
|
+
catch {
|
|
62
|
+
return false;
|
|
63
|
+
}
|
|
64
|
+
return cron.schedule === wrapped;
|
|
65
|
+
}
|
package/dist/cjs/env.d.ts
CHANGED
|
@@ -10,3 +10,13 @@ export interface OtelEnv {
|
|
|
10
10
|
resource: Record<string, string>;
|
|
11
11
|
}
|
|
12
12
|
export declare function otelEnv(env?: NodeJS.ProcessEnv): OtelEnv;
|
|
13
|
+
/**
|
|
14
|
+
* The commit `HEAD` points at, found by walking up from `from` to a `.git` directory (a `.git` file of a worktree or submodule is
|
|
15
|
+
* followed through its `gitdir:` line). Reads `HEAD`, then the ref file or `packed-refs`; no child process. undefined when not found.
|
|
16
|
+
*/
|
|
17
|
+
export declare function gitHeadSha(from: string): string | undefined;
|
|
18
|
+
/**
|
|
19
|
+
* service.version: explicit option, WT_RELEASE, OTEL_RESOURCE_ATTRIBUTES, the first CI commit-sha variable, the build stamp
|
|
20
|
+
* (`WT_BUILD_STAMP`, `BUILD_STAMP`), then the `.git` HEAD found upward from `gitFrom` (skipped when not given). Empty and `unknown` count as absent.
|
|
21
|
+
*/
|
|
22
|
+
export declare function resolveRelease(opt: string | undefined, env: NodeJS.ProcessEnv, otelResource: Record<string, string>, gitFrom?: string): string | undefined;
|