Error Reporting

The error reporting API allows you to manually report errors to telemetry. While the SDK automatically captures unhandled errors and unhandled promise rejections, this API is useful for reporting handled errors, custom error conditions, and framework-specific errors (like React error boundaries).

Critical Error Reporting Behavior:

• Errors are sent asynchronously (non-blocking)
• Errors are transmitted to all configured endpoints
• Errors matching ignoreErrorMessages patterns are not reported
• Errors sent before init() may be queued or dropped
• Invalid error objects may be ignored or converted
• String errors are converted to error events with the string as the message

Capabilities

Report Error

Manually reports an error to be tracked in telemetry.

/**
 * Manually reports an error to be tracked in telemetry
 * @param error - Error message or error object
 * @param opts - Error reporting options (optional)
 * @throws No errors thrown; invalid errors may be ignored
 */
function reportError(error: string | ErrorLike, opts?: ReportErrorOpts): void;

interface ErrorLike {
  message: string;
  name?: string;
  stack?: string;
}

interface ReportErrorOpts {
  /** Component stack trace for React errors */
  componentStack?: string | null | undefined;
  /** Additional attributes to include with the error report */
  attributes?: Record<string, AttributeValueType | AnyValue>;
}

Usage Examples:

import { reportError } from "@dash0/sdk-web";

// Report a string error
reportError("Something went wrong in user flow");

// Report an Error object
try {
  riskyOperation();
} catch (error) {
  reportError(error);
}

// Report with additional context
reportError("Failed to load user data", {
  attributes: {
    "user.id": "user-12345",
    "operation": "fetch_profile",
    "retry_count": 3,
  },
});

// Report with custom error object
reportError({
  message: "Network request failed",
  name: "NetworkError",
  stack: "Error: Network request failed\n    at fetchData (app.js:123)",
});

For IIFE (script tag) usage:

dash0("reportError", "Something went wrong");
dash0("reportError", error);

Critical Behavior:

• Errors are sent asynchronously (non-blocking)
• If SDK is not initialized, errors may be queued or dropped
• String errors are converted to error events with the string as the message
• Component stack is primarily for React error boundaries
• Errors are transmitted to all configured endpoints
• Invalid error objects may be ignored or converted
• Errors matching ignoreErrorMessages patterns are not reported
• Errors with circular references may cause serialization issues

Common Use Cases

Try-Catch Error Handling

Report caught exceptions that you handle in your code:

import { reportError } from "@dash0/sdk-web";

async function loadUserData(userId) {
  try {
    const response = await fetch(`/api/users/${userId}`);
    if (!response.ok) {
      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
    }
    return await response.json();
  } catch (error) {
    // Report the error
    reportError(error, {
      attributes: {
        "user.id": userId,
        "error.context": "user_data_fetch",
      },
    });

    // Show user-friendly error
    showErrorMessage("Failed to load user data");

    // Return fallback data
    return null;
  }
}

Async Error Handling

Report errors from promise chains:

fetchData()
  .then(processData)
  .catch((error) => {
    reportError(error, {
      attributes: {
        "operation": "data_processing",
      },
    });
  });

React Error Boundaries

Use in React error boundaries to report component errors:

import React from "react";
import { reportError } from "@dash0/sdk-web";

class ErrorBoundary extends React.Component {
  componentDidCatch(error, errorInfo) {
    // Report the error with component stack
    reportError(error, {
      componentStack: errorInfo.componentStack,
      attributes: {
        "error.boundary": this.constructor.name,
      },
    });
  }

  render() {
    if (this.state.hasError) {
      return <ErrorFallback />;
    }
    return this.props.children;
  }
}

For React 18+ with functional error boundaries:

import { reportError } from "@dash0/sdk-web";

function App() {
  return (
    <ErrorBoundary
      onError={(error, errorInfo) => {
        reportError(error, {
          componentStack: errorInfo.componentStack,
        });
      }}
    >
      <MyComponent />
    </ErrorBoundary>
  );
}

Validation Errors

Report validation failures with context:

function validateForm(formData) {
  if (!formData.email.includes("@")) {
    reportError("Invalid email format", {
      attributes: {
        "form.id": "registration",
        "field.name": "email",
        "validation.rule": "email_format",
      },
    });
    return false;
  }
  return true;
}

API Errors

Report API-specific errors with response details:

async function callAPI(endpoint, data) {
  try {
    const response = await fetch(endpoint, {
      method: "POST",
      body: JSON.stringify(data),
    });

    if (!response.ok) {
      const errorBody = await response.text();
      reportError(`API Error: ${response.status}`, {
        attributes: {
          "http.url": endpoint,
          "http.status_code": response.status,
          "http.response_body": errorBody,
          "api.endpoint": endpoint,
        },
      });
    }

    return response.json();
  } catch (error) {
    reportError(error, {
      attributes: {
        "api.endpoint": endpoint,
        "error.type": "network",
      },
    });
    throw error;
  }
}

Business Logic Errors

Report application-specific error conditions:

function processPayment(amount, paymentMethod) {
  if (amount > MAX_TRANSACTION_AMOUNT) {
    reportError("Transaction amount exceeds limit", {
      attributes: {
        "transaction.amount": amount,
        "transaction.limit": MAX_TRANSACTION_AMOUNT,
        "payment.method": paymentMethod,
      },
    });
    throw new Error("Amount exceeds maximum allowed");
  }

  // Process payment...
}

Third-Party Integration Errors

Report errors from third-party libraries:

import { reportError } from "@dash0/sdk-web";

// Stripe error handling
stripe.confirmPayment(options)
  .catch((error) => {
    reportError(error, {
      attributes: {
        "integration": "stripe",
        "payment.intent": paymentIntentId,
        "error.code": error.code,
        "error.decline_code": error.decline_code,
      },
    });
  });

