effect-time-tracing-logging

時間、トレーシング、ロギング

使用する場面

• タイムアウト、期限、またはスリープが必要な場合
• レイテンシ分析用のスパンや、デバッグ用のログが必要な場合

時間

import { Clock, Duration } from "effect"
const now = yield* Clock.currentTimeMillis
yield* Effect.sleep(Duration.seconds(1))

タイムアウト

const guarded = yield* Effect.timeout(task, Duration.seconds(2))

トレーシング（スパンラッパーパターン）

const op = Effect.withSpan("operation")(Effect.succeed(1))

ロギング

yield* Effect.logInfo("message")
yield* Effect.logDebug("debug")
yield* Effect.logError("error")

実例：Layer を使って最小ログレベルを設定する

import { Effect, Option, Logger, LogLevel, Layer } from "effect"

export const setMinimumLogLevel = (cliLevel: Option.Option<LogLevel.LogLevel>) =>
  APP_CONFIG["LOG_LEVEL"].pipe(
    Effect.map((envLevel) => Option.zipLeft(cliLevel, envLevel)),
    Effect.map(Option.getOrElse(() => LogLevel.Info)),
    Effect.map((level) => Logger.minimumLogLevel(level)),
    Layer.unwrapEffect
  )

ガイダンス

• 単位を明確にするため、Duration ヘルパーを優先してください
• 重要なセクションをスパンでラップし、コンテキスト用の属性を付与してください
• 構造化ログを使用し、その場しのぎのコンソール出力は避けてください

注意点

• ミリ秒の数値を混在させること → Duration を一貫して使用してください
• 外部呼び出しにタイムアウトがないこと → 処理がハングするリスクがあります

関連リンク

• タイムアウトと競合状態については「エラーとリトライ」を参照してください
• 時間ベースの処理を協調させる方法については「並行処理」を参照してください

ローカルソースの参照

重要：実装前にローカルの Effect ソースを検索してください

Effect のソースコード全体は docs/effect-source/ にあります。Effect のコードを書く前に、必ず実際の実装を検索してください。

主なソースファイル

• Clock：docs/effect-source/effect/src/Clock.ts
• Duration：docs/effect-source/effect/src/Duration.ts
• Effect（withSpan、log）：docs/effect-source/effect/src/Effect.ts
• Logger：docs/effect-source/effect/src/Logger.ts
• LogLevel：docs/effect-source/effect/src/LogLevel.ts

検索例

# Find Clock operations
grep -F "currentTimeMillis" docs/effect-source/effect/src/Clock.ts
grep -F "sleep" docs/effect-source/effect/src/Clock.ts

# Study Duration helpers
grep -F "seconds" docs/effect-source/effect/src/Duration.ts
grep -F "millis" docs/effect-source/effect/src/Duration.ts
grep -F "minutes" docs/effect-source/effect/src/Duration.ts

# Find span and logging patterns
grep -F "withSpan" docs/effect-source/effect/src/Effect.ts
grep -F "logInfo" docs/effect-source/effect/src/Effect.ts
grep -F "logError" docs/effect-source/effect/src/Effect.ts

# Look at Logger implementation
grep -F "minimumLogLevel" docs/effect-source/effect/src/Logger.ts

ワークフロー

1. 必要な時間／ロギング API（例：Clock、Duration、withSpan）を特定します
2. docs/effect-source/effect/src/ で実装を検索します
3. 型と時間ベースのパターンを確認します
4. 使用例についてテストファイルを確認します
5. 実際の実装に基づいてコードを書きます

実際のソースコード ＞ ドキュメント ＞ 推測

参考資料

• Agent Skills の概要：https://www.anthropic.com/news/skills
• Skills ガイド：https://docs.claude.com/en/docs/claude-code/skills