Logging

Logging is an important aspect of software development, especially for debugging and monitoring the behavior of your applications. In this section, we’ll explore Effect’s logging utilities and see how they compare to traditional logging methods.

Advantages Over Traditional Logging

Effect’s logging utilities provide several benefits over conventional logging approaches:

Dynamic Log Level Control: With Effect’s logging, you have the ability to change the log level dynamically. This means you can control which log messages get displayed based on their severity. For example, you can configure your application to log only warnings or errors, which can be extremely helpful in production environments to reduce noise.
Custom Logging Output: Effect’s logging utilities allow you to change how logs are handled. You can direct log messages to various destinations, such as a service or a file, using a custom logger. This flexibility ensures that logs are stored and processed in a way that best suits your application’s requirements.
Fine-Grained Logging: Effect enables fine-grained control over logging on a per-part basis of your program. You can set different log levels for different parts of your application, tailoring the level of detail to each specific component. This can be invaluable for debugging and troubleshooting, as you can focus on the information that matters most.
Environment-Based Logging: Effect’s logging utilities can be combined with deployment environments to achieve granular logging strategies. For instance, during development, you might choose to log everything at a trace level and above for detailed debugging. In contrast, your production version could be configured to log only errors or critical issues, minimizing the impact on performance and noise in production logs.
Additional Features: Effect’s logging utilities come with additional features such as the ability to measure time spans, alter log levels on a per-effect basis, and integrate spans for performance monitoring.

log

The Effect.log function allows you to log a message at the default INFO level.

Example (Logging a Simple Message)

1
import { Effect, Logger } from "effect"
2

3
const program = Effect.log("Application started")
4

5
Effect.runFork(program)
6
/*
7
Output:
8
timestamp=... level=INFO fiber=#0 message="Application started"
9
*/
10

11
// Capture the logged message content (ignoring the non-deterministic timestamp)
12
const messages: Array<unknown> = []
13
Effect.runSync(
14
  program.pipe(
15
    Effect.provide(
16
      Logger.layer([Logger.make((options) => messages.push(options.message))]),
17
    ),
18
  ),
19
)
20
messages // => [["Application started"]]

The default logger in Effect adds several useful details to each log entry:

Annotation	Description
`timestamp`	The timestamp when the log message was generated.
`level`	The log level at which the message is logged (e.g., `INFO`, `ERROR`).
`fiber`	The identifier of the fiber executing the program.
`message`	The log message content, which can include multiple strings or values.
`span`	(Optional) The duration of a span in milliseconds, providing insight into the timing of operations.

You can also log multiple messages at once.

Example (Logging Multiple Messages)

1
import { Effect, Logger } from "effect"
2

3
const program = Effect.log("message1", "message2", "message3")
4

5
Effect.runFork(program)
6
/*
7
Output:
8
timestamp=... level=INFO fiber=#0 message=message1 message=message2 message=message3
9
*/
10

11
// Capture the logged message content (ignoring the non-deterministic timestamp)
12
const messages: Array<unknown> = []
13
Effect.runSync(
14
  program.pipe(
15
    Effect.provide(
16
      Logger.layer([Logger.make((options) => messages.push(options.message))]),
17
    ),
18
  ),
19
)
20
messages // => [["message1", "message2", "message3"]]

For added context, you can also include one or more Cause instances in your logs, which provide detailed error information under an additional cause annotation:

Example (Logging with Causes)

1
import { Effect, Cause, Logger } from "effect"
2

3
const program = Effect.log(
4
  "message1",
5
  "message2",
6
  Cause.die("Oh no!"),
7
  Cause.die("Oh uh!"),
8
)
9

10
Effect.runFork(program)
11
/*
12
Output:
13
timestamp=... level=INFO fiber=#0 message=message1 message=message2 cause="Error: Oh no!
14
Error: Oh uh!"
15
*/
16

17
// Capture the logged message content and cause (ignoring the non-deterministic timestamp)
18
const messages: Array<unknown> = []
19
const causes: Array<Cause.Cause<unknown>> = []
20
Effect.runSync(
21
  program.pipe(
22
    Effect.provide(
23
      Logger.layer([
24
        Logger.make((options) => {
25
          messages.push(options.message)
26
          causes.push(options.cause)
27
        }),
28
      ]),
29
    ),
30
  ),
31
)
32
messages // => [["message1", "message2"]]
33
Cause.hasDies(causes[0]) // => true

Log Levels

logDebug

By default, DEBUG messages are not displayed. To enable them for an effect, provide the References.MinimumLogLevel context reference with the value "Debug".

Example (Enabling Debug Logs)

1
import { Effect, References, Logger } from "effect"
2

