Time, Tracing & Logging

When to use

• You need timeouts, deadlines, or sleeps

• You want spans for latency analysis or logs for debugging

Time

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

Timeout

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

Tracing (span wrapper pattern)

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

Logging

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

Real-world snippet: set minimum log level via 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 )

Guidance

• Prefer Duration helpers for clarity of units

• Wrap critical sections with spans; attach attributes for context

• Use structured logs and avoid ad-hoc console prints

Pitfalls

• Mixing ms numbers → use Duration consistently

• No timeouts on external calls → risk of hanging operations

Cross-links

• Errors & Retries for timeouts+races

• Concurrency for coordinated time-based operations

Local Source Reference

CRITICAL: Search local Effect source before implementing

The full Effect source code is available at docs/effect-source/ . Always search the actual implementation before writing Effect code.

Key Source Files

• 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

Example Searches

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

Workflow

• Identify the time/logging API you need (e.g., Clock, Duration, withSpan)

• Search docs/effect-source/effect/src/ for the implementation

• Study the types and time-based patterns

• Look at test files for usage examples

• Write your code based on real implementations

Real source code > documentation > assumptions

References

• Agent Skills overview: https://www.anthropic.com/news/skills

• Skills guide: https://docs.claude.com/en/docs/claude-code/skills