runtime

func HandlePanicValue ¶

func HandlePanicValue(ctx context.Context, logger Logger, panicValue any, component, name string)

HandlePanicValue processes a panic value that was already recovered by an external mechanism (e.g., Fiber's recover middleware). This function logs and records observability data without calling recover() itself.

Use this when integrating with frameworks that provide their own panic recovery but still need our observability pipeline.

Parameters:

• ctx: Context for observability (metrics, tracing, error reporting)
• logger: Logger for structured logging
• panicValue: The panic value recovered by the external mechanism
• component: The service component (e.g., "matcher", "ingestion")
• name: Descriptive name for the handler (e.g., "http_handler")

Example (Fiber middleware):

recover.New(recover.Config{
    StackTraceHandler: func(c *fiber.Ctx, panicValue any) {
        ctx := extractContext(c)
        runtime.HandlePanicValue(ctx, logger, panicValue, "matcher", "http_handler")
    },
})

func InitPanicMetrics ¶

func InitPanicMetrics(factory *metrics.MetricsFactory, logger ...Logger)

InitPanicMetrics initializes panic metrics with the provided MetricsFactory.

Backward compatibility:

• InitPanicMetrics(factory)
• InitPanicMetrics(factory, logger)

The logger is optional and used only for metric recording diagnostics. This should be called once during application startup after telemetry is initialized. It is safe to call multiple times; subsequent calls are no-ops.

Example:

tl, err := opentelemetry.NewTelemetry(cfg)
if err != nil {
    log.Fatalf("failed to init telemetry: %v", err)
}
tl.ApplyGlobals()
runtime.InitPanicMetrics(tl.MetricsFactory)

func IsProductionMode ¶

func IsProductionMode() bool

IsProductionMode returns whether production mode is enabled.

func RecordPanicToSpan ¶

func RecordPanicToSpan(ctx context.Context, panicValue any, stack []byte, goroutineName string)

RecordPanicToSpan records a recovered panic as an error event on the current span. This enriches distributed traces with panic information for debugging.

The function:

• Adds a "panic.recovered" event with panic value, stack trace, and goroutine name
• Records the panic as an error using span.RecordError
• Sets the span status to Error with a descriptive message

Parameters:

• ctx: Context containing the active span
• panicValue: The value passed to panic()
• stack: The stack trace captured via debug.Stack()
• goroutineName: The name of the goroutine where the panic occurred

If there is no active span in the context, this function is a no-op.

func RecordPanicToSpanWithComponent ¶

func RecordPanicToSpanWithComponent(
	ctx context.Context,
	panicValue any,
	stack []byte,
	component, goroutineName string,
)

RecordPanicToSpanWithComponent is like RecordPanicToSpan but also includes the component name. This is useful for HTTP/gRPC handlers where both component and handler name are relevant.

Parameters:

• ctx: Context containing the active span
• panicValue: The value passed to panic()
• stack: The stack trace captured via debug.Stack()
• component: The service component (e.g., "transaction", "onboarding")
• goroutineName: The name of the handler or goroutine

func RecoverAndCrash ¶

func RecoverAndCrash(logger Logger, name string)

RecoverAndCrash recovers from a panic, logs it with the stack trace, and re-panics to crash the process. Use this in defer statements for critical operations where continuing after a panic would be dangerous.

Example:

func criticalOperation() {
    defer runtime.RecoverAndCrash(logger, "critical-op")
    // ...
}

func RecoverAndCrashWithContext ¶

func RecoverAndCrashWithContext(ctx context.Context, logger Logger, component, name string)

RecoverAndCrashWithContext is like RecoverAndCrash but with full observability integration. It records metrics and span events before re-panicking.

Parameters:

• ctx: Context for observability (metrics, tracing, error reporting)
• logger: Logger for structured logging
• component: The service component (e.g., "transaction", "onboarding")
• name: Descriptive name for the goroutine or handler

func RecoverAndLog ¶

func RecoverAndLog(logger Logger, name string)

RecoverAndLog recovers from a panic, logs it with the stack trace, and continues execution. Use this in defer statements for handlers and workers where you want to prevent crashes.

Note: This function does not record metrics or span events because it lacks context. For observability integration, use RecoverAndLogWithContext instead.

Example:

func worker() {
    defer runtime.RecoverAndLog(logger, "worker")
    // ...
}

func RecoverAndLogWithContext ¶

func RecoverAndLogWithContext(ctx context.Context, logger Logger, component, name string)

RecoverAndLogWithContext is like RecoverAndLog but with full observability integration. It records metrics, span events, and reports to error tracking services.

Parameters:

• ctx: Context for observability (metrics, tracing, error reporting)
• logger: Logger for structured logging
• component: The service component (e.g., "transaction", "onboarding")
• name: Descriptive name for the goroutine or handler

Example:

func handler(ctx context.Context) {
    defer runtime.RecoverAndLogWithContext(ctx, logger, "transaction", "create_handler")
    // ...
}

func RecoverWithPolicy ¶

func RecoverWithPolicy(logger Logger, name string, policy PanicPolicy)

RecoverWithPolicy recovers from a panic and handles it according to the specified policy. Use this when the recovery behavior needs to be determined at runtime.

Note: This function does not record metrics or span events because it lacks context. For observability integration, use RecoverWithPolicyAndContext instead.

Example:

func flexibleHandler(policy runtime.PanicPolicy) {
    defer runtime.RecoverWithPolicy(logger, "handler", policy)
    // ...
}

func RecoverWithPolicyAndContext ¶

func RecoverWithPolicyAndContext(
	ctx context.Context,
	logger Logger,
	component, name string,
	policy PanicPolicy,
)

RecoverWithPolicyAndContext is like RecoverWithPolicy but with full observability integration. It records metrics, span events, and reports to error tracking services.

Parameters:

• ctx: Context for observability (metrics, tracing, error reporting)
• logger: Logger for structured logging
• component: The service component (e.g., "transaction", "onboarding")
• name: Descriptive name for the goroutine or handler
• policy: How to handle the panic after logging/recording

Example:

func worker(ctx context.Context, policy runtime.PanicPolicy) {
    defer runtime.RecoverWithPolicyAndContext(ctx, logger, "transaction", "balance_worker", policy)
    // ...
}

func ResetPanicMetrics ¶

func ResetPanicMetrics()

ResetPanicMetrics clears the panic metrics singleton. This is primarily intended for testing to ensure test isolation. In production, this should generally not be called.

func SafeGo ¶

func SafeGo(logger Logger, name string, policy PanicPolicy, fn func())

SafeGo launches a goroutine with panic recovery. If the goroutine panics, the panic is handled according to the specified policy.

Note: This function does not record metrics or span events because it lacks context. For observability integration, use SafeGoWithContext instead.

Parameters:

• logger: Logger for recording panic information
• name: Descriptive name for the goroutine (used in logs)
• policy: How to handle panics (KeepRunning or CrashProcess)
• fn: The function to execute in the goroutine

Example:

runtime.SafeGo(logger, "email-sender", runtime.KeepRunning, func() {
    sendEmail(to, subject, body)
})

func SafeGoWithContext ¶

func SafeGoWithContext(
	ctx context.Context,
	logger Logger,
	name string,
	policy PanicPolicy,
	fn func(context.Context),
)

SafeGoWithContext launches a goroutine with panic recovery and context propagation.

Note: For better observability labeling, prefer SafeGoWithContextAndComponent.

func SafeGoWithContextAndComponent ¶

func SafeGoWithContextAndComponent(
	ctx context.Context,
	logger Logger,
	component, name string,
	policy PanicPolicy,
	fn func(context.Context),
)

SafeGoWithContextAndComponent is like SafeGoWithContext but also records the provided component name in observability signals.

Parameters:

• ctx: Context for cancellation, values, and observability
• logger: Logger for recording panic information
• component: The service component (e.g., "transaction", "onboarding")
• name: Descriptive name for the goroutine (used in logs and metrics)
• policy: How to handle panics (KeepRunning or CrashProcess)
• fn: The function to execute, receiving the context

func SetErrorReporter ¶

func SetErrorReporter(reporter ErrorReporter)

SetErrorReporter configures the global error reporter for panic reporting. Pass nil to disable error reporting.

This should be called once during application startup if an external error tracking service is desired.

Example with structured logging:

type logReporter struct {
    logger *slog.Logger
}

func (r *logReporter) CaptureException(ctx context.Context, err error, tags map[string]string) {
    attrs := make([]any, 0, len(tags)*2)
    for k, v := range tags {
        attrs = append(attrs, k, v)
    }
    r.logger.ErrorContext(ctx, "panic recovered", append(attrs, "error", err)...)
}

runtime.SetErrorReporter(&logReporter{logger: slog.Default()})

func SetProductionMode ¶

func SetProductionMode(enabled bool)

SetProductionMode enables or disables production mode for error reporting. In production mode, stack traces and potentially sensitive panic details are redacted.