3
const task1 = Effect.gen(function* () {
4
  yield* Effect.sleep("2 seconds")
5
  yield* Effect.logDebug("task1 done") // Log a debug message
6
}).pipe(Effect.provideService(References.MinimumLogLevel, "Debug")) // Enable DEBUG level
7

8
const task2 = Effect.gen(function* () {
9
  yield* Effect.sleep("1 second")
10
  yield* Effect.logDebug("task2 done") // This message won't be logged
11
})
12

13
const program = Effect.gen(function* () {
14
  yield* Effect.log("start")
15
  yield* task1
16
  yield* task2
17
  yield* Effect.log("done")
18
})
19

20
Effect.runFork(program)
21
/*
22
Output:
23
timestamp=... level=INFO message=start
24
timestamp=... level=DEBUG message="task1 done" <-- 2 seconds later
25
timestamp=... level=INFO message=done <-- 1 second later
26
*/
27

28
// Capture the logged messages (ignoring the non-deterministic timestamps)
29
const messages: Array<unknown> = []
30
await Effect.runPromise(
31
  program.pipe(
32
    Effect.provide(
33
      Logger.layer([Logger.make((options) => messages.push(options.message))]),
34
    ),
35
  ),
36
)
37
// task2's debug message is filtered out, since it never enables the Debug level
38
messages // => [["start"], ["task1 done"], ["done"]]

logInfo

The INFO log level is displayed by default. This level is typically used for general application events or progress updates.

Example (Logging at the Info Level)

1
import { Effect, Logger } from "effect"
2

3
const program = Effect.gen(function* () {
4
  yield* Effect.logInfo("start")
5
  yield* Effect.sleep("2 seconds")
6
  yield* Effect.sleep("1 second")
7
  yield* Effect.logInfo("done")
8
})
9

10
Effect.runFork(program)
11
/*
12
Output:
13
timestamp=... level=INFO message=start
14
timestamp=... level=INFO message=done <-- 3 seconds later
15
*/
16

17
// Capture the logged messages (ignoring the non-deterministic timestamps)
18
const messages: Array<unknown> = []
19
await Effect.runPromise(
20
  program.pipe(
21
    Effect.provide(
22
      Logger.layer([Logger.make((options) => messages.push(options.message))]),
23
    ),
24
  ),
25
)
26
messages // => [["start"], ["done"]]

logWarning

The WARN log level is displayed by default. This level is intended for potential issues or warnings that do not immediately disrupt the flow of the program but should be monitored.

Example (Logging at the Warning Level)

1
import { Effect, Result, Logger } from "effect"
2

3
const task = Effect.fail("Oh uh!").pipe(Effect.as(2))
4

5
const program = Effect.gen(function* () {
6
  const failureOrSuccess = yield* Effect.result(task)
7
  if (Result.isFailure(failureOrSuccess)) {
8
    yield* Effect.logWarning(failureOrSuccess.failure)
9
    return 0
10
  } else {
11
    return failureOrSuccess.success
12
  }
13
})
14

15
Effect.runFork(program)
16
/*
17
Output:
18
timestamp=... level=WARN fiber=#0 message="Oh uh!"
19
*/
20

21
// Capture the logged message content (ignoring the non-deterministic timestamp)
22
const messages: Array<unknown> = []
23
const result = await Effect.runPromise(
24
  program.pipe(
25
    Effect.provide(
26
      Logger.layer([Logger.make((options) => messages.push(options.message))]),
27
    ),
28
  ),
29
)
30
result // => 0
31
messages // => [["Oh uh!"]]

logError

The ERROR log level is displayed by default. These messages represent issues that need to be addressed.

Example (Logging at the Error Level)

1
import { Effect, Result, Logger } from "effect"
2

3
const task = Effect.fail("Oh uh!").pipe(Effect.as(2))
4

5
const program = Effect.gen(function* () {
6
  const failureOrSuccess = yield* Effect.result(task)
7
  if (Result.isFailure(failureOrSuccess)) {
8
    yield* Effect.logError(failureOrSuccess.failure)
9
    return 0
10
  } else {
11
    return failureOrSuccess.success
12
  }
13
})
14

15
Effect.runFork(program)
16
/*
17
Output:
18
timestamp=... level=ERROR fiber=#0 message="Oh uh!"
19
*/
20

21
// Capture the logged message content (ignoring the non-deterministic timestamp)
22
const messages: Array<unknown> = []
23
const result = await Effect.runPromise(
24
  program.pipe(
25
    Effect.provide(
26
      Logger.layer([Logger.make((options) => messages.push(options.message))]),
27
    ),
28
  ),
29
)
30
result // => 0
31
messages // => [["Oh uh!"]]

logFatal

The FATAL log level is displayed by default. This log level is typically reserved for unrecoverable errors.

Example (Logging at the Fatal Level)

1
import { Effect, Result, Logger } from "effect"
2

