Skip to main content

Track Errors

Source reviewed: 2026-11-15 against the released Custd SDK 3.43.3.

Custd groups application errors into issues, with occurrence counts, release, environment and bounded code locations. Open Errors (/errors) to investigate, resolve or ignore them. A resolved issue that returns from a later release is a regression. Native Custd SDKs send directly to your configured Custd deployment; no external error-reporting SDK or collector is required.

Choose the tenant and Site first​

Sign in with your existing authorized tenant account. Before provisioning, run:

custdctl config current
custdctl auth status --profile prod
custdctl account --profile prod

Check the returned account and company, not just the profile's name. An internal project belongs to its existing company: give it a project-owned data scope, resource, Sites and producers; do not create a company for each application. HaakCo-owned applications use the existing haakco company. Keep unrelated projects' privacy, retention and desired-state declarations unchanged.

With tenant-administrator access, open Admin → Sites (/admin?tab=sites). Create separate project-named Sites for independently operated applications:

  • Browser Site: configure the exact allowed origins. Only its public write key may enter browser configuration.
  • Server Site: leave origins empty. Its key is a server credential and must stay in the application's secret manager, never a browser or mobile bundle.

The write key is shown once on create or rotation. Store server keys through the approved secret handoff. Rotation invalidates the previous key; do not rotate a working key merely to retrieve it. Error capture uses the SDK's baseUrl and writeKey configuration; applications must not construct collector envelopes.

Browser and React​

Install the released SDK from its public source:

pnpm add '@haakco/custd-sdk@github:haakco/custd-sdk#v3.43.3&path:/sdk-js'

Read the public Browser Site configuration from your application's existing configuration owner, then install capture at its lifecycle boundary:

import { ErrorCaptureClient, installBrowserErrorCapture } from '@haakco/custd-sdk'

const errors = new ErrorCaptureClient({
baseUrl: publicConfig.custdBaseUrl,
writeKey: publicConfig.custdBrowserWriteKey,
environment: publicConfig.environment,
release: publicConfig.release,
})
const removeCapture = installBrowserErrorCapture(errors)
// Call removeCapture() when this application unmounts.

The installer captures browser errors and unhandled promises without preventing their normal handling. A React error boundary reports its caught error with void errors.captureException({ error }) and retains its normal recovery UI. For an authenticated application relay, the installer also accepts an object whose captureException method returns the actual SDK ErrorCaptureResult.

Each client admits at most 20 captures and four concurrent sends, with a 2-second deadline and no retry or persisted queue. The result is accepted, rejected, unavailable or limited; reporting must never change the operation that failed. Preserve local operational errors when Custd is unavailable.

Expo and React Native​

Use the same released JavaScript SDK, without adding a vendor SDK or global polyfills. createErrorCaptureEvent({ error, mode }, { environment, release }) returns a safe typed DTO and requires no Web Crypto, DOM or fetch globals when eventId is omitted. Hermes/Metro bundle code locations are supported.

Send that DTO to your own authenticated application relay. The app must not contain a server Site key, producer credential or tenant-wide reporting token. The relay strictly rejects unknown JSON fields, authenticates the application user, enforces request/rate bounds and supplies its own environment/release and server Site key. The Go SDK's reporter.CaptureEvent(ctx, event) validates the DTO and returns confirmed collector acceptance; local admission is not delivery.

installNativeErrorCapture(errorUtils, capture) accepts an injected React Native ErrorUtils-shaped object. It chains the original handler even when capture fails and returns cleanup that restores only its own handler. The relay adapter owns bounded delivery and account/server teardown; caught React errors still belong in the app's boundary. Do not persist errors across accounts or servers. This is JavaScript error capture, not native OS crash processing. Production Hermes promise rejection tracking has no supported public subscription; do not patch private runtime APIs to imply coverage that the SDK does not provide.

Go and PHP servers​

Use the released native clients documented in the Custd SDK repository:

RuntimeNative ownerLifecycle
GoNewErrorReporter(ErrorCaptureConfig) and ReportOne reporter per process/Site; snapshot the caller before asynchronous delivery, drain with bounded Close
Go relayErrorReporter.CaptureEventRevalidate the mobile DTO and return the real collector result
PHP/LaravelHaakCo\Custd\ErrorTracking\Client and captureException(CaptureRequest)Call from the framework's existing error owner, preserving normal handling and logging

Go's process reporter has four in-flight sends and no pending queue or retry. Report returning true means admitted; Stats().Accepted records delivered acceptance. Request-scoped Go and PHP capture clients each stop at 20 captures; do not retain a request-scoped client forever in a persistent worker.

What leaves the application​

Native SDK capture copies only exception class, bounded code basenames and line/column locations, release/environment, handled state and an optional application-owned ULID correlation ID. It drops messages, arguments, source context, absolute paths, requests, users, credentials and media content before transport. JavaScript/Go events are capped at 16 KiB and 24 code frames; PHP also bounds its exception chain and envelope.

The intake still understands compatible error envelopes, including fields a third-party SDK may send. That compatibility does not provide the native SDK's pre-transport privacy guarantee. Replace the old emitter at its owner rather than running two collectors or assuming a destination change sanitizes its data.

Verify and operate​

Send one controlled content-free error and inspect its typed accepted result, then verify the expected Site/release issue in Errors. A queued report, HTTP status alone or saved settings do not prove the issue arrived. Check safe outcome counters, Site origin/scope configuration and permissions on failure; never print keys, raw envelopes or application data into proof logs.

Keep deployment credentials in the approved secret manager. HaakCo repository commands use just infisical-login for the isolated Docker profile; copying a host login or dumping environment values is not the supported path. A provisioning broker's machine authority is distinct from an authorized human tenant account; do not elevate one or silently borrow the other to bypass a denied operation.

Resolve after releasing the fix; ignore an issue only when that is an intentional operator decision. Optional error alerts are tenant-wide destinations: configure only an agreed mailbox/webhook and verify actual receipt, never a guessed address. See Manage alerts and notifications.

Issues are removed after 90 quiet days since last seen by the scheduler. Accepted error-occurred events separately follow the tenant's raw/archive retention policies. A Site's retentionDays setting does not establish a different issue lifetime.