next-observer 0.3.18 → 0.3.19

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 (2) hide show
  1. package/README.md +87 -20
  2. package/package.json +4 -3
package/README.md CHANGED
@@ -1,40 +1,101 @@
1
1
  # next-observer
2
2
 
3
- The observer for **[next-observe](https://www.npmjs.com/package/next-observe)**: an OTLP collector, a trace UI, an anomaly
4
- detector and AI agents (Google ADK) that investigate your Next.js app on their own. Run it with `npx` — it never goes
5
- into your app's dependencies.
3
+ The **observer** for Next.js: one process that receives your app's telemetry, shows it, and has **AI agents** investigate
4
+ it. A server, a UI, an anomaly detector and the agents — started with `npx`, never installed into your app.
6
5
 
7
6
  ```bash
8
- npx next-observer dev # observer + UI on http://127.0.0.1:4318, then `next dev` in the current directory
7
+ npx next-observer init # once: connects the app (installs the APM agent, next-observe, into it)
8
+ npm run observe # the observer + `next dev`; open http://127.0.0.1:4318
9
9
  ```
10
10
 
11
- - **Trace UI** — list + waterfall, no Docker, no external backend
12
- - **Chat with agents** that query your telemetry: slow operations, regressions between deployments, failing operations
13
- with exact errors, N+1 patterns — with evidence cards built from the data, not by the model
14
- - **Anomaly detector** that starts an investigation by itself when error rates or latency jump
15
- - **Cold starts are not regressions:** the first request of a route after a server start (in `next dev` it includes
16
- compiling the route) is left out of latency stats and the detector, and marked in traces (needs next-observe ≥ 0.2.2)
11
+ No app at hand? `npx next-observer collector --demo` starts the observer with a sample shop that has four things to
12
+ find: a deployment that made checkout slower, a failing endpoint, an N+1 query, and an error the last deployment brought.
17
13
 
18
- Requires Node.js 22.18+. The app is instrumented with `next-observe` (see its README).
14
+ ![Overview: requests, latency, errors, and a banner saying the last deployment looks like a regression](https://raw.githubusercontent.com/ataztech910/nextjs-observe/master/docs/screenshots/overview.png)
15
+
16
+ ## Two packages, one letter apart
17
+
18
+ | | [`next-observe`](https://www.npmjs.com/package/next-observe) | [`next-observer`](https://www.npmjs.com/package/next-observer) |
19
+ |---|---|---|
20
+ | **What it is** | the **APM agent** | the **observer** — a server with a UI and **AI agents** |
21
+ | **Where it runs** | inside your Next.js app (a dependency) | next to the app, started with `npx` (never a dependency) |
22
+ | **What it does** | collects telemetry and sends it | receives telemetry, shows it, investigates it |
23
+ | **Contains AI?** | no — OpenTelemetry only | yes — the AI agents live here |
24
+
25
+ ```
26
+ your Next.js app the observer
27
+ ┌──────────────────────────┐ ┌──────────────────────────────────┐
28
+ │ next-observe │ traces │ next-observer (port 4318) │
29
+ │ the APM agent │ ───────────▶ │ server · UI · anomaly detector │
30
+ │ collects and sends │ OTLP/HTTP │ AI agents that investigate │
31
+ └──────────────────────────┘ └──────────────────────────────────┘
32
+ ```
33
+
34
+ **Two kinds of "agent" — they are not the same thing:**
35
+
36
+ - **APM agent** = `next-observe`. The classic meaning from application performance monitoring: a library inside the app
37
+ that records what happens (requests, timings, errors) and ships it out. It decides nothing.
38
+ - **AI agents** = inside `next-observer`. Language models with tools that query the recorded telemetry and answer
39
+ "what is slow, since which deployment, and where in the code". They never run inside your app.
40
+
41
+ ## What you get
42
+
43
+ **Overview** — requests by status class, latency and 5xx rate, each compared with the period before; the slowest and
44
+ the busiest routes. When the latest deployment made a route slower or more error-prone, a banner says so with the
45
+ measured numbers, and **Investigate** hands the question to the AI agents.
46
+
47
+ **AI agents that investigate — asked or on their own.** The anomaly detector watches incoming traces; when errors or
48
+ latency jump it starts an investigation by itself. The agents get facts only from tools over your telemetry, and the
49
+ evidence cards under a report are built by code from those tool results, not written by the model.
50
+
51
+ ![Chat: the detector noticed slow requests and the AI agents traced them to a function and a deployment](https://raw.githubusercontent.com/ataztech910/nextjs-observe/master/docs/screenshots/chat.png)
52
+
53
+ **Errors as defects** — one entry per "this operation fails with this message", not per failed request: where the
54
+ error originated, which requests fail because of it, when it was first seen, and whether the last deployment brought it.
55
+
56
+ ![Errors: two defects, the first marked NEW IN V2](https://raw.githubusercontent.com/ataztech910/nextjs-observe/master/docs/screenshots/errors.png)
57
+
58
+ **Traces** — a waterfall, the critical path (the spans that decided the duration), each operation's own time, and how
59
+ this call compares with the others of its kind.
60
+
61
+ ![A trace with the critical path highlighted and a table of where the time went](https://raw.githubusercontent.com/ataztech910/nextjs-observe/master/docs/screenshots/trace.png)
62
+
63
+ **One operation up close** — its latency distribution, and a note when the calls fall into two clearly separate speeds
64
+ (a fast and a slow path, or the version before and after a deployment).
65
+
66
+ ![An operation page: details per version and a latency histogram with two speeds](https://raw.githubusercontent.com/ataztech910/nextjs-observe/master/docs/screenshots/operation.png)
67
+
68
+ **Copy prompt** — on a trace, a defect or a finished investigation: a ready prompt for a coding agent (Claude Code,
69
+ Cursor, …) with the measured facts and the task, so the fix starts from data instead of a retelling.
70
+
71
+ Also: cold starts are not regressions (the first request of a route after a server start is left out of latency and
72
+ marked), no Docker and no external backend, and it accepts OTLP/HTTP from any OpenTelemetry SDK — not only `next-observe`.
73
+
74
+ Requires Node.js 22.18+.
19
75
 
20
76
  ## Commands
21
77
 
22
78
  ```bash
23
79
  next-observer init [--root <dir>] [--proxy] # connect a Next.js app (see below)
24
- next-observer dev [--root <dir>] [--port <n>] [-- <next dev args>] # observer + next dev
25
- next-observer collector [--host <h>] [--port <n>] [--api-key <k>] [--ui-password <p>] [--demo]
80
+ next-observer dev [--root <dir>] [--port <n>] [-- <next dev args>] # the observer + your app's `next dev`
81
+ next-observer collector [--host <h>] [--port <n>] [--api-key <k>] [--ui-password <p>] [--demo] # the observer alone
26
82
  ```
27
83
 
28
84
  Run them with `npx next-observer <command>`; installed globally (`npm i -g next-observer`) the command is also
29
85
  available as `nxo`.
30
86
 
31
- `next-observer init` installs `next-observe` with the project's package manager, wraps the exported `next.config` in
87
+ `next-observer init` installs the APM agent, `next-observe`, with the project's package manager, wraps the exported `next.config` in
32
88
  `withObserve()`, creates `instrumentation.ts` and `instrumentation-client.ts` (in `src/` when the app lives there; `.js`
33
89
  without TypeScript) and adds an `observe` script. Already connected files stay untouched; an existing `register()` is
34
90
  never rewritten — init says what to add. `--proxy` also creates the runtime proxy route for browser spans.
35
91
 
36
- `next-observer collector` runs the observer alone — next to `next dev` in another terminal, or on a server for production.
37
- `--demo` preloads a sample "shop" scenario (a regression between versions, a failing endpoint, an N+1) and keeps sending live v2 traffic, so the detector and the agents have something to find without an app.
92
+ `next-observer dev` is a convenience for local work: it starts the observer and then your app's own `next dev` in the
93
+ same terminal. The app stays yours — the observer only launches it.
94
+
95
+ `next-observer collector` runs the observer alone — next to `next dev` in another terminal, or on a server for
96
+ production. ("Collector" is the OpenTelemetry word for the server that receives telemetry; here it comes with the UI,
97
+ the detector and the AI agents.) `--demo` preloads the sample shop and keeps sending live traffic, so the detector and
98
+ the AI agents have something to find without an app.
38
99
 
39
100
  ## On a server
40
101
 
@@ -47,16 +108,21 @@ next-observer collector --host 0.0.0.0 --api-key <ingest key> --ui-password <pas
47
108
  `--api-key` is for the apps sending traces (`OBSERVE_API_KEY` in the app), `--ui-password` for the people opening the
48
109
  UI and the chat (the browser asks for it). `/health` stays open for uptime checks. Without them the banner warns.
49
110
 
50
- ## Models
111
+ ## Models for the AI agents
51
112
 
52
113
  | `OBSERVE_AI` | Model |
53
114
  |---|---|
54
- | `mock` (default) | deterministic stand-in — the whole pipeline runs without tokens |
115
+ | `mock` (default) | deterministic stand-in — the whole pipeline runs without a model, tokens or a network |
55
116
  | `real` | Gemini when `GEMINI_API_KEY` + `GEMINI_MODEL` are set, otherwise [Kitana](https://www.npmjs.com/package/@kitana-sdk/adk) (Claude / Codex CLI, Ollama, API keys) |
56
117
 
57
- ## Your own specialists
118
+ One investigation makes 7–12 model calls. A call that hangs is started again once; "too many requests" (429) and
119
+ "overloaded" (5xx) are waited for and retried — up to a minute, as the provider asks. A free Gemini tier allows only a
120
+ few requests per minute, so an investigation may pause for that minute; a key without credits, a wrong key or a wrong
121
+ model name is explained in the chat in plain words.
122
+
123
+ ## Your own AI agents
58
124
 
59
- Put `observe.agents.ts` (or `.mts`, `.js`, `.mjs`) in the app root. A specialist with a built-in name
125
+ The built-in AI agents are an orchestrator and three specialists (latency, errors, traffic). To change them, put `observe.agents.ts` (or `.mts`, `.js`, `.mjs`) in the app root. A specialist with a built-in name
60
126
  (`latency_agent`, `error_agent`, `traffic_agent`) replaces it; a new name adds one. The orchestrator picks specialists by
61
127
  their `description`; the rules "facts from tools only" and "own tools only" are added to every instruction.
62
128
 
@@ -82,6 +148,7 @@ Tools: `get_services`, `get_operation_stats`, `compare_versions`, `get_errors`,
82
148
  |---|---|---|
83
149
  | `OBSERVE_AI` | `mock` | `mock` \| `real` |
84
150
  | `OBSERVE_DETECTOR` | on | `off` disables the anomaly detector |
151
+ | `OBSERVE_MODEL_TIMEOUT_MS` | `90000` | how long one model call may take before it is started again |
85
152
  | `OBSERVE_API_KEY` | — | require `x-api-key` on ingest (`/v1/traces`) |
86
153
  | `OBSERVE_UI_PASSWORD` | — | require a password for the UI, the query API and the chat (browser login, any user name) |
87
154
  | `OBSERVE_PORT`, `OBSERVE_HOST`, `OBSERVE_ROOT` | `4318`, `127.0.0.1`, `.` | same as `--port`, `--host`, `--root` |
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "next-observer",
3
- "version": "0.3.18",
4
- "description": "The observer for next-observe: OTLP collector, trace UI, anomaly detector and AI agents that investigate your Next.js app. Run with npx next-observer dev.",
3
+ "version": "0.3.19",
4
+ "description": "The observer for Next.js: a server with a UI and AI agents that receives your app's OpenTelemetry traces, shows them and investigates them. Run with npx next-observer dev. The APM agent that goes into the app is next-observe.",
5
5
  "keywords": [
6
6
  "nextjs",
7
7
  "opentelemetry",
@@ -9,7 +9,8 @@
9
9
  "tracing",
10
10
  "ai-agents",
11
11
  "adk",
12
- "collector"
12
+ "collector",
13
+ "apm"
13
14
  ],
14
15
  "author": "Andrei Tazetdinov",
15
16
  "license": "MIT",