Privacy and troubleshooting
What the Doclight SDKs collect, what request and tool data can and cannot prove, and how to diagnose missing events.
Applies to npm 0.1.0 of @doclight/core, @doclight/node, @doclight/express and @doclight/mcp.
What is collected
- Automatic integrations do not record request or response bodies, or MCP tool arguments and results.
- The published Express middleware does not collect cookies, query parameters or raw IP addresses.
- Secret-pattern redaction is on by default. It is not a guarantee that arbitrary sensitive content is removed; do not disable it.
- Values you supply (session goals, metadata, context, agent labels, session IDs) are sent as given. Use short, non-sensitive identifiers, never emails, tokens or customer names.
- Structured context is on by default. Set
privacy.captureContext: falseif you do not need it. - Keep keys in a secret manager or deployment environment, and out of source control and browser code.
What the data can and cannot show
Request logs are evidence of access, not intent
Website instrumentation sees HTTP requests that reach your application: route, method, duration, status and a label you supply. It does not reveal an agent's search query, prompt, reasoning or task objective.
- Claimed identity. A
User-Agentorx-agent-idvalue is client-controlled and can be spoofed. It does not prove the vendor. - Failures are friction, not task failure. A
403shows a request was denied, not why the agent came or that its task failed. A slow request does not show the agent got stuck. - Correlation. Without a supplied session ID every request is its own session, so a multi-step journey cannot be reconstructed from independent requests.
- Coverage. Middleware cannot see traffic answered by a CDN, edge cache or upstream static server, or requests a WAF rejects before they reach your app. Missing events do not prove no crawler visited.
- Tool calls. Timing and thrown errors inside an MCP server you control are stronger evidence, but one successful tool call does not mean the whole task completed.
- Different measurement. None of this is Doclight's AI visibility or citation measurement; see metrics.
Troubleshooting
| Symptom | Check |
|---|---|
| No events received | Endpoint and route, credentials, project mapping, middleware order, and the 3-second flush interval |
401 / 403 from ingestion | Credential validity and authorization. Your website's status codes are separate |
404 from ingestion | Wrong base URL, or a service without /v1/events/batch. Do not include the path in endpoint |
droppedInvalid increases | Required fields, event type, metadata bounds (50 keys, 1 KB) |
droppedQueueFull increases | Traffic exceeds send capacity, or ingestion is unavailable |
sent increases but the dashboard is empty | 0.1.0 treats any 2xx as success. Confirm persistence and project mapping on the receiver |
| No data from cached pages | The request was answered before reaching the middleware |
| Events lost on exit | Call shutdown(); the Express and automatic MCP wrappers expose no flush in 0.1.0 |
| MCP protocol errors | Use McpServer for automatic wrapping; keep stdout protocol-only |
| An option from a README does not exist | Compare your installed version with repository main |
Print the installed version with pnpm ls @doclight/node @doclight/express @doclight/mcp @doclight/core, and read
client.getStats() for enqueued, sent, droppedQueueFull, droppedInvalid and failedSends.
Agent guides in the repositories
The Express repository has an agent integration skill
and the Node repository has an agent installation guide.
They track repository main, which is ahead of npm 0.1.0, so review their version assumptions before giving them to a
coding agent. pnpm add does not install them.