Time, Tracing & Logging

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

1. Identify the time/​logging API you need (e.g., Clock, Duration, withSpan)
2. Search docs/​effect-source/​effect/​src/ for the implementation
3. Study the types and time-based patterns
4. Look at test files for usage examples
5. 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