Skip to content

observability.md

Latest commit

 

History

History
153 lines (110 loc) · 6.58 KB

observability.md

File metadata and controls

153 lines (110 loc) · 6.58 KB
Raw
title Observability
description Callback hooks for error tracking and performance metrics, compatible with tools like Sentry or Datadog. Pass an `ObservabilityHook` instance to `GustoProvider` via `config.observability`.
sidebar_position 13
generated_by typedoc
custom_edit_url

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

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