api-tracer-kit 1.0.0 → 1.1.0

package/docs/troubleshooting.md

@@ -0,0 +1,194 @@
+# Troubleshooting
+
+## Nothing is being recorded
+
+Work down this list in order. Each step tells you which link in the chain is
+broken, so you never have to guess.
+
+### 1. Is the tracer running at all?
+
+Open your app and look at the **browser** console. With `debug: true` or a log
+of your own you should see the tracer start. If you see nothing, `init()` never
+ran — the package is installed but nothing imported it.
+
+**Installing a package does not run it.** Something must import the module that
+calls `init()`, and that module must be reachable from your entry point:
+
+```js
+// src/index.js
+import './services/apiRecorder';
+```
+
+Check the module is actually in the bundle:
+
+```bash
+curl -s http://localhost:3000/static/js/bundle.js | grep -c 'api-tracer-kit'
+```
+
+Zero means it is not being compiled in.
+
+### 2. Is it configured the way you think?
+
+Inspect the live tracer from the browser console:
+
+```js
+const t = globalThis[Symbol.for('api-tracer-kit.registry')].tracer;
+({ active: t.isActive, patches: t.uninstallers.length, excludes: t.options.exclude.map(String) });
+```
+
+| What you see | What it means |
+| --- | --- |
+| `active: false` | `init()` never ran |
+| `excludes: []` when you passed `reportTo` | **your options were ignored — see below** |
+| `patches: 3` when you passed `transports: []` | same cause |
+
+**The most common cause of a tracer that runs but reports nothing is a second
+`init()`.** It is idempotent — a second call keeps the first one's configuration
+so it cannot install a second set of interceptors and double-count every
+request. Since 1.0.1 it warns:
+
+```
+[api-tracer] init() was called again on a tracer that is already running, so these
+options were ignored: reportTo, transports, envelope.
+```
+
+Find every call and keep exactly one:
+
+```bash
+grep -rn 'apiTracer.init\|initApiTracer' src/
+```
+
+### 3. Is your app actually making API calls?
+
+An app sitting on a login screen may make none. Check the Network tab, or:
+
+```js
+globalThis[Symbol.for('api-tracer-kit.registry')].tracer.getTraces().length;
+```
+
+Traces above zero means the tracer works and the problem is downstream — go to
+step 5. Zero traces with calls visible in the Network tab means the transport
+carrying them is not patched — step 4.
+
+### 4. Is the right transport patched?
+
+`transports: []` patches **nothing globally**. That is correct when you only
+want axios, but it means plain `fetch` and `XMLHttpRequest` calls are invisible.
+
+axios instances need `useAxios()`; there is no global to patch. And it must
+cover the instance your code actually uses — `useAxios(axios)` covers the
+default export and everything `axios.create()` makes **after** that call, so
+`init()` has to run before your API layer creates its instances.
+
+### 5. Are traces reaching the console?
+
+```bash
+curl -s http://127.0.0.1:4400/api/live | python3 -c 'import json,sys; print(json.load(sys.stdin)["count"])'
+```
+
+Still zero with traces in memory? The reporter is failing. It fails **silently
+by design** — a console that is not running must never affect your app — so look
+at the Network tab for the POST to `/api/record`.
+
+| | |
+| --- | --- |
+| No request at all | `reportTo` is not set. Back to step 2. |
+| `404` | Path mismatch. If `reportTo` is `/api-console`, the console must run with `BASE_PATH=/api-console`. |
+| CORS error | Add your app's origin to `ALLOWED_ORIGINS`. Localhost always works. |
+| `ERR_CONNECTION_REFUSED` | The console is not running, or is on a different port. |
+| Blocked, mixed content | An HTTPS app cannot post to an `http://` console. Serve the console over TLS or under a path on the app's own origin. |
+
+### 6. Are you looking at the right app?
+
+If port 3000 was taken, CRA silently starts on 3001 — and you may be browsing a
+different project entirely:
+
+```bash
+lsof -nP -iTCP:3000 -sTCP:LISTEN
+```
+
+## The scan finds no endpoints
+
+```bash
+npx api-tracer init
+```
+
+It prints what each preset found:
+
+```
+  service-object   325
+  fetch-direct       1
+  axios-direct       0
+```
+
+All zero means no preset reads your codebase. Check `sources` covers where your
+API layer lives, then either force one with `--preset`, or write a `parse`
+function — see [Configuration](./configuration.md#your-own-scanner).
+
+Live recording works without a catalog: every call is adopted as an endpoint of
+its own.
+
+## Endpoints list, but nothing is captured
+
+Those are independent. The list comes from the console reading your source; the
+captures come from your app posting traffic. A working list tells you nothing
+about the tracer. Go to step 1 above.
+
+## `Module not found: ... falls outside of the project src/ directory`
+
+CRA's `ModuleScopePlugin`. You imported by relative path. Import by package
+name; see [Frameworks → CRA](./frameworks.md#create-react-app).
+
+## `Package "api-tracer-kit" refers to a non-existing file`
+
+Yarn 1 resolving a relative `file:` path wrongly. Use a packed tarball, or a
+published version. See [Frameworks → CRA](./frameworks.md#create-react-app).
+
+## A second React, or "invalid hook call"
+
+`yarn add file:<directory>` copies the whole directory, **including its own
+`node_modules`** — React among them. Two Reacts in one build breaks hooks. A
+registry install or a packed tarball ships only what `files` allows.
+
+## Every call is recorded twice
+
+Two `init()` calls on separate instances, or a second copy of the package in the
+build. The shared tracer is held in a global registry so entry points agree; a
+duplicate usually means two different versions are installed.
+
+```bash
+npm ls api-tracer-kit
+```
+
+axios calls are **not** a cause: a call seen by both the axios and XHR adapters
+is recorded once.
+
+## Response bodies are missing
+
+Check `response.bodyOmitted`:
+
+| | |
+| --- | --- |
+| `too-large` | over `maxBodyBytes` (default 200 kB). Raise it if you need them. |
+| `stream` | `text/event-stream`. Never buffered, deliberately. |
+| `binary` | a non-textual content type. Described, not read. |
+| `unreadable` | the body could not be cloned or parsed. |
+
+## A response body is `<redacted>`
+
+A field whose **name** matched `redactFields`, or a header matching
+`redactHeaders`. That is working as intended. Narrow the pattern if it is too
+eager — but see [Security](./security.md) first.
+
+## The app broke after adding the tracer
+
+It should not have; that is the package's first design constraint. Confirm by
+removing it:
+
+```js
+apiTracer.destroy();
+```
+
+That restores every patched global and axios adapter. If the problem survives
+`destroy()`, it is not the tracer. If it does not, please open an issue with the
+transport and the call shape.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "api-tracer-kit",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Trace every API call an app makes, and map, exercise and monitor the endpoints it has.",
   "keywords": [
     "api",
@@ -50,6 +50,7 @@
   "files": [
     "dist",
     "cli",
+    "docs",
     "README.md",
     "LICENSE",
     "CHANGELOG.md"