ezlogs-nextjs 0.4.3 → 0.4.6

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.
Files changed (66) hide show
  1. package/README.md +217 -86
  2. package/THIRD_PARTY_LICENSES.md +27 -0
  3. package/dist/actors/index.d.cts +1 -1
  4. package/dist/actors/index.d.ts +1 -1
  5. package/dist/{chunk-Z2TM3LGG.js → chunk-2NFJOT6Q.js} +1 -1
  6. package/dist/{chunk-R6IWVTX3.cjs → chunk-65HRY3PW.cjs} +31 -21
  7. package/dist/{chunk-YXZZNZG6.cjs → chunk-B3WST6ES.cjs} +9 -9
  8. package/dist/{chunk-MMLQXSSD.cjs → chunk-B5ZUQULZ.cjs} +18 -11
  9. package/dist/{chunk-NX4EL7BY.cjs → chunk-DM2EAOSF.cjs} +4 -4
  10. package/dist/chunk-DRE2VXFX.js +19 -0
  11. package/dist/chunk-H3FC5HMW.cjs +16 -0
  12. package/dist/{chunk-GI6BM4MR.js → chunk-IBSNHBUC.js} +18 -12
  13. package/dist/chunk-JWJKFZBW.js +52 -0
  14. package/dist/{chunk-MHBS5FEP.js → chunk-M3VBQ5KT.js} +27 -4
  15. package/dist/chunk-NFZ5OKF3.cjs +22 -0
  16. package/dist/{chunk-GMHOUAKD.cjs → chunk-O7SFYXJC.cjs} +37 -13
  17. package/dist/{chunk-U22T7QYY.js → chunk-PK2Z2ABL.js} +13 -3
  18. package/dist/{chunk-YMIGZYFH.js → chunk-RD47JECJ.js} +1 -1
  19. package/dist/chunk-RMKGMIV2.js +13 -0
  20. package/dist/{chunk-NINIAL7M.js → chunk-U3IJV5EJ.js} +1 -1
  21. package/dist/chunk-VJR4VB4B.cjs +56 -0
  22. package/dist/{chunk-PS4U2GFJ.cjs → chunk-YO6E763S.cjs} +5 -5
  23. package/dist/{configuration-CJ5yKVlP.d.cts → configuration-b9pImwFB.d.cts} +2 -2
  24. package/dist/{configuration-CJ5yKVlP.d.ts → configuration-b9pImwFB.d.ts} +2 -2
  25. package/dist/db/drizzle.cjs +3 -3
  26. package/dist/db/drizzle.js +2 -2
  27. package/dist/db/postgres-js.cjs +4 -4
  28. package/dist/db/postgres-js.js +2 -2
  29. package/dist/db/prisma.cjs +12 -12
  30. package/dist/db/prisma.js +2 -2
  31. package/dist/db/supabase.cjs +42 -17
  32. package/dist/db/supabase.d.cts +11 -5
  33. package/dist/db/supabase.d.ts +11 -5
  34. package/dist/db/supabase.js +33 -9
  35. package/dist/index.cjs +288 -142
  36. package/dist/index.d.cts +2 -2
  37. package/dist/index.d.ts +2 -2
  38. package/dist/index.js +198 -52
  39. package/dist/jobs/bullmq.cjs +44 -16
  40. package/dist/jobs/bullmq.d.cts +7 -1
  41. package/dist/jobs/bullmq.d.ts +7 -1
  42. package/dist/jobs/bullmq.js +33 -6
  43. package/dist/jobs/inngest.cjs +36 -17
  44. package/dist/jobs/inngest.d.cts +7 -1
  45. package/dist/jobs/inngest.d.ts +7 -1
  46. package/dist/jobs/inngest.js +23 -5
  47. package/dist/jobs/supabase-queues.cjs +9 -9
  48. package/dist/jobs/supabase-queues.js +4 -4
  49. package/dist/jobs/trigger.cjs +7 -7
  50. package/dist/jobs/trigger.js +4 -4
  51. package/dist/jobs/upstash-workflow.cjs +139 -23
  52. package/dist/jobs/upstash-workflow.d.cts +20 -2
  53. package/dist/jobs/upstash-workflow.d.ts +20 -2
  54. package/dist/jobs/upstash-workflow.js +129 -14
  55. package/dist/nextjs-plugin/index.cjs +46 -29
  56. package/dist/nextjs-plugin/index.js +46 -29
  57. package/dist/nextjs-plugin/loader.cjs +70 -60
  58. package/dist/nextjs-plugin/loader.d.cts +18 -1
  59. package/dist/nextjs-plugin/loader.d.ts +18 -1
  60. package/dist/nextjs-plugin/loader.js +70 -61
  61. package/dist/triggers/index.cjs +22 -16
  62. package/dist/triggers/index.d.cts +0 -10
  63. package/dist/triggers/index.d.ts +0 -10
  64. package/dist/triggers/index.js +11 -5
  65. package/package.json +6 -5
  66. package/sql/postgres/00_install.sql +20 -3
package/README.md CHANGED
@@ -24,21 +24,39 @@ Status: Completed successfully
24
24
 
25
25
  ---
26
26
 
