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. Recognized sensitive values are redacted and raw errors excluded by default before callbacks run; see SanitizationConfig. Select which payload fields to forward. This processing does not detect every PII value or cover data independently collected by your monitoring tool.

Example

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

export const observability: ObservabilityHook = {
  onError: error => {
    Sentry.captureException(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 ?? ''}`)
  },
}

// Pass observability to GustoProvider through config.observability.

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

Configures redaction and raw-error inclusion for observability callbacks.

Remarks

By default, the SDK redacts recognized string patterns in error message and fieldErrors[].message, and recursively redacts sensitive keys and recognized string patterns in fieldErrors[].metadata and metric tags. Sensitive keys include credentials, financial identifiers, personal names, birth dates, addresses, and document identifiers. Values are replaced with placeholders; keys are retained. Other properties are not redacted.

Pattern and key matching do not detect every sensitive value. Free-text names and addresses, for example, may remain in messages. Select which fields to forward in your callbacks and use additional sensitive keys or custom sanitizers for further processing.

Processing order is SDK redaction/raw exclusion, custom sanitizer, SDK redaction/raw exclusion again, then the observability callback. Custom functions receive processed input and their output follows the same configuration. enabled controls redaction independently of includeRawError; opted-in raw errors pass through without redaction.

This configuration applies only to observability callbacks. It does not sanitize form-hook errors, component events, request hooks, or data added by your monitoring integration.

Properties

Property	Type	Description
additionalSensitiveFields?	string[]	Additional sensitive keys in field-error metadata and metric tags. Remarks Uses case-insensitive substring matching in nested objects and arrays, before and after custom sanitizers when redaction is enabled. Matching values are replaced with [REDACTED]. Does not match field-error paths, message text, or properties outside metadata and tags.
customErrorSanitizer?	(error: ObservabilityError) => ObservabilityError	Transforms an error between applications of the configured SDK processing. Remarks Receives an error after configured redaction and raw exclusion. The SDK processes the returned message, fieldErrors[].message, fieldErrors[].metadata, and raw again according to enabled, includeRawError, and additionalSensitiveFields. Other properties are preserved without redaction. Return an error of the same type; messages may be replaced and metadata omitted for additional control over emitted data.
customMetricSanitizer?	(metric: ObservabilityMetric) => ObservabilityMetric	Transforms a metric between applications of the configured SDK redaction. Remarks Receives a metric after configured tag redaction. Returned tags are redacted again, including keys added by your function. Both passes honor enabled and additionalSensitiveFields. Other properties are preserved without redaction.
enabled?	boolean	Whether to redact recognized sensitive values in messages, field-error metadata, and metric tags. Default: true. Remarks When false, built-in and additional-sensitive-key redaction is skipped before and after custom sanitizers. Custom sanitizers still run. Raw errors remain excluded unless includeRawError is true.
includeRawError?	boolean	Whether to include the original error as raw in observability errors. Default: false. Remarks When false, raw is set to undefined before and after a custom error sanitizer, regardless of enabled. When true, raw passes through without redaction and can contain form inputs, API response bodies, and request headers, including credentials.