// Analytics error handling
analytics.track("event").catch((error) => {
  reportError(error, {
    attributes: {
      "integration": "analytics",
      "event.name": "custom_event",
    },
  });
});

Custom Error Classes

Report custom error types:

class AuthenticationError extends Error {
  constructor(message, userId) {
    super(message);
    this.name = "AuthenticationError";
    this.userId = userId;
  }
}

try {
  authenticateUser(credentials);
} catch (error) {
  if (error instanceof AuthenticationError) {
    reportError(error, {
      attributes: {
        "error.type": "authentication",
        "user.id": error.userId,
      },
    });
  } else {
    reportError(error);
  }
}

Timeout Errors

Report operation timeouts:

async function fetchWithTimeout(url, timeout = 5000) {
  const controller = new AbortController();
  const timeoutId = setTimeout(() => controller.abort(), timeout);

  try {
    const response = await fetch(url, { signal: controller.signal });
    clearTimeout(timeoutId);
    return response;
  } catch (error) {
    clearTimeout(timeoutId);

    if (error.name === "AbortError") {
      reportError("Request timeout", {
        attributes: {
          "url": url,
          "timeout.ms": timeout,
          "error.type": "timeout",
        },
      });
    } else {
      reportError(error);
    }

    throw error;
  }
}

Error Attributes

Common attributes to include with error reports:

• user.id - User identifier for user-specific debugging
• error.context - Context where the error occurred
• operation - Operation being performed
• retry_count - Number of retry attempts
• error.type - Category of error (network, validation, etc.)
• component - Component or module name
• error.recoverable - Whether the error is recoverable

Automatic Error Tracking

The SDK automatically tracks:

• Unhandled JavaScript errors
• Unhandled promise rejections
• Errors in wrapped event handlers (if wrapEventHandlers: true)
• Errors in wrapped timers (if wrapTimers: true)

Use reportError() for:

• Handled errors in try-catch blocks
• Framework-specific errors (React error boundaries)
• Business logic errors
• Validation errors
• Custom error conditions

Edge Cases and Error Conditions

Error Object Handling

• String Errors: String errors are converted to error events with the string as the message
• Missing Properties: If error object is missing message, behavior is undefined
• Invalid Stack: Invalid stack traces are preserved as-is
• Circular References: Error objects with circular references may cause serialization issues
• Non-Error Objects: Non-Error objects may be converted or ignored
• Error Subclasses: Error subclasses are handled the same as standard Error objects
• Error Properties: Custom properties on Error objects may be included in attributes

Component Stack

• React Only: Component stack is primarily for React error boundaries
• Null/Undefined: Null or undefined component stack is ignored
• Format: Component stack format is framework-specific
• Very Long Stacks: Very long component stacks may be truncated
• Invalid Format: Invalid component stack formats are preserved as-is

Initialization

• Before Init: If reportError() is called before init(), errors may be queued or dropped
• After Init: Errors reported after initialization are transmitted immediately
• Multiple Init: If init() is called multiple times, errors are sent to all configured endpoints
• Init Failure: If initialization fails, queued errors may be lost

Network and Transmission

• Offline Mode: Errors are queued when offline and transmitted when online
• Network Failures: Network failures do not throw errors; errors may be queued or dropped
• Transmission Delays: Errors are sent asynchronously; transmission delays are not reported
• Rate Limiting: Endpoints may rate limit errors; SDK may retry or drop errors
• Multiple Endpoints: Errors are sent to all configured endpoints
• Partial Failures: If one endpoint fails, errors are still sent to other endpoints
• Transmission Timeouts: Transmission timeouts may cause errors to be dropped

Performance

• High Frequency: Reporting many errors quickly may impact performance
• Large Attributes: Large error attributes may impact transmission performance
• Error Queuing: If transmission is slow, errors may be queued in memory
• Memory Usage: Queued errors may increase memory usage if transmission is slow
• CPU Usage: Error serialization may increase CPU usage

Multiple Endpoints

• All Endpoints: Errors are sent to all configured endpoints
• Partial Failures: If one endpoint fails, errors are still sent to other endpoints
• Endpoint Errors: Endpoint errors do not affect other endpoints
• Endpoint Ordering: Endpoints are processed in order; order may affect performance

Error Filtering

• Ignore Patterns: Errors matching ignoreErrorMessages patterns are not reported
• Pattern Matching: Error messages are matched against regex patterns
• Case Sensitivity: Pattern matching may be case-sensitive or case-insensitive depending on regex
• Partial Matches: Partial matches to ignore patterns are not blocked; only full matches are blocked
• Pattern Performance: Complex regex patterns may impact performance

Attribute Edge Cases

• Invalid Attributes: Invalid attribute values may be ignored or converted
• Very Many Attributes: Very many attributes may impact transmission performance
• Very Large Attributes: Very large attribute values may be truncated
• Reserved Attributes: Reserved attribute names may be overwritten by SDK
• Attribute Conflicts: Attribute conflicts are resolved in favor of SDK attributes

Stack Trace Edge Cases

• Missing Stack: Errors without stack traces are still reported
• Very Long Stacks: Very long stack traces may be truncated
• Source Maps: Source map resolution is not performed by SDK
• Minified Code: Stack traces from minified code may be difficult to read
• Cross-Origin Errors: Cross-origin errors may have limited stack trace information

Error Message Edge Cases

• Empty Messages: Empty error messages may be ignored or cause issues
• Very Long Messages: Very long error messages may be truncated
• Special Characters: Special characters in error messages are preserved
• Unicode Characters: Unicode characters in error messages are preserved
• Control Characters: Control characters in error messages may be filtered