3
const task = Effect.fail("Oh uh!").pipe(Effect.as(2))
4

5
const program = Effect.gen(function* () {
6
  const failureOrSuccess = yield* Effect.result(task)
7
  if (Result.isFailure(failureOrSuccess)) {
8
    yield* Effect.logFatal(failureOrSuccess.failure)
9
    return 0
10
  } else {
11
    return failureOrSuccess.success
12
  }
13
})
14

15
Effect.runFork(program)
16
/*
17
Output:
18
timestamp=... level=FATAL fiber=#0 message="Oh uh!"
19
*/
20

21
// Capture the logged message content (ignoring the non-deterministic timestamp)
22
const messages: Array<unknown> = []
23
const result = await Effect.runPromise(
24
  program.pipe(
25
    Effect.provide(
26
      Logger.layer([Logger.make((options) => messages.push(options.message))]),
27
    ),
28
  ),
29
)
30
result // => 0
31
messages // => [["Oh uh!"]]

Custom Annotations

You can enhance your log outputs by adding custom annotations using the Effect.annotateLogs function. This allows you to attach extra metadata to each log entry, improving traceability and providing additional context.

Adding a Single Annotation

You can apply a single annotation as a key/value pair to all log entries within an effect.

Example (Single Key/Value Annotation)

1
import { Effect, Logger, References } from "effect"
2

3
const program = Effect.gen(function* () {
4
  yield* Effect.log("message1")
5
  yield* Effect.log("message2")
6
}).pipe(
7
  // Annotation as key/value pair
8
  Effect.annotateLogs("key", "value"),
9
)
10

11
Effect.runFork(program)
12
/*
13
Output:
14
timestamp=... level=INFO fiber=#0 message=message1 key=value
15
timestamp=... level=INFO fiber=#0 message=message2 key=value
16
*/
17

18
// Capture the annotations attached to each logged message
19
const annotations: Array<unknown> = []
20
Effect.runSync(
21
  program.pipe(
22
    Effect.provide(
23
      Logger.layer([
24
        Logger.make((options) =>
25
          annotations.push(
26
            options.fiber.getRef(References.CurrentLogAnnotations),
27
          ),
28
        ),
29
      ]),
30
    ),
31
  ),
32
)
33
annotations // => [{ key: "value" }, { key: "value" }]

In this example, all logs generated within the program will include the annotation key=value.

Annotations with Nested Effects

Annotations propagate to all logs generated within nested or downstream effects. This ensures that logs from any child effects inherit the parent effect’s annotations.

Example (Propagating Annotations to Nested Effects)

In this example, the annotation key=value is included in all logs, even those from the nested anotherProgram effect.

1
import { Effect, Logger } from "effect"
2

3
// Define a child program that logs an error
4
const anotherProgram = Effect.gen(function* () {
5
  yield* Effect.logError("error1")
6
})
7

8
// Define the main program
9
const program = Effect.gen(function* () {
10
  yield* Effect.log("message1")
11
  yield* Effect.log("message2")
12
  yield* anotherProgram // Call the nested program
13
}).pipe(
14
  // Attach an annotation to all logs in the scope
15
  Effect.annotateLogs("key", "value"),
16
)
17

18
Effect.runFork(program)
19
/*
20
Output:
21
timestamp=... level=INFO fiber=#0 message=message1 key=value
22
timestamp=... level=INFO fiber=#0 message=message2 key=value
23
timestamp=... level=ERROR fiber=#0 message=error1 key=value
24
*/
25

26
// Capture the logged messages, confirming the annotation reaches the nested effect too
27
const messages: Array<unknown> = []
28
Effect.runSync(
29
  program.pipe(
30
    Effect.provide(
31
      Logger.layer([Logger.make((options) => messages.push(options.message))]),
32
    ),
33
  ),
34
)
35
messages // => [["message1"], ["message2"], ["error1"]]

Adding Multiple Annotations

You can also apply multiple annotations at once by passing an object with key/value pairs. Each key/value pair will be added to every log entry within the effect.

Example (Multiple Annotations)

1
import { Effect, Logger, References } from "effect"
2

3
const program = Effect.gen(function* () {
4
  yield* Effect.log("message1")
5
  yield* Effect.log("message2")
6
}).pipe(
7
  // Add multiple annotations
8
  Effect.annotateLogs({ key1: "value1", key2: "value2" }),
9
)
10

11
Effect.runFork(program)
12
/*
13
Output:
14
timestamp=... level=INFO fiber=#0 message=message1 key2=value2 key1=value1
15
timestamp=... level=INFO fiber=#0 message=message2 key2=value2 key1=value1
16
*/
17

