Verification and common problems - Node.js

A controlled event

await ray.captureMessage('DockRay control message');

Reporting methods return a promise - in a script that exits right after the call, precede it with await or wrap it in ray.report(), otherwise the process can shut down before the request leaves.

Common problems

ray.enabled is false despite the variables being set

The client never reads process.env on its own - credentials always reach the constructor explicitly, as in the examples in this section. Check that token and privateKey really arrived as non-empty strings; an empty string counts the same as no value at all.

The build fails to compile in an edge runtime or on Cloudflare Workers

The symptom is usually a bundler error along the lines of "Module not found: Can't resolve 'node:fs'". The package's main entry point imports node:fs, node:os and node:zlib, which such a bundle cannot resolve. Import @dockcodes/dock-ray/edge instead of the main entry point - the API stays the same, only stack source context and gzip compression disappear.

installGlobalHandlers() does nothing until you call it

Catching uncaught process failures is off by default - it has to be turned on deliberately, because it changes how the process ends on a fatal error. After calling ray.installGlobalHandlers(), a reported uncaughtException ends with a call to process.exit(1), unless you pass { exitOnUncaught: false }. An unhandledRejection is only reported and does not end the process.

Some events disappear under heavy load

The report() queue holds at most 50 concurrent reports for the whole process; anything beyond that is dropped with no trace in the log. Check sampleRate too if it has been lowered - it defaults to 1 and sends everything.

Transactions fragment into thousands of different rows

A transaction's name comes from the route pattern registered with the router (req.route.path in Express, routerPath in Fastify). If the adapter runs on a request that never reached a registered handler - a 404 response, middleware placed before the router - there is no pattern to use, and the name falls back to the raw path from the address, so every distinct address becomes its own row.

4xx codes do not reach the panel as errors

That is the default shouldReport working as intended: only 5xx responses are reported, because a 4xx is usually the caller getting it wrong, not the application failing. Pass your own shouldReport function to the adapter to change that.

The panel answers 200 but there is no event

A 200 {"success": false} response means the account has used up its monthly error quota. The integration does not treat that as a failure - and rightly so. You can see the quota on the account dashboard; until the end of the month it is counted from recorded usage, so deleting errors does not reset it.

Still not working

Work through the troubleshooting checklist, and if that does not help, write to us. Include the project name, the integration version and roughly when you ran the test: it shortens the way to an answer.