27
- ## Install
27
+ ## Install: paste the prompt into your coding AI, or do it by hand
28
28
 
29
- ```bash
30
- npm install ezlogs-nextjs
31
- # or: pnpm add ezlogs-nextjs / bun add ezlogs-nextjs
29
+ **1. Fastest: let your coding AI do it.** Paste this into Cursor,
30
+ Claude Code, v0, Replit or any coding AI:
31
+
32
+ ```text
33
+ Install EZLogs in this app by following https://app.ezlogs.io/install/nextjs.md
32
34
  ```
33
35
 
36
+ The AI does every step below (package, `instrumentation.ts`, config,
37
+ key, database, jobs) and then checks that capture works. It asks you for
38
+ your API key. Signed in at [app.ezlogs.io](https://app.ezlogs.io), the
39
+ prompt shown under a new key in **Settings → API keys** already has your
40
+ key in it.
41
+
42
+ **2. By hand:** follow the [quick start](#quick-start-by-hand) below.
43
+ Steps 1-4 take a few minutes; steps 5-7 depend on your stack.
44
+
45
+ ## Quick start (by hand)
46
+
34
47
  Requires Node 18.17+ and Next.js 14+.
35
48
 
36
- ## Quick start
49
+ ### 1. Install the package
37
50
 
38
- ### 1. Create `instrumentation.ts`
51
+ ```bash
52
+ npm install ezlogs-nextjs
53
+ # or: pnpm add ezlogs-nextjs / bun add ezlogs-nextjs
54
+ ```
55
+
56
+ ### 2. Add `instrumentation.ts`
39
57
 
40
- At your project root (or `src/instrumentation.ts` if you use the
41
- `src/` layout):
58
+ Starts the agent when your server boots. Put it at the project root
59
+ (or `src/instrumentation.ts` if you use the `src/` layout):
42
60
 
43
61
  ```ts
44
62
  import { ezlogs } from "ezlogs-nextjs";
