Interface IOTelErrorHandlers

Configuration interface for OpenTelemetry error handling callbacks. Provides hooks to customize how different types of errors and diagnostic messages are handled within the OpenTelemetry system.

Example

const errorHandlers: IOTelErrorHandlers = {
  attribError: (message, key, value) => {
    console.warn(`Attribute error for ${key}:`, message);
  },
  spanError: (message, spanName) => {
    logger.error(`Span ${spanName} error:`, message);
  },
  warn: (message) => {
    logger.warn(message);
  },
  error: (message) => {
    logger.error(message);
  }
};

Remarks

If handlers are not provided, default behavior will be used:

  • attribError: Throws an OTelInvalidAttributeError
  • spanError: Logs to console or calls warn handler
  • debug: Logs to console.log
  • warn: Logs to console.warn
  • error: Logs to console.error
  • notImplemented: Logs to console.error

Since

3.4.0

interface IOTelErrorHandlers {
    attribError?: ((message: string, key: string, value: any) => void);
    debug?: ((message: string) => void);
    error?: ((message: string) => void);
    notImplemented?: ((message: string) => void);
    spanError?: ((message: string, spanName: string) => void);
    warn?: ((message: string) => void);
}

Properties

attribError? debug? error? notImplemented? spanError? warn?

Properties

OptionalattribError

attribError?: ((message: string, key: string, value: any) => void)

Handles attribute-related errors, such as invalid attribute values or keys. Called when an attribute operation fails validation or processing.

Type declaration

    • (message, key, value): void

    • Parameters

      • message: string

        Descriptive error message explaining what went wrong

      • key: string

        The attribute key that caused the error

      • value: any

        The attribute value that caused the error (may be of any type)

      Returns void

Remarks

Common scenarios that trigger this handler:

  • Invalid attribute key format
  • Attribute value exceeds length limits
  • Unsupported attribute value type
  • Attribute count exceeds limits

Default

Throws an OTelInvalidAttributeError

Example

attribError: (message, key, value) => {
  metrics.increment('otel.attribute.errors', { key, type: typeof value });
  logger.warn(`Attribute ${key} rejected: ${message}`);
}

Optionaldebug

debug?: ((message: string) => void)

Handles debug-level diagnostic messages. Used for detailed troubleshooting information that is typically only relevant during development or when diagnosing issues.

Type declaration

    • (message): void

    • Parameters

      • message: string

        Debug message to be handled

      Returns void

Remarks

Debug messages are typically:

  • Verbose operational details
  • Internal state information
  • Performance metrics
  • Development-time diagnostics

Default

Logs to console.log

Example

debug: (message) => {
  if (process.env.NODE_ENV === 'development') {
    console.debug('[OTel Debug]', message);
  }
}

Optionalerror

error?: ((message: string) => void)

Handles general error conditions that may affect functionality. Used for significant errors that should be investigated but may not be fatal.

Type declaration

    • (message): void

    • Parameters

      • message: string

        Error message to be handled

      Returns void

Remarks

Error scenarios include:

  • Failed network requests
  • Configuration validation failures
  • Resource allocation failures
  • Unexpected runtime conditions

Default

Logs to console.error

Example

error: (message) => {
  logger.error('[OTel Error]', message);
  errorReporting.captureException(new Error(message));
}

OptionalnotImplemented

notImplemented?: ((message: string) => void)

Handles errors related to unimplemented functionality. Called when a method or feature is not yet implemented or is intentionally disabled in the current configuration.

Type declaration

    • (message): void

    • Parameters

      • message: string

        Message describing the unimplemented functionality

      Returns void

Remarks

Common scenarios:

  • Placeholder methods that haven't been implemented
  • Features disabled in the current build
  • Platform-specific functionality not available
  • Optional features not included in the configuration

Default

Logs to console.error

Example

notImplemented: (message) => {
  logger.warn(`[OTel Not Implemented] ${message}`);
  if (process.env.NODE_ENV === 'development') {
    console.trace('Not implemented method called');
  }
}

OptionalspanError

spanError?: ((message: string, spanName: string) => void)

Handles span-related errors that occur during span operations. Called when a span operation fails or encounters an unexpected condition.

Type declaration

    • (message, spanName): void

    • Parameters

      • message: string

        Descriptive error message explaining the span error

      • spanName: string

        The name of the span that encountered the error

      Returns void

Remarks

Common scenarios that trigger this handler:

  • Span operation called on an ended span
  • Invalid span configuration
  • Span processor errors
  • Context propagation failures

Default

Logs to console or calls the warn handler

Example

spanError: (message, spanName) => {
  metrics.increment('otel.span.errors', { span_name: spanName });
  logger.error(`Span operation failed for "${spanName}": ${message}`);
}

Optionalwarn

warn?: ((message: string) => void)

Handles warning-level messages for non-fatal issues. Used for conditions that are unusual but don't prevent continued operation.

Type declaration

    • (message): void

    • Parameters

      • message: string

        Warning message to be handled

      Returns void

Remarks

Warning scenarios include:

  • Configuration issues that fall back to defaults
  • Performance degradation
  • Deprecated API usage
  • Resource limit approaches

Default

Logs to console.warn

Example

warn: (message) => {
  logger.warn('[OTel Warning]', message);
  metrics.increment('otel.warnings');
}

Settings

Member Visibility

On This Page

Properties