18
// Capture the annotations attached to each logged message
19
const annotations: Array<unknown> = []
20
Effect.runSync(
21
  program.pipe(
22
    Effect.provide(
23
      Logger.layer([
24
        Logger.make((options) =>
25
          annotations.push(
26
            options.fiber.getRef(References.CurrentLogAnnotations),
27
          ),
28
        ),
29
      ]),
30
    ),
31
  ),
32
)
33
annotations // => [{ key1: "value1", key2: "value2" }, { key1: "value1", key2: "value2" }]

In this case, each log will contain both key1=value1 and key2=value2.

Scoped Annotations

If you want to limit the scope of your annotations so that they only apply to certain log entries, you can use Effect.annotateLogsScoped. This function confines the annotations to logs produced within a specific scope.

Example (Scoped Annotations)

1
import { Effect, Logger, References } from "effect"
2

3
const program = Effect.gen(function* () {
4
  yield* Effect.log("no annotations") // No annotations
5
  yield* Effect.annotateLogsScoped({ key: "value" }) // Scoped annotation
6
  yield* Effect.log("message1") // Annotation applied
7
  yield* Effect.log("message2") // Annotation applied
8
}).pipe(
9
  Effect.scoped,
10
  // Outside scope, no annotations
11
  Effect.andThen(Effect.log("no annotations again")),
12
)
13

14
Effect.runFork(program)
15
/*
16
Output:
17
timestamp=... level=INFO fiber=#0 message="no annotations"
18
timestamp=... level=INFO fiber=#0 message=message1 key=value
19
timestamp=... level=INFO fiber=#0 message=message2 key=value
20
timestamp=... level=INFO fiber=#0 message="no annotations again"
21
*/
22

23
// Capture each logged message together with the annotations active at that point
24
const records: Array<unknown> = []
25
Effect.runSync(
26
  program.pipe(
27
    Effect.provide(
28
      Logger.layer([
29
        Logger.make((options) => {
30
          records.push({
31
            message: options.message,
32
            annotations: options.fiber.getRef(References.CurrentLogAnnotations),
33
          })
34
        }),
35
      ]),
36
    ),
37
  ),
38
)
39
records // => [{ message: ["no annotations"], annotations: {} }, { message: ["message1"], annotations: { key: "value" } }, { message: ["message2"], annotations: { key: "value" } }, { message: ["no annotations again"], annotations: {} }]

Log Spans

Effect provides built-in support for log spans, which allow you to measure and log the duration of specific tasks or sections of your code. This feature is helpful for tracking how long certain operations take, giving you better insights into the performance of your application.

Example (Measuring Task Duration with a Log Span)

1
import { Effect, Logger, References } from "effect"
2

3
const program = Effect.gen(function* () {
4
  // Simulate a delay to represent a task taking time
5
  yield* Effect.sleep("1 second")
6
  // Log a message indicating the job is done
7
  yield* Effect.log("The job is finished!")
8
}).pipe(
9
  // Apply a log span labeled "myspan" to measure
10
  // the duration of this operation
11
  Effect.withLogSpan("myspan"),
12
)
13

14
Effect.runFork(program)
15
/*
16
Output:
17
timestamp=... level=INFO fiber=#0 message="The job is finished!" myspan=1011ms
18
*/
19

20
// Capture the logged message and the active span label (the duration itself is non-deterministic)
21
const records: Array<unknown> = []
22
await Effect.runPromise(
23
  program.pipe(
24
    Effect.provide(
25
      Logger.layer([
26
        Logger.make((options) => {
27
          records.push({
28
            message: options.message,
29
            spans: options.fiber
30
              .getRef(References.CurrentLogSpans)
31
              .map(([label]) => label),
32
          })
33
        }),
34
      ]),
35
    ),
36
  ),
37
)
38
records // => [{ message: ["The job is finished!"], spans: ["myspan"] }]

Disabling Default Logging

Sometimes, perhaps during test execution, you might want to disable default logging in your application. Effect provides several ways to turn off logging when needed. In this section, we’ll look at different methods to disable logging in the Effect framework.

Example (Providing a Minimum Log Level)

One convenient way to disable logging is to provide References.MinimumLogLevel with the value "None".

1
import { Effect, Logger, References } from "effect"
2

3
const program = Effect.gen(function* () {
4
  yield* Effect.log("Executing task...")
5
  yield* Effect.sleep("100 millis")
6
  console.log("task done")
7
})
8

9
// Default behavior: logging enabled
10
Effect.runFork(program)
11
/*
12
Output:
13
timestamp=... level=INFO fiber=#0 message="Executing task..."
14
task done
15
*/
16

17
// Disable logging by setting minimum log level to 'None'
18
Effect.runFork(
19
  program.pipe(Effect.provideService(References.MinimumLogLevel, "None")),
20
)
21
/*
22
Output:
23
task done
24
*/
25

