Observability

Callback hooks for error tracking and performance metrics, compatible with tools like Sentry or Datadog. Pass an ObservabilityHook instance to GustoProvider via config.observability.

ObservabilityHook

Hooks for routing SDK errors and performance metrics into an external monitoring tool.

Remarks

Pass an instance to GustoProvider via config.observability to forward errors to services like Sentry or Datadog and to capture performance metrics for form submissions and component loading. Sanitization is applied before the hooks are invoked; see SanitizationConfig.

Example

import * as Sentry from '@sentry/react'
import { GustoProvider, type ObservabilityHook } from '@gusto/embedded-react-sdk'

const observability: ObservabilityHook = {
  onError: error => {
    Sentry.captureException(error.raw ?? new Error(error.message), {
      level: error.category === 'validation_error' ? 'warning' : 'error',
      tags: {
        error_category: error.category,
        component: error.componentName ?? 'unknown',
        http_status: String(error.httpStatus ?? ''),
      },
    })
  },
  onMetric: metric => {
    console.log(`[Metric] ${metric.name}: ${metric.value}${metric.unit ?? ''}`)
  },
}

<GustoProvider config={{ baseUrl: '/api/', observability }}>
  <YourApp />
</GustoProvider>

Properties

Property	Type	Description
onError?	(error: ObservabilityError) => void	Called when an error is caught by error boundaries or form submission fails. Receives an ObservabilityError — an SDKError enriched with componentName and (for boundary errors) componentStack.
onMetric?	(metric: ObservabilityMetric) => void	Called to track performance metrics for component operations.
sanitization?	SanitizationConfig	Configuration for sanitizing data before sending to observability tools. Default: { enabled: true, includeRawError: false }

Utility types

ObservabilityError

An SDKError enriched with component context for observability telemetry.

Remarks

Delivered to ObservabilityHook.onError. Extends SDKError with timestamp, componentName, and componentStack so error-tracking tools (e.g. Sentry) can correlate and group errors. The base SDKError (without these fields) is the shape exposed through form hooks.

Extends

• SDKError

Properties

Property	Type	Description
category	SDKErrorCategory	High-level error classification
fieldErrors	SDKFieldError[]	Flattened field-level errors from API responses. Empty array for non-field errors.
message	string	Human-readable error summary
timestamp	number	When the error occurred (Unix timestamp in milliseconds)
componentName?	string	SDK component where the error occurred (e.g. "Employee.Profile")
componentStack?	string	React component stack trace (present only for errors caught by ErrorBoundary)
httpStatus?	number	HTTP status code (undefined for non-HTTP errors like network or validation)
raw?	unknown	The original error object for advanced use cases. May be stripped by sanitization (controlled by sanitization.includeRawError).

---

ObservabilityMetric

A performance metric emitted by the SDK to ObservabilityHook.onMetric.

Remarks

Built-in metric names include sdk.form.submit_duration (form submission time) and sdk.component.loading_duration (time spent in loading/suspense state). Tags may include status (success or error) and component when known.

Properties

Property	Type	Description
name	string	Metric name (e.g., 'sdk.form.submit_duration', 'sdk.component.loading_duration')
timestamp	number	When the metric was recorded (Unix timestamp in milliseconds)
value	number	Metric value
tags?	Record<string, string>	Tags for filtering/grouping
unit?	ObservabilityMetricUnit	Metric unit

---

ObservabilityMetricUnit

ObservabilityMetricUnit = "ms" | "count" | "bytes" | "percent"

Unit of measure for an ObservabilityMetric.

---

SanitizationConfig

Configuration for sanitizing error and metric data before it reaches observability hooks.

Remarks

Sanitization runs by default to prevent PII leakage. When enabled, the SDK pattern-redacts SSNs, emails, phone numbers, credit card numbers, and API tokens from messages and tags, and removes values for fields with sensitive names (password, ssn, bankAccount, etc.) from metadata. The raw error object is excluded unless includeRawError is set to true.

Properties

Property	Type	Description
additionalSensitiveFields?	string[]	Additional field names to treat as sensitive (case-insensitive)
customErrorSanitizer?	(error: ObservabilityError) => ObservabilityError	Custom sanitization function for errors
customMetricSanitizer?	(metric: ObservabilityMetric) => ObservabilityMetric	Custom sanitization function for metrics
enabled?	boolean	Whether to sanitize error data. Default: true
includeRawError?	boolean	Whether to include the raw error object on SDKError. Default: false WARNING: Raw errors may contain sensitive data from form inputs or API responses