---
title: 非同期保存処理におけるエラー可視化とコンテキストの導入
status: Accepted
date: 2026-02-20
context: Improving Observability of Background Tasks
---

# 非同期保存処理におけるエラー可視化とコンテキストの導入

## Context and Problem Statement / コンテキスト

beautyspot では、関数の実行結果をキャッシュに保存する際、`wait=False` を指定することでバックグラウンドスレッドでの非同期保存を行うことができます。しかし、バックグラウンドでの保存処理中にエラーが発生した場合、これまではログが出力されるのみ（サイレントフェイル）でした。

メインスレッドをクラッシュさせないという点では安全ですが、ユーザーからすると「なぜかキャッシュが効かない」という原因究明が困難な状態に陥るリスクがありました。また、監視ツールへのエラー通知や、カスタムのリカバリ処理を行うためのフックが存在しませんでした。

## Decision Drivers / 要求

* **Observability**: バックグラウンドでの保存失敗を、ユーザーが確実に検知し、適切に（監視システムへの通知など）対処できること。
* **Developer Experience (DX)**: エラー情報の取得において、型補完が効く安全なインターフェースを提供すること。
* **Safety**: エラーハンドリング自体がメインロジックの安定性やパフォーマンスを損なわないこと。

## Considered Options / 検討

* **Option 1**: 現状維持（ログ出力のみ）。可観測性が低い。
* **Option 2**: メインスレッドへ例外を伝播させる。アプリケーションの安定性を損なうため不採用。
* **Option 3**: コールバック関数 (`on_background_error`) の導入。エラー発生時に任意の処理を実行可能にする。

## Decision Outcome / 決定

Chosen option: **Option 3**.

以下の設計方針で実装します。

1. **`on_background_error` 引数の追加:** `Spot.__init__` にコールバックを受け付ける引数を追加します。
2. **型安全なコンテキストオブジェクト (`SaveErrorContext`) の導入:** ハンドラーには、エラー時の詳細情報（対象の関数名、キャッシュキー、戻り値等）を含む専用のデータクラスを渡します。
3. **`result` (評価済みオブジェクト) の包含:** デバッグを容易にするため、キャッシュしようとした実際のオブジェクトを含めます。ただしメモリリークのリスクがあるため、Docstring にて警告を記載します。
4. **コールバック内の例外保護:** コールバック関数自体が失敗した場合でも、バックグラウンドスレッドをクラッシュさせないよう `try-except` で保護します。

## Consequences / 決定

* **Positive**:
    * ユーザーはバックグラウンド保存の失敗を確実に検知し、監視システムへの通知等が可能になる。
    * 型付きコンテキストにより、安全かつ直感的にエラー詳細へアクセスできる。
    * メインロジックのパフォーマンスや安定性を維持したまま、高い可観測性を実現できる。
* **Negative**:
    * `SaveErrorContext` で巨大なオブジェクトの参照を保持し続けた場合、メモリを圧迫する可能性がある。