26
// Confirm that the minimum log level actually suppresses the log message
27
const enabledMessages: Array<unknown> = []
28
await Effect.runPromise(
29
  program.pipe(
30
    Effect.provide(
31
      Logger.layer([
32
        Logger.make((options) => enabledMessages.push(options.message)),
33
      ]),
34
    ),
35
  ),
36
)
37
enabledMessages.length // => 1
38

39
const disabledMessages: Array<unknown> = []
40
await Effect.runPromise(
41
  program.pipe(
42
    Effect.provideService(References.MinimumLogLevel, "None"),
43
    Effect.provide(
44
      Logger.layer([
45
        Logger.make((options) => disabledMessages.push(options.message)),
46
      ]),
47
    ),
48
  ),
49
)
50
disabledMessages.length // => 0

Example (Using a Layer)

Another approach to disable logging is by creating a layer that sets the minimum log level to "None", effectively turning off all log output.

1
import { Effect, Layer, Logger, References } from "effect"
2

3
const program = Effect.gen(function* () {
4
  yield* Effect.log("Executing task...")
5
  yield* Effect.sleep("100 millis")
6
  console.log("task done")
7
})
8

9
// Create a layer that disables logging
10
const layer = Layer.succeed(References.MinimumLogLevel, "None")
11

12
// Apply the layer to disable logging
13
Effect.runFork(program.pipe(Effect.provide(layer)))
14
/*
15
Output:
16
task done
17
*/
18

19
// Confirm that no log message was emitted
20
const messages: Array<unknown> = []
21
await Effect.runPromise(
22
  program.pipe(
23
    Effect.provide(layer),
24
    Effect.provide(
25
      Logger.layer([Logger.make((options) => messages.push(options.message))]),
26
    ),
27
  ),
28
)
29
messages.length // => 0

Example (Using a Custom Runtime)

You can also disable logging by creating a custom runtime that includes the configuration to turn off logging:

1
import { Effect, Layer, Logger, ManagedRuntime, References } from "effect"
2

3
const program = Effect.gen(function* () {
4
  yield* Effect.log("Executing task...")
5
  yield* Effect.sleep("100 millis")
6
  console.log("task done")
7
})
8

9
// Create a custom runtime that disables logging
10
const customRuntime = ManagedRuntime.make(
11
  Layer.succeed(References.MinimumLogLevel, "None"),
12
)
13

14
// Run the program using the custom runtime
15
customRuntime.runFork(program)
16
/*
17
Output:
18
task done
19
*/
20

21
// Confirm that no log message was emitted through a runtime with logging disabled
22
const messages: Array<unknown> = []
23
const capturingRuntime = ManagedRuntime.make(
24
  Layer.merge(
25
    Layer.succeed(References.MinimumLogLevel, "None"),
26
    Logger.layer([Logger.make((options) => messages.push(options.message))]),
27
  ),
28
)
29
await capturingRuntime.runPromise(program)
30
messages.length // => 0

Loading the Log Level from Configuration

To load the log level from a configuration and apply it to your program, map the configured value to a layer for References.MinimumLogLevel.

Example (Loading Log Level from Configuration)

1
import {
2
  Effect,
3
  Config,
4
  Layer,
5
  ConfigProvider,
6
  References,
7
  Logger,
8
} from "effect"
9

10
// Simulate a program with logs
11
const program = Effect.gen(function* () {
12
  yield* Effect.logError("ERROR!")
13
  yield* Effect.logWarning("WARNING!")
14
  yield* Effect.logInfo("INFO!")
15
  yield* Effect.logDebug("DEBUG!")
16
})
17

18
// Load the log level from the configuration and apply it as a layer
19
const LogLevelLive = Config.logLevel("LOG_LEVEL").pipe(
20
  Effect.map((level) =>
21
    // Set the minimum log level
22
    Layer.succeed(References.MinimumLogLevel, level),
23
  ),
24
  Layer.unwrap, // Convert the effect into a layer
25
)
26

27
// Provide the loaded log level to the program
28
const configured = Effect.provide(program, LogLevelLive)
29

30
// Test the program using a mock configuration provider
31
const test = Effect.provide(
32
  configured,
33
  ConfigProvider.layer(ConfigProvider.fromUnknown({ LOG_LEVEL: "Warn" })),
34
)
35

36
Effect.runFork(test)
37
/*
38
Output:
39
... level=ERROR fiber=#0 message=ERROR!
40
... level=WARN fiber=#0 message=WARNING!
41
*/
42

43
// Capture which messages actually pass the configured "Warn" minimum level
44
const messages: Array<unknown> = []
45
await Effect.runPromise(
46
  test.pipe(
47
    Effect.provide(
48
      Logger.layer([Logger.make((options) => messages.push(options.message))]),
49
    ),
50
  ),
51
)
52
messages // => [["ERROR!"], ["WARNING!"]]

