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.
- package/README.md +217 -86
- package/THIRD_PARTY_LICENSES.md +27 -0
- package/dist/actors/index.d.cts +1 -1
- package/dist/actors/index.d.ts +1 -1
- package/dist/{chunk-Z2TM3LGG.js → chunk-2NFJOT6Q.js} +1 -1
- package/dist/{chunk-R6IWVTX3.cjs → chunk-65HRY3PW.cjs} +31 -21
- package/dist/{chunk-YXZZNZG6.cjs → chunk-B3WST6ES.cjs} +9 -9
- package/dist/{chunk-MMLQXSSD.cjs → chunk-B5ZUQULZ.cjs} +18 -11
- package/dist/{chunk-NX4EL7BY.cjs → chunk-DM2EAOSF.cjs} +4 -4
- package/dist/chunk-DRE2VXFX.js +19 -0
- package/dist/chunk-H3FC5HMW.cjs +16 -0
- package/dist/{chunk-GI6BM4MR.js → chunk-IBSNHBUC.js} +18 -12
- package/dist/chunk-JWJKFZBW.js +52 -0
- package/dist/{chunk-MHBS5FEP.js → chunk-M3VBQ5KT.js} +27 -4
- package/dist/chunk-NFZ5OKF3.cjs +22 -0
- package/dist/{chunk-GMHOUAKD.cjs → chunk-O7SFYXJC.cjs} +37 -13
- package/dist/{chunk-U22T7QYY.js → chunk-PK2Z2ABL.js} +13 -3
- package/dist/{chunk-YMIGZYFH.js → chunk-RD47JECJ.js} +1 -1
- package/dist/chunk-RMKGMIV2.js +13 -0
- package/dist/{chunk-NINIAL7M.js → chunk-U3IJV5EJ.js} +1 -1
- package/dist/chunk-VJR4VB4B.cjs +56 -0
- package/dist/{chunk-PS4U2GFJ.cjs → chunk-YO6E763S.cjs} +5 -5
- package/dist/{configuration-CJ5yKVlP.d.cts → configuration-b9pImwFB.d.cts} +2 -2
- package/dist/{configuration-CJ5yKVlP.d.ts → configuration-b9pImwFB.d.ts} +2 -2
- package/dist/db/drizzle.cjs +3 -3
- package/dist/db/drizzle.js +2 -2
- package/dist/db/postgres-js.cjs +4 -4
- package/dist/db/postgres-js.js +2 -2
- package/dist/db/prisma.cjs +12 -12
- package/dist/db/prisma.js +2 -2
- package/dist/db/supabase.cjs +42 -17
- package/dist/db/supabase.d.cts +11 -5
- package/dist/db/supabase.d.ts +11 -5
- package/dist/db/supabase.js +33 -9
- package/dist/index.cjs +288 -142
- package/dist/index.d.cts +2 -2
- package/dist/index.d.ts +2 -2
- package/dist/index.js +198 -52
- package/dist/jobs/bullmq.cjs +44 -16
- package/dist/jobs/bullmq.d.cts +7 -1
- package/dist/jobs/bullmq.d.ts +7 -1
- package/dist/jobs/bullmq.js +33 -6
- package/dist/jobs/inngest.cjs +36 -17
- package/dist/jobs/inngest.d.cts +7 -1
- package/dist/jobs/inngest.d.ts +7 -1
- package/dist/jobs/inngest.js +23 -5
- package/dist/jobs/supabase-queues.cjs +9 -9
- package/dist/jobs/supabase-queues.js +4 -4
- package/dist/jobs/trigger.cjs +7 -7
- package/dist/jobs/trigger.js +4 -4
- package/dist/jobs/upstash-workflow.cjs +139 -23
- package/dist/jobs/upstash-workflow.d.cts +20 -2
- package/dist/jobs/upstash-workflow.d.ts +20 -2
- package/dist/jobs/upstash-workflow.js +129 -14
- package/dist/nextjs-plugin/index.cjs +46 -29
- package/dist/nextjs-plugin/index.js +46 -29
- package/dist/nextjs-plugin/loader.cjs +70 -60
- package/dist/nextjs-plugin/loader.d.cts +18 -1
- package/dist/nextjs-plugin/loader.d.ts +18 -1
- package/dist/nextjs-plugin/loader.js +70 -61
- package/dist/triggers/index.cjs +22 -16
- package/dist/triggers/index.d.cts +0 -10
- package/dist/triggers/index.d.ts +0 -10
- package/dist/triggers/index.js +11 -5
- package/package.json +6 -5
- 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
|
-
|
|
30
|
-
|
|
31
|
-
|
|
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
|
-
|
|
49
|
+
### 1. Install the package
|
|
37
50
|
|
|
38
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
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
|
-
|
|
90
|
+
### 3. Wrap your Next config
|
|
67
91
|
|
|
68
|
-
|
|
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
|
-
|
|
82
|
-
under
|
|
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
|
-
|
|
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
|
-
|
|
100
|
-
|
|
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
|
-
|
|
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
|
|
119
|
-
|
|
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
|
-
|
|
132
|
-
|
|
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
|
-
|
|
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
|
-
|
|
144
|
-
need one more step, depending on your stack:
|
|
184
|
+
More in [docs/troubleshooting.md](./docs/troubleshooting.md).
|
|
145
185
|
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
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
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
`
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
**
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
the
|
|
185
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
231
|
-
|
|
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
|
-
|
|
241
|
-
|
|
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
|
-
|
|
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
|
|
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
|
+
```
|
package/dist/actors/index.d.cts
CHANGED
package/dist/actors/index.d.ts
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
'use strict';
|
|
2
2
|
|
|
3
|
-
var
|
|
4
|
-
var
|
|
5
|
-
var
|
|
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 =
|
|
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 =
|
|
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 ??
|
|
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
|
-
|
|
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 ??
|
|
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(
|
|
78
|
-
return
|
|
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
|
|
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 =
|
|
93
|
-
if (Array.isArray(payload)) return payload.length === 0 ? null :
|
|
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
|
|
109
|
+
return chunkB3WST6ES_cjs.sanitizeArgs([rest], patterns)[0];
|
|
100
110
|
}
|
|
101
|
-
return
|
|
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 =
|
|
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 =
|
|
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 =
|
|
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 ||
|
|
161
|
-
return
|
|
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 =
|
|
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);
|