effect-time-tracing-logging

majiayu000's avatarfrom majiayu000

Time with Clock/Duration, tracing spans, and structured logging. Use for time-based logic, deadlines, and observability.

⭐0stars🔀0forks📁View on GitHub🕐Updated Jan 5, 2026
[Agent Observability]

When & Why to Use This Skill

This Claude skill provides a comprehensive suite for managing time-based logic and system observability within the Effect ecosystem. It enables developers to implement precise timeouts, deadlines, and delays using standardized Duration helpers, while offering structured logging and span-based tracing to monitor application health, analyze latency, and simplify debugging.

Use Cases

  • Implementing robust timeouts and deadlines for external API calls to prevent hanging operations and improve system resilience.
  • Wrapping critical business logic in tracing spans to perform detailed latency analysis and identify performance bottlenecks.
  • Replacing ad-hoc console prints with structured, multi-level logging (Info, Debug, Error) for better log management and production monitoring.
  • Managing complex asynchronous workflows that require precise time control, such as implementing 'sleep' intervals or coordinated time-based operations.
  • Standardizing log levels across different environments (CLI vs. Production) using Layer-based configuration for consistent observability.
nameeffect-time-tracing-logging
descriptionTime with Clock/Duration, tracing spans, and structured logging. Use for time-based logic, deadlines, and observability.
allowed-toolsRead, Grep, Glob, Edit, Write

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