Custom loggers

In this section, you’ll learn how to define a custom logger and set it as the default logger in your application. Custom loggers give you control over how log messages are handled, such as routing them to external services, writing to files, or formatting logs in a specific way.

Defining a Custom Logger

You can define your own logger using the Logger.make function. This function allows you to specify how log messages should be processed.

Example (Defining a Simple Custom Logger)

1
import { Logger } from "effect"
2

3
// Custom logger that outputs log messages to the console
4
const logger = Logger.make(({ logLevel, message }) => {
5
  globalThis.console.log(`[${logLevel.toUpperCase()}] ${message}`)
6
})
7

8
Logger.isLogger(logger) // => true

In this example, the custom logger logs messages to the console with the log level and message formatted as [LogLevel] Message.

Using a Custom Logger in a Program

Let’s assume you have the following tasks and a program where you log some messages:

1
import { Effect, Logger } from "effect"
2

4 collapsed lines
3
// Custom logger that outputs log messages to the console
4
const logger = Logger.make(({ logLevel, message }) => {
5
  globalThis.console.log(`[${logLevel.toUpperCase()}] ${message}`)
6
})
7

8
const task1 = Effect.gen(function* () {
9
  yield* Effect.sleep("2 seconds")
10
  yield* Effect.logDebug("task1 done")
11
})
12

13
const task2 = Effect.gen(function* () {
14
  yield* Effect.sleep("1 second")
15
  yield* Effect.logDebug("task2 done")
16
})
17

18
const program = Effect.gen(function* () {
19
  yield* Effect.log("start")
20
  yield* task1
21
  yield* task2
22
  yield* Effect.log("done")
23
})
24

25
Effect.isEffect(program) // => true

Create a Logger.layer containing the loggers that should receive messages, then provide it to the program with Effect.provide.

Example (Replacing the Default Logger with a Custom Logger)

1
import { Effect, Logger, References } from "effect"
2

21 collapsed lines
3
// Custom logger that outputs log messages to the console
4
const logger = Logger.make(({ logLevel, message }) => {
5
  globalThis.console.log(`[${logLevel.toUpperCase()}] ${message}`)
6
})
7

8
const task1 = Effect.gen(function* () {
9
  yield* Effect.sleep("2 seconds")
10
  yield* Effect.logDebug("task1 done")
11
})
12

13
const task2 = Effect.gen(function* () {
14
  yield* Effect.sleep("1 second")
15
  yield* Effect.logDebug("task2 done")
16
})
17

18
const program = Effect.gen(function* () {
19
  yield* Effect.log("start")
20
  yield* task1
21
  yield* task2
22
  yield* Effect.log("done")
23
})
24

25
// Replace the default logger with the custom logger
26
const layer = Logger.layer([logger, Logger.tracerLogger])
27

28
Effect.runFork(
29
  program.pipe(
30
    Effect.provideService(References.MinimumLogLevel, "Debug"),
31
    Effect.provide(layer),
32
  ),
33
)
34

35
// Capture the level+message pairs delivered to the custom logger
36
const entries: Array<string> = []
37
await Effect.runPromise(
38
  program.pipe(
39
    Effect.provideService(References.MinimumLogLevel, "Debug"),
40
    Effect.provide(
41
      Logger.layer([
42
        Logger.make(({ logLevel, message }) => {
43
          entries.push(`[${logLevel.toUpperCase()}] ${message}`)
44
        }),
45
      ]),
46
    ),
47
  ),
48
)
49
entries // => ["[INFO] start", "[DEBUG] task1 done", "[DEBUG] task2 done", "[INFO] done"]

When you run the above program, the following log messages are printed to the console:

[INFO] start
[DEBUG] task1 done
[DEBUG] task2 done
[INFO] done

Built-in Loggers

Effect provides several built-in loggers that you can use depending on your logging needs. These loggers offer different formats, each suited for different environments or purposes, such as development, production, or integration with external logging services.

Each logger is available in two forms: the logger itself, and a layer that uses the logger and sends its output to the Console default service. For example, the structuredLogger logger generates logs in a detailed object-based format, while the structured layer uses the same logger and writes the output to the Console service.

stringLogger (default)

The stringLogger logger produces logs in a human-readable key-value style. This format is commonly used in development and production because it is simple and easy to read in the console.

This logger does not have a corresponding layer because it is the default logger.

1
import { Effect, Logger } from "effect"
2

3
const program = Effect.log("msg1", "msg2", ["msg3", "msg4"]).pipe(
4
  Effect.delay("100 millis"),
5
  Effect.annotateLogs({ key1: "value1", key2: "value2" }),
6
  Effect.withLogSpan("myspan"),
7
)
8