@@ -55,19 +73,28 @@ export async function register() {
55
73
  `serverUrl` is optional: it defaults to `process.env.EZLOGS_SERVER_URL`
56
74
  if set, otherwise `https://app.ezlogs.io`. Set it only if you self-host.
57
75
 
58
- ### 2. Wrap your Next config
76
+ **Who did it.** Every action shows the signed-in person. With Supabase
77
+ Auth there is nothing to add. Otherwise add one line to `ezlogs.init`:
59
78
 
60
- `withEzlogsConfig(...)` is a transparent wrapper around your existing
61
- config object. It doesn't add EZLogs-specific settings to your Next
62
- config — every EZLogs option goes in `ezlogs.init({...})`. The wrapper
63
- just registers the build-time loaders that auto-wrap your routes and
64
- Server Actions.
79
+ | Your sign-in | Add to `ezlogs.init({ … })` |
80
+ |---|---|
81
+ | Auth.js (NextAuth v5) | `actorFromRequest: authJsActor({ auth })` (your `auth` from `auth.ts`) |
82
+ | NextAuth v4 | `actorFromRequest: nextAuthActor({ authOptions })` |
83
+ | Clerk | `actorFromRequest: clerkActor()` |
84
+ | Your own session or JWT | a small function, see [docs/auth.md](./docs/auth.md) |
85
+
86
+ ```ts
87
+ import { authJsActor } from "ezlogs-nextjs/actors"; // or nextAuthActor / clerkActor
88
+ ```
65
89
 
66
- Pick the snippet matching your config file:
90
+ ### 3. Wrap your Next config
67
91
 
68
- **`next.config.ts`** (TypeScript — Next 14+ default):
92
+ Registers the build-time loaders that auto-wrap your routes and Server
93
+ Actions. It adds no EZLogs settings to your config; every EZLogs option
94
+ goes in `ezlogs.init({...})`.
69
95
 
70
96
  ```ts
97
+ // next.config.ts
71
98
  import type { NextConfig } from "next";
72
99
  import { withEzlogsConfig } from "ezlogs-nextjs/plugin";
73
100
 
@@ -78,8 +105,8 @@ const nextConfig: NextConfig = {
78
105
  export default withEzlogsConfig(nextConfig);
79
106
  ```
80
107
 
81
- **`next.config.mjs`** / ESM **`next.config.js`** (also type-checks
82
- under `checkJs`, e.g. create-t3-app):
108
+ <details>
109
+ <summary><code>next.config.mjs</code> / ESM <code>next.config.js</code> (also type-checks under <code>checkJs</code>, e.g. create-t3-app)</summary>
83
110
 
84
111
  ```js
85
112
  import { withEzlogsConfig } from "ezlogs-nextjs/plugin";
@@ -89,15 +116,22 @@ const nextConfig = { /* your options */ };
89
116
  export default withEzlogsConfig(nextConfig);
90
117
  ```
91
118
 
92
- **`next.config.js`** (CommonJS):
119
+ </details>
120
+
121
+ <details>
122
+ <summary><code>next.config.js</code> (CommonJS)</summary>
93
123
 
94
124
  ```js
95
125
  const { withEzlogsConfig } = require("ezlogs-nextjs/plugin");
96
126
  module.exports = withEzlogsConfig({ /* your options */ });
97
127
  ```
98
128
 
99
- **Already have an `instrumentation.ts` or a wrapped config?** Keep
100
- yours and add to it:
129
+ </details>
130
+
131
+ <details>
132
+ <summary>Already have an <code>instrumentation.ts</code> or a wrapped config?</summary>
133
+
134
+ Keep yours and add to it:
101
135
 
102
136
  - `instrumentation.ts`: put the `ezlogs.init({...})` call inside your
103
137
  existing `register()`, in the `NEXT_RUNTIME === "nodejs"` branch
@@ -108,81 +142,121 @@ yours and add to it:
108
142
  `export default withNextIntl(withEzlogsConfig(nextConfig))` or
109
143
  `withSentryConfig(withEzlogsConfig(nextConfig), { ... })`.
110
144
 
111
- ### 3. Set env vars, restart, verify
145
+ </details>
146
+
147
+ ### 4. Add your key, restart, check
112
148
 
113
149
  ```bash
114
150
  # .env.local
115
151
  EZLOGS_PROJECT_TOKEN=ezl_your_api_key_here
116
152
  ```
117
153
 
118
- Restart your dev server and look for this line in the terminal (one
119
- per server process, at the default log level):
154
+ Restart your dev server. The terminal shows this line once per server
155
+ process:
120
156
 
121
157
  ```
122
158
  [ezlogs] capturing → app.ezlogs.io (key ezl_a1b2c3d4…)
123
159
  ```
124
160
 
161
+ Call an API route or submit a Server Action; events appear in your
162
+ EZLogs dashboard within a few seconds. Opening a page is not a reliable
163
+ check: page views are recorded only when the app has a `middleware.ts`
164
+ (or `proxy.ts` on Next 16).
165
+
166
+ <details>
167
+ <summary>Not seeing the line?</summary>
168
+
125
169
  If `projectToken` is missing you get this instead:
126
170
 
127
171
  ```
128
172
  [ezlogs] not capturing: projectToken missing in ezlogs.init() (check EZLOGS_PROJECT_TOKEN)
129
173
  ```
130
174
 
131
- Call an API route or submit a Server Action; events appear in your
132
- EZLogs dashboard within a few seconds. Page views are only recorded when
133
- the app has a `middleware.ts` (or `proxy.ts` on Next 16), so opening a
134
- page is not a reliable check.
135
-
136
- Sending to a local EZLogs server over plain `http://` (development)?
137
- Events are still sent, but the agent warns on every start; pass
175
+ Sending to a local EZLogs server over a non-localhost plain `http://`
176
+ address? Events are still sent, but the agent warns on every start; pass
138
177
  `allowInsecureTransport: true` to `ezlogs.init` to silence it. Keep
139
178
  `https://` in production.
140
179
 
141
- ### 4. Database changes
180
+ `next dev` keeps reloading the page after you installed or upgraded the
181
+ agent? Stop it, delete the `.next` folder, and start it again: a dev
182
+ cache built before the change can keep invalidating itself.
142
183
 
143
- Steps 1-3 capture requests, Server Actions and jobs. Database changes
144
- need one more step, depending on your stack:
184
+ More in [docs/troubleshooting.md](./docs/troubleshooting.md).
145
185
 
146
- | Your app writes with | Do this | You get |
147
- |---|---|---|
148
- | **Supabase** (supabase-js) | `npm i pg`, set `DATABASE_URL` to the Postgres connection string, run `npx ezlogs-nextjs install-triggers`. Nothing to wrap: the agent tags supabase-js requests and the trigger reads the tag. | Every write (`.from()`, `.rpc()`, bulk) with from→to diffs, linked to its request |
149
- | **Prisma** on Postgres | triggers (as above) + `new PrismaClient().$extends(ezlogsPrisma())` (below) | Same |
150
- | **Drizzle** (node-postgres) or raw **`pg`** | triggers (as above). With `DATABASE_URL` set, the agent patches `pg` itself; if your app loads its own copy of `pg` (monorepos), pass it: `ezlogs.init({ ..., patchDatabaseClient: pg })`. | Same |
151
- | **postgres.js** or **Drizzle** on postgres-js | triggers (as above) + `wrapPostgresJs(postgres(url))` (below) | Same |
152
- | Neon HTTP, scripts | triggers (as above) | Writes show up as their own actions, not linked to the request |
153
- | MySQL, SQLite, PlanetScale, no trigger access | a per-ORM adapter: `ezlogsPrisma()`, `ezlogsDrizzleLogger`, `wrapSupabase` ([docs/database.md](./docs/database.md)) | New values only, no before-values |
186
+ </details>
187
+
188
+ ### 5. Capture database changes
189
+
190
+ Steps 1-4 capture requests and Server Actions. This step adds what
191
+ changed in your database: which record, each column from → to, and the
192
+ request and person that made the change. Pick your stack:
193
+
194
+ | Your app writes with | Do this |
195
+ |---|---|
196
+ | **Supabase** (supabase-js), **Drizzle** on node-postgres, raw **`pg`** | [Triggers](#triggers) only |
197
+ | **Prisma** on Postgres | [Triggers](#triggers) + [Prisma extension](#prisma) |
198
+ | **postgres.js**, or **Drizzle** on postgres-js | [Triggers](#triggers) + [wrap `sql`](#postgresjs) |
199
+ | Neon HTTP, scripts | [Triggers](#triggers) (writes show up as their own actions, not linked to the request) |
200
+ | MySQL, SQLite, PlanetScale, no trigger access | A per-ORM adapter: `ezlogsPrisma()`, `ezlogsDrizzleLogger`, `wrapSupabase` ([docs/database.md](./docs/database.md)). New values only, no before-values |
201
+
202
+ #### Triggers
203
+
204
+ Set `DATABASE_URL` (or `POSTGRES_URL`) to your Postgres connection
205
+ string, then run this once from your app's directory:
154
206
 
155
207
  ```bash
156
208
  npm i pg # the trigger installer and reader need it
157
209
  npx ezlogs-nextjs install-triggers
158
210
  ```
159
211
 
160
- Run it from your app's directory with the package installed there
161
- (with bun: `bunx ezlogs-nextjs install-triggers` or
162
- `./node_modules/.bin/ezlogs-nextjs install-triggers`); if the package
163
- isn't installed locally, npx / bunx download whatever version is
164
- published, and the CLI warns. They also download it when your
165
- lockfile's bin entries predate 0.3.0 (seen with bun and a `file:`
166
- dependency); the CLI then prints the command that runs your project's
167
- copy: `node node_modules/ezlogs-nextjs/bin/install-triggers.cjs install-triggers`.
168
- The CLI reads `DATABASE_URL` / `POSTGRES_URL` from your shell or from
169
- `.env`, `.env.local` and `.env.[mode]` (loaded the way Next.js loads
170
- them, incl. `${VAR}` expansion; a variable already set in the shell
171
- wins). Migration tables, database internals, the agent's own audit
172
- table, verification-token tables and session stores (a
173
- `session(s)`-style name **and** a token, expiry, `sess`, `data`,
174
- `payload` or `last_activity` column: Auth.js, Lucia, Rails, Laravel,
175
- connect-pg-simple) are skipped; the output lists each skipped table
176
- with the reason. A `session` table without such columns (analytics
177
- visits, bookings) is tracked. If `pg` or the
178
- audit table is missing at runtime, the agent logs one warning at
179
- startup and leaves the trigger path off.
180
-
181
- **Recommended setup for Prisma** (plain `new PrismaClient()`, or with
182
- a driver adapter such as `@prisma/adapter-pg`): triggers **plus** the
183
- extension, which tags each write with the request so DB changes join
184
- the right action and actor. (`patchPrismaPgAdapter` /
185
- `patchPrismaClient` are legacy; see [docs/database.md](./docs/database.md).)
212
+ The trigger path needs Postgres 10 or newer (Supabase, Neon, RDS and
213
+ every currently supported Postgres qualify).
214
+
215
+ Supabase, Drizzle on node-postgres and raw `pg` need nothing else: the
216
+ agent tags their writes itself, and the triggers record every write
217
+ (supabase-js `.from()`, `.rpc()`, bulk) linked to its request.
218
+
219
+ <details>
220
+ <summary>Trigger details: bun, monorepos, which tables are skipped</summary>
221
+
222
+ - **Monorepos:** with `DATABASE_URL` set, the agent patches `pg`
223
+ itself. If your app loads its own copy of `pg`, pass it:
224
+ `ezlogs.init({ ..., patchDatabaseClient: pg })`.
225
+ - **Run it where the package is installed.** With bun:
226
+ `bunx ezlogs-nextjs install-triggers` or
227
+ `./node_modules/.bin/ezlogs-nextjs install-triggers`. If the package
228
+ isn't installed locally, npx / bunx download whatever version is
229
+ published, and the CLI warns. They also download it when your
230
+ lockfile's bin entries predate 0.3.0 (seen with bun and a `file:`
231
+ dependency); the CLI then prints the command that runs your project's
232
+ copy: `node node_modules/ezlogs-nextjs/bin/install-triggers.cjs install-triggers`.
233
+ - **Env files:** the CLI reads `DATABASE_URL` / `POSTGRES_URL` from your
234
+ shell or from `.env`, `.env.local` and `.env.[mode]` (loaded the way
235
+ Next.js loads them, incl. `${VAR}` expansion; a variable already set
236
+ in the shell wins).
237
+ - **Skipped tables:** migration tables, database internals, the agent's
238
+ own audit table, verification-token tables and session stores (a
239
+ `session(s)`-style name **and** a token, expiry, `sess`, `data`,
240
+ `payload` or `last_activity` column: Auth.js, Lucia, Rails, Laravel,
241
+ connect-pg-simple). The output lists each skipped table with the
242
+ reason. A `session` table without such columns (analytics visits,
243
+ bookings) is tracked.
244
+ - If `pg` or the audit table is missing at runtime, the agent logs one
245
+ warning at startup and leaves the trigger path off.
246
+ - **Self-check:** if writes made while requests or jobs run in a
247
+ process keep arriving untagged, and that process has never sent a
248
+ tagged row, the agent logs one warning naming the fix. It never
249
+ guesses which request an untagged row belongs to.
250
+
251
+ </details>
252
+
253
+ #### Prisma
254
+
255
+ Triggers **plus** this extension (plain `new PrismaClient()`, or with a
256
+ driver adapter such as `@prisma/adapter-pg`). It tags each write with
257
+ the request, so the change joins the right action and person. Add
258
+ `.$extends(ezlogsPrisma())` where your app creates its client, and keep
259
+ your own import path (T3 apps import from `generated/prisma`).
186
260
 
187
261
  ```ts
188
262
  // lib/prisma.ts
@@ -192,6 +266,9 @@ import { ezlogsPrisma } from "ezlogs-nextjs/prisma";
192
266
  export const prisma = new PrismaClient().$extends(ezlogsPrisma());
193
267
  ```
194
268
 
269
+ <details>
270
+ <summary>How the Prisma extension works</summary>
271
+
195
272
  Each write inside a captured request runs as
196
273
  `$transaction([set_config(correlation id, actor id), your query])` (Prisma's
197
274
  documented RLS-extension pattern); reads are untouched. Writes inside
@@ -199,7 +276,19 @@ your own `prisma.$transaction(...)` are not tagged: they still show up,
199
276
  as separate actions without an actor. Without the extension, a plain
200
277
  PrismaClient's writes are never tagged.
201
278
 
202
- **postgres.js / Drizzle on postgres-js** (Vercel Postgres templates,
279
+ Without triggers, the extension still sends Prisma writes itself (new
280
+ values only — Prisma doesn't expose the old row). With triggers it
281
+ sends nothing for tracked tables; the trigger rows are the single
282
+ source, so there are no duplicates (also for `@@map`-ed models).
283
+
284
+ `patchPrismaPgAdapter` / `patchPrismaClient` are legacy; see
285
+ [docs/database.md](./docs/database.md).
286
+
287
+ </details>
288
+
289
+ #### postgres.js
290
+
291
+ For postgres.js and Drizzle on postgres-js (Vercel Postgres templates,
203
292
  `nextjs/saas-starter`): triggers **plus** wrap the `sql` instance once.
204
293
 
205
294
  ```ts
@@ -212,6 +301,9 @@ export const sql = wrapPostgresJs(postgres(process.env.DATABASE_URL!));
212
301
  export const db = drizzle(sql); // Drizzle: pass the wrapped instance
213
302
  ```
214
303
 
304
+ <details>
305
+ <summary>How the postgres.js wrapper works (and its latency cost)</summary>
306
+
215
307
  Each write inside a captured request (``sql`insert …` ``, `sql.unsafe`,
216
308
  Drizzle inserts / updates / deletes) runs as BEGIN; set_config
217
309
  (correlation id, actor); your write; COMMIT on one pooled connection,
@@ -222,28 +314,65 @@ tagged: those writes show up as their own actions. Each tagged write
222
314
  is its own transaction (4 round trips instead of 1), so write latency
223
315
  grows with your database round-trip time.
224
316
 
225
- **Background workers** (BullMQ and other job processes) are separate
226
- processes: call `ezlogs.init` there too and build the database client
227
- the same way (extension for Prisma), or the job's writes show up as
228
- separate actions without an actor.
317
+ </details>
229
318
 
230
- **Self-check:** if writes made while requests or jobs run in a process
231
- keep arriving untagged, and that process has never sent a tagged row,
232
- the agent logs one warning naming the fix. It never guesses which
233
- request an untagged row belongs to.
234
-
235
- Without triggers, the extension still sends Prisma writes itself (new
236
- values only — Prisma doesn't expose the old row). With triggers it
237
- sends nothing for tracked tables; the trigger rows are the single
238
- source, so there are no duplicates (also for `@@map`-ed models).
319
+ <details>
320
+ <summary>Upgrading from an older version</summary>
239
321
 
240
- **Upgrading:** from 0.2.x or 0.3.x there is nothing to re-run before
241
- deploying. From 0.1.x, run `npx ezlogs-nextjs install-triggers --tables=none`
322
+ From 0.2.x or 0.3.x there is nothing to re-run before deploying. From
323
+ 0.1.x, run `npx ezlogs-nextjs install-triggers --tables=none`
242
324
  **before** deploying the new agent (functions only, no table locks),
243
325
  deploy right after, and later re-run `npx ezlogs-nextjs install-triggers`
244
326
  at a quiet moment. Details in [CHANGELOG.md](./CHANGELOG.md).
245
327
 
246
- ### 5. Name your records
328
+ </details>
329
+
330
+ ### 6. Capture background jobs
331
+
332
+ Nothing to add for the runners below. The Next config wrapper from step 3
333
+ instruments them where your server code imports them (aliases such as
334
+ `Client as WorkflowClient` included). Each job then shows up in the same
335
+ action as the request that started it, with the database changes the job
336
+ made:
337
+
338
+ | Runner | Instrumented imports |
339
+ |---|---|
340
+ | Upstash Workflow | `serve`, `servePagesRouter`, `createWorkflow`, `serveMany` from `@upstash/workflow/nextjs`; `Client` from `@upstash/workflow` |
341
+ | QStash | `Client` from `@upstash/qstash` |
342
+ | BullMQ | `Queue`, `Worker` from `bullmq` |
343
+ | Inngest (v3) | `Inngest` from `inngest` (gets `ezlogsInngestMiddleware()`); wrap a function body in `runInsideInngestCorrelation` to link its writes |
344
+
345
+ A workflow step or QStash delivery is one job event: the agent does not
346
+ also record the POST that delivered it.
347
+
348
+ Add these by hand ([docs/jobs.md](./docs/jobs.md)):
349
+
350
+ | Runner | Add |
351
+ |---|---|
352
+ | Trigger.dev | `registerTriggerHooks(tasks)` from `ezlogs-nextjs/trigger` |
353
+ | Supabase Queues (pgmq) | `wrapSupabaseQueueClient` + `captureQueueMessage` from `ezlogs-nextjs/supabase-queues` |
354
+ | Code Next doesn't build (a worker started with `node worker.js`), or `import * as` / `require()` | the same runner's wrapper: `wrapBullWorker`, `wrapWorkflowClient`, … (listed in [docs/jobs.md](./docs/jobs.md)) |
355
+
356
+ Wrapping by hand where the agent already instruments is harmless: each
357
+ job is still recorded once.
358
+
359
+ **Jobs that run in a separate worker process** (for example a BullMQ
360
+ worker you start with `node worker.js`) don't load `instrumentation.ts`.
361
+ In that worker's entry file, start the agent before the worker starts,
362
+ and create the database client the same way as in step 5:
363
+
364
+ ```ts
365
+ // worker.ts (your worker's entry file)
366
+ import { ezlogs } from "ezlogs-nextjs";
367
+
368
+ ezlogs.init({ projectToken: process.env.EZLOGS_PROJECT_TOKEN! });
369
+ // ...then create your Worker as usual
370
+ ```
371
+
372
+ Otherwise the job's database changes show up as separate actions,
373
+ without who made them.
374
+
375
+ ### 7. Name your records
247
376
 
248
377
  Database changes are titled with the record's `name`, `title`,
249
378
  `number` or `label` column. Records of people (users, members,
@@ -289,7 +418,9 @@ logout / sign-in / sign-out / signin / signout / `/session*` path
289
418
  **Auth events are captured:** `POST`s to sign-in, sign-up, sign-out,
290
419
  login and logout routes (NextAuth / Auth.js `/api/auth/*`, custom
291
420
  `/api/login`, …) and auth Server Actions, including failed attempts
292
- (a 4xx response or a returned error). Passwords, tokens and other
421
+ (a 4xx response, a returned error, or a redirect whose target carries
422
+ `error=`, which is how Auth.js and NextAuth report a failed sign-in
423
+ from their API routes). Passwords, tokens and other
293
424
  sensitive params are sent as `"[FILTERED]"`; on auth routes and auth
294
425
  Server Actions (`signIn`, `verifyOtp`, …) one-time codes and OAuth
295
426
  state are too (`code`, `state`, `verification_code`, `otp*`, `pin`,
@@ -0,0 +1,27 @@
1
+ # Third-party licenses
2
+
3
+ `ezlogs-nextjs` bundles part of [sucrase](https://github.com/alangpierce/sucrase) (its parser, 3.35.1) into `dist/nextjs-plugin/loader.*`. Its license:
4
+
5
+ ```
6
+ The MIT License (MIT)
7
+
8
+ Copyright (c) 2012-2018 various contributors (see AUTHORS)
9
+
10
+ Permission is hereby granted, free of charge, to any person obtaining a copy
11
+ of this software and associated documentation files (the "Software"), to deal
12
+ in the Software without restriction, including without limitation the rights
13
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
14
+ copies of the Software, and to permit persons to whom the Software is
15
+ furnished to do so, subject to the following conditions:
16
+
17
+ The above copyright notice and this permission notice shall be included in all
18
+ copies or substantial portions of the Software.
19
+
20
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
21
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
22
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
23
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
24
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
25
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
26
+ SOFTWARE.
27
+ ```
@@ -1,4 +1,4 @@
1
- import { a as ActorFromRequest } from '../configuration-CJ5yKVlP.cjs';
1
+ import { A as ActorFromRequest } from '../configuration-b9pImwFB.cjs';
2
2
 
3
3
  /**
4
4
  * Returns an `ActorFromRequest` that pulls the current user from
@@ -1,4 +1,4 @@
1
- import { a as ActorFromRequest } from '../configuration-CJ5yKVlP.js';
1
+ import { A as ActorFromRequest } from '../configuration-b9pImwFB.js';
2
2
 
3
3
  /**
4
4
  * Returns an `ActorFromRequest` that pulls the current user from
@@ -1,4 +1,4 @@
1
- import { makeAsyncContextCapture, getCurrentActor, current } from './chunk-GI6BM4MR.js';
1
+ import { makeAsyncContextCapture, getCurrentActor, current } from './chunk-IBSNHBUC.js';
2
2
  import { logger } from './chunk-FCFVIRQF.js';
3
3
 
4
4
  // src/triggers/patch-pg.ts
@@ -1,8 +1,8 @@
1
1
  'use strict';
2
2
 
3
- var chunkGMHOUAKD_cjs = require('./chunk-GMHOUAKD.cjs');
4
- var chunkYXZZNZG6_cjs = require('./chunk-YXZZNZG6.cjs');
5
- var chunkMMLQXSSD_cjs = require('./chunk-MMLQXSSD.cjs');
3
+ var chunkO7SFYXJC_cjs = require('./chunk-O7SFYXJC.cjs');
4
+ var chunkB3WST6ES_cjs = require('./chunk-B3WST6ES.cjs');
5
+ var chunkB5ZUQULZ_cjs = require('./chunk-B5ZUQULZ.cjs');
6
6
  var chunkTWTG5ILJ_cjs = require('./chunk-TWTG5ILJ.cjs');
7
7
 
8
8
  // src/jobs/shared.ts
@@ -12,7 +12,7 @@ var ACTOR_TOKEN = /^a([0-9a-f]{2,128})_([0-9a-f]{16})$/;
12
12
  var ACTOR_ID_MAX_BYTES = 64;
13
13
  function emitJobEvent(input) {
14
14
  try {
15
- const config = chunkMMLQXSSD_cjs.configuration();
15
+ const config = chunkB5ZUQULZ_cjs.configuration();
16
16
  if (!config.captureJobs) return;
17
17
  if (config.allExcludedJobClasses().includes(input.jobClass)) return;
18
18
  const sourceData = compactJobSourceData({
@@ -20,33 +20,39 @@ function emitJobEvent(input) {
20
20
  job_id: input.jobId ?? null,
21
21
  queue: input.queue ?? null,
22
22
  retry_count: input.retryCount ?? null,
23
+ step: input.step ?? null,
23
24
  arguments: jobArguments(input.payload)
24
25
  });
25
- const event = chunkYXZZNZG6_cjs.build({
26
+ const event = chunkB3WST6ES_cjs.build({
26
27
  source_type: "background_job",
27
28
  source_data: sourceData,
28
29
  outcome: input.outcome,
29
- correlation_id: input.correlationId ?? chunkMMLQXSSD_cjs.current(),
30
+ correlation_id: input.correlationId ?? chunkB5ZUQULZ_cjs.current(),
30
31
  resource_ids: [],
31
32
  context: null,
32
33
  duration_ms: input.durationMs ?? null,
33
34
  error_message: input.errorMessage ?? null,
34
35
  timestamp: input.startedAt
35
36
  });
36
- chunkYXZZNZG6_cjs.pushEvent(event);
37
+ chunkB3WST6ES_cjs.pushEvent(event);
37
38
  } catch (error) {
38
39
  chunkTWTG5ILJ_cjs.logger.debug(`job emit failed: ${describeError(error)}`);
39
40
  }
40
41
  }
41
42
  async function runJobWithCapture(meta, work) {
42
- const correlationId = meta.correlationId ?? chunkMMLQXSSD_cjs.generate();
43
+ const correlationId = meta.correlationId ?? chunkB5ZUQULZ_cjs.generate();
43
44
  const body = async () => {
44
45
  const startedAt = /* @__PURE__ */ new Date();
45
46
  const startMs = startedAt.getTime();
47
+ const step = meta.step;
46
48
  const baseMeta = {
47
49
  jobClass: meta.jobClass,
48
50
  jobId: meta.jobId ?? null,
49
51
  queue: meta.queue ?? null,
52
+ // Read when the event is built (after the run): the step it executed.
53
+ get step() {
54
+ return (typeof step === "function" ? step() : step) ?? null;
55
+ },
50
56
  retryCount: meta.retryCount ?? null,
51
57
  correlationId,
52
58
  startedAt,
@@ -65,6 +71,10 @@ async function runJobWithCapture(meta, work) {
65
71
  const message = error instanceof Error ? `${error.name}: ${error.message}` : String(error);
66
72
  await flushJobAuditLog(startedAt);
67
73
  if (meta.isControlFlow?.(error)) throw error;
74
+ if (meta.isSuccessfulExit?.(error)) {
75
+ emitJobEvent({ ...baseMeta, outcome: "success", durationMs: Date.now() - startMs });
76
+ throw error;
77
+ }
68
78
  emitJobEvent({
69
79
  ...baseMeta,
70
80
  outcome: "failure",
@@ -74,13 +84,13 @@ async function runJobWithCapture(meta, work) {
74
84
  throw error;
75
85
  }
76
86
  };
77
- const scoped = () => body().finally(chunkMMLQXSSD_cjs.endCorrelationScope);
78
- return chunkMMLQXSSD_cjs.runWithCorrelation(correlationId, () => chunkMMLQXSSD_cjs.runWithActorScope(scoped, meta.actor ?? null));
87
+ const scoped = () => body().finally(chunkB5ZUQULZ_cjs.endCorrelationScope);
88
+ return chunkB5ZUQULZ_cjs.runWithCorrelation(correlationId, () => chunkB5ZUQULZ_cjs.runWithActorScope(scoped, meta.actor ?? null));
79
89
  }
80
90
  var JOB_FLUSH_SKEW_MS = 500;
81
91
  async function flushJobAuditLog(startedAt) {
82
92
  try {
83
- await chunkGMHOUAKD_cjs.flushAuditLog(chunkMMLQXSSD_cjs.configuration().databaseReader, {
93
+ await chunkO7SFYXJC_cjs.flushAuditLog(chunkB5ZUQULZ_cjs.configuration().databaseReader, {
84
94
  since: new Date(startedAt.getTime() - JOB_FLUSH_SKEW_MS)
85
95
  });
86
96
  } catch (error) {
@@ -89,16 +99,16 @@ async function flushJobAuditLog(startedAt) {
89
99
  }
90
100
  function jobArguments(payload) {
91
101
  if (payload === null || payload === void 0) return null;
92
- const patterns = chunkMMLQXSSD_cjs.configuration().excludedGraphqlVariableKeys;
93
- if (Array.isArray(payload)) return payload.length === 0 ? null : chunkYXZZNZG6_cjs.sanitizeArgs(payload, patterns);
102
+ const patterns = chunkB5ZUQULZ_cjs.configuration().excludedGraphqlVariableKeys;
103
+ if (Array.isArray(payload)) return payload.length === 0 ? null : chunkB3WST6ES_cjs.sanitizeArgs(payload, patterns);
94
104
  if (typeof payload === "object" && Object.getPrototypeOf(payload) === Object.prototype) {
95
105
  const rest = { ...payload };
96
106
  delete rest[CORRELATION_PAYLOAD_KEY];
97
107
  delete rest[ACTOR_PAYLOAD_KEY];
98
108
  if (Object.keys(rest).length === 0) return null;
99
- return chunkYXZZNZG6_cjs.sanitizeArgs([rest], patterns)[0];
109
+ return chunkB3WST6ES_cjs.sanitizeArgs([rest], patterns)[0];
100
110
  }
101
- return chunkYXZZNZG6_cjs.sanitizeArgs([payload], patterns);
111
+ return chunkB3WST6ES_cjs.sanitizeArgs([payload], patterns);
102
112
  }
103
113
  function extractCorrelationFromPayload(payload, key = CORRELATION_PAYLOAD_KEY) {
104
114
  if (payload === null || typeof payload !== "object") return null;
@@ -108,7 +118,7 @@ function extractCorrelationFromPayload(payload, key = CORRELATION_PAYLOAD_KEY) {
108
118
  function stampCorrelationOnPayload(payload, key = CORRELATION_PAYLOAD_KEY) {
109
119
  if (!payload || typeof payload !== "object") return payload;
110
120
  if (typeof payload[key] === "string" && payload[key]) return payload;
111
- const id = chunkMMLQXSSD_cjs.current();
121
+ const id = chunkB5ZUQULZ_cjs.current();
112
122
  if (!id) return payload;
113
123
  return { ...payload, [key]: id };
114
124
  }
@@ -126,10 +136,10 @@ function describeError(error) {
126
136
  }
127
137
  function pendingActorToken(correlationId) {
128
138
  try {
129
- const actor = chunkMMLQXSSD_cjs.getCurrentActor();
139
+ const actor = chunkB5ZUQULZ_cjs.getCurrentActor();
130
140
  if (!actor || actor.kind && actor.kind !== "human" || actor.principal) return null;
131
141
  const actorId = actor.id;
132
- const key = chunkMMLQXSSD_cjs.configuration().projectToken;
142
+ const key = chunkB5ZUQULZ_cjs.configuration().projectToken;
133
143
  if (!actorId || !key) return null;
134
144
  const bytes = new TextEncoder().encode(actorId);
135
145
  if (bytes.length > ACTOR_ID_MAX_BYTES) return null;
@@ -157,8 +167,8 @@ ${actorId}`;
157
167
  var tokenMemo = /* @__PURE__ */ new Map();
158
168
  function signedActorToken(correlationId) {
159
169
  const now = pendingActorToken(correlationId);
160
- if (now || chunkMMLQXSSD_cjs.getCurrentActor() || !chunkMMLQXSSD_cjs.configuration().actorFromSupabase) return now;
161
- return chunkMMLQXSSD_cjs.maybeExtractSupabaseActor().then(
170
+ if (now || chunkB5ZUQULZ_cjs.getCurrentActor() || !chunkB5ZUQULZ_cjs.configuration().actorFromSupabase) return now;
171
+ return chunkB5ZUQULZ_cjs.maybeExtractSupabaseActor().then(
162
172
  () => pendingActorToken(correlationId),
163
173
  () => null
164
174
  );
@@ -169,7 +179,7 @@ async function actorToken(correlationId) {
169
179
  async function readActorToken(token, correlationId) {
170
180
  try {
171
181
  const match = typeof token === "string" ? ACTOR_TOKEN.exec(token) : null;
172
- const key = chunkMMLQXSSD_cjs.configuration().projectToken;
182
+ const key = chunkB5ZUQULZ_cjs.configuration().projectToken;
173
183
  if (!match || !key || match[1].length % 2 !== 0) return null;
174
184
  const bytes = new Uint8Array(match[1].match(/../g).map((h) => parseInt(h, 16)));
175
185
  const actorId = new TextDecoder("utf-8", { fatal: true }).decode(bytes);