Hooks
Not available yet. TracePath does not publish a React package, so the hook described here cannot be imported today. See OpenTelemetry for the integration path that works now.
A single hook will expose the capture API inside components, reading the client from the provider's context.
Planned surface
| Function | Description |
|---|---|
captureException(error) | Capture an error with its stack trace |
captureExceptionWithAttributes(error, attributes) | Capture an error with extra context attached |
captureMessage(message) | Send a non-error event. See Messages |
recordAction(category, name, data) | Drop a breadcrumb into the session action timeline |
Calling the hook outside a provider will throw, which is deliberate: it surfaces a missing or misplaced provider at development time instead of silently dropping every event.
Where to call it
The provider already catches render errors, and the SDK already catches uncaught errors and unhandled rejections. What is left for the hook is the middle ground where an error never becomes uncaught:
- Inside a
try/catchin an event handler - In async code whose rejection you handle yourself
- Anywhere you show the user a friendly failure message and swallow the original error
That last case is the one that matters most, because it is precisely the error the dashboard would otherwise never see.
Attribute values must be strings
The ingest endpoint types attributes as a string map and rejects the whole upload with
400 Bad Request if any value is a number, boolean or object. The SDK re-queues a rejected
batch and retries it, so one bad value blocks every later exception and message from that
page too. Convert values before attaching them. TypeScript catches this because the signature
is Record<string, string>; plain .jsx does not.
recordAction
A recorded action does not create an issue on its own. It joins the rolling action buffer next to the automatic network and navigation entries, and ships with the next exception captured in the same session — which is what turns "checkout failed" into "checkout failed, and here is what the user did in the ten seconds before it".
Guidelines
- Do not over-capture. Validation failures and expected 4xx responses are not bugs; the default error filtering already drops most of them.
- Add context where it saves a round trip. Attach the identifiers you would otherwise go looking for in your own logs.
- Handle gracefully. Capturing an error and showing the user something useful are two separate jobs; do both.
- Split by mechanism. Hooks for event handlers, the provider for render errors.
Class components
The context is exported directly, so a class component can read it through contextType and
call the same functions without the hook.