9
Effect.runFork(program)
10

11
// Capture the formatted log line (ignoring the non-deterministic timestamp/fiber/span duration)
12
let formatted = ""
13
await Effect.runPromise(
14
  program.pipe(
15
    Effect.provide(
16
      Logger.layer([
17
        Logger.make((options) => {
18
          formatted = Logger.formatSimple.log(options)
19
        }),
20
      ]),
21
    ),
22
  ),
23
)
24
formatted.includes("message=msg1 message=msg2") // => true
25
formatted.endsWith("key1=value1 key2=value2") // => true

Output:

timestamp=2024-12-28T10:44:31.281Z level=INFO fiber=#0 message=msg1 message=msg2 message="[
  \"msg3\",
  \"msg4\"
]" myspan=102ms key2=value2 key1=value1

logfmtLogger

The logfmtLogger logger produces logs in a human-readable key-value format, similar to the stringLogger logger. The main difference is that logfmtLogger removes extra spaces to make logs more compact.

1
import { Effect, Logger } from "effect"
2

3
const program = Effect.log("msg1", "msg2", ["msg3", "msg4"]).pipe(
4
  Effect.delay("100 millis"),
5
  Effect.annotateLogs({ key1: "value1", key2: "value2" }),
6
  Effect.withLogSpan("myspan"),
7
)
8

9
Effect.runFork(
10
  program.pipe(
11
    Effect.provide(Logger.layer([Logger.consoleLogFmt, Logger.tracerLogger])),
12
  ),
13
)
14

15
// Capture the formatted log line (ignoring the non-deterministic timestamp/fiber/span duration)
16
let formatted = ""
17
await Effect.runPromise(
18
  program.pipe(
19
    Effect.provide(
20
      Logger.layer([
21
        Logger.make((options) => {
22
          formatted = Logger.formatLogFmt.log(options)
23
        }),
24
      ]),
25
    ),
26
  ),
27
)
28
formatted.includes("message=msg1 message=msg2") // => true
29
formatted.endsWith("key1=value1 key2=value2") // => true

Output:

timestamp=2024-12-28T10:44:31.281Z level=INFO fiber=#0 message=msg1 message=msg2 message="[\"msg3\",\"msg4\"]" myspan=102ms key2=value2 key1=value1

prettyLogger

The prettyLogger logger enhances log output by using color and indentation for better readability, making it particularly useful during development when visually scanning logs in the console.

1
import { Effect, Logger } from "effect"
2

3
const program = Effect.log("msg1", "msg2", ["msg3", "msg4"]).pipe(
4
  Effect.delay("100 millis"),
5
  Effect.annotateLogs({ key1: "value1", key2: "value2" }),
6
  Effect.withLogSpan("myspan"),
7
)
8

9
Effect.runFork(
10
  program.pipe(
11
    Effect.provide(Logger.layer([Logger.consolePretty(), Logger.tracerLogger])),
12
  ),
13
)
14

15
// Wait for the fire-and-forget run above to finish logging before capturing below
16
await Effect.runPromise(Effect.sleep("150 millis"))
17

18
// Capture the individual console lines written by the pretty logger
19
// (ignoring the non-deterministic timestamp/fiber/span duration on the first line)
20
const calls: Array<Array<unknown>> = []
21
const originalLog = console.log
22
console.log = (...args: Array<unknown>) => {
23
  calls.push(args)
24
}
25
try {
26
  await Effect.runPromise(
27
    program.pipe(
28
      Effect.provide(
29
        Logger.layer([Logger.consolePretty(), Logger.tracerLogger]),
30
      ),
31
    ),
32
  )
33
} finally {
34
  console.log = originalLog
35
}
36
calls.length // => 5
37
calls.slice(1) // => [["msg2"], [["msg3", "msg4"]], ["key1:", "value1"], ["key2:", "value2"]]

Output:

[11:37:14.265] INFO (#0) myspan=101ms: msg1
  msg2
  [ 'msg3', 'msg4' ]
  key2: value2
  key1: value1

structuredLogger

The structuredLogger logger produces logs in a detailed object-based format. This format is helpful when you need more traceable logs, especially if other systems analyze them or store them for later review.

1
import { Effect, Logger } from "effect"
2

3
const program = Effect.log("msg1", "msg2", ["msg3", "msg4"]).pipe(
4
  Effect.delay("100 millis"),
5
  Effect.annotateLogs({ key1: "value1", key2: "value2" }),
6
  Effect.withLogSpan("myspan"),
7
)
8

9
Effect.runFork(
10
  program.pipe(
11
    Effect.provide(
12
      Logger.layer([Logger.consoleStructured, Logger.tracerLogger]),
13
    ),
14
  ),
15
)
16

17
// Capture the structured record (ignoring the non-deterministic timestamp/fiberId/span duration)
18
let structured: any
19
await Effect.runPromise(
20
  program.pipe(
21
    Effect.provide(
22
      Logger.layer([
23
        Logger.make((options) => {
24
          structured = Logger.formatStructured.log(options)
25
        }),
26
      ]),
27
    ),
28
  ),
29
)
30
structured.message // => ["msg1", "msg2", ["msg3", "msg4"]]
31
structured.level // => "INFO"
32
structured.annotations // => { key1: "value1", key2: "value2" }
33
Object.keys(structured.spans) // => ["myspan"]

Output:

{
  message: [ 'msg1', 'msg2', [ 'msg3', 'msg4' ] ],
  level: 'INFO',
  timestamp: '2024-12-28T10:44:31.281Z',
  cause: undefined,
  annotations: { key2: 'value2', key1: 'value1' },
  spans: { myspan: 102 },
  fiberId: '#0'
}

Field	Description
`message`	Either a single processed value or an array of processed values, depending on how many messages are logged.
`level`	A string that indicates the log level label (for example, “INFO” or “DEBUG”).
`timestamp`	An ISO 8601 timestamp for when the log was generated (for example, “2024-01-01T00:00:00.000Z”).
`cause`	A string that shows detailed error information, or `undefined` if no cause was provided.
`annotations`	An object where each key is an annotation label and the corresponding value is parsed into a structured format (for instance, `{"key": "value"}`).
`spans`	An object mapping each span label to its duration in milliseconds, measured from its start time until the moment the logger was called (for example, `{"myspan": 102}`).
`fiberId`	The identifier of the fiber that generated this log (for example, “#0”).

jsonLogger

The jsonLogger logger produces logs in JSON format. This can be useful for tools or services that parse and store JSON logs. It calls JSON.stringify on the object created by the structuredLogger logger.

1
import { Effect, Logger } from "effect"
2

3
const program = Effect.log("msg1", "msg2", ["msg3", "msg4"]).pipe(
4
  Effect.delay("100 millis"),
5
  Effect.annotateLogs({ key1: "value1", key2: "value2" }),
6
  Effect.withLogSpan("myspan"),
7
)
8

9
Effect.runFork(
10
  program.pipe(
11
    Effect.provide(Logger.layer([Logger.consoleJson, Logger.tracerLogger])),
12
  ),
13
)
14

15
// Capture the JSON record (ignoring the non-deterministic timestamp/fiberId/span duration)
16
let jsonString = ""
17
await Effect.runPromise(
18
  program.pipe(
19
    Effect.provide(
20
      Logger.layer([
21
        Logger.make((options) => {
22
          jsonString = Logger.formatJson.log(options)
23
        }),
24
      ]),
25
    ),
26
  ),
27
)
28
const parsed = JSON.parse(jsonString)
29
parsed.message // => ["msg1", "msg2", ["msg3", "msg4"]]
30
parsed.level // => "INFO"
31
parsed.annotations // => { key1: "value1", key2: "value2" }
32
Object.keys(parsed.spans) // => ["myspan"]

Output:

{"message":["msg1","msg2",["msg3","msg4"]],"level":"INFO","timestamp":"2024-12-28T10:44:31.281Z","annotations":{"key2":"value2","key1":"value1"},"spans":{"myspan":102},"fiberId":"#0"}

Combining Loggers

Forwarding to Multiple Loggers

A custom logger can invoke other loggers to forward each message to all of them.

Example (Combining Two Loggers)

1
import { Effect, Logger } from "effect"
2

3
// Define a custom logger that logs to the console
4
const logger = Logger.make(({ logLevel, message }) => {
5
  globalThis.console.log(`[${logLevel.toUpperCase()}] ${message}`)
6
})
7

8
// Combine the default logger and the custom logger
9
//
10
//      ┌─── Logger<unknown, [void, void]>
11
//      ▼
12
const combined = Logger.make((options) => [
13
  Logger.defaultLogger.log(options),
14
  logger.log(options),
15
])
16

17
const program = Effect.log("something")
18

19
Effect.runFork(
20
  program.pipe(
21
    // Replace the default logger with the combined logger
22
    Effect.provide(Logger.layer([combined, Logger.tracerLogger])),
23
  ),
24
)
25
/*
26
Output:
27
timestamp=2025-01-09T13:50:58.655Z level=INFO fiber=#0 message=something
28
[INFO] something
29
*/
30

31
// Capture the message that reaches the combined logger
32
const messages: Array<unknown> = []
33
Effect.runSync(
34
  program.pipe(
35
    Effect.provide(
36
      Logger.layer([Logger.make((options) => messages.push(options.message))]),
37
    ),
38
  ),
39
)
40
messages // => [["something"]]