日志记录

日志记录是软件开发的重要方面，特别是对于调试和监控应用程序行为。在本节中，我们将探索 Effect 的日志记录工具，并了解它们与传统日志记录方法的比较。

相比传统日志记录的优势

Effect 的日志记录工具相比传统日志记录方法提供了几个优势：

1. 动态日志级别控制：使用 Effect 的日志记录，您可以动态更改日志级别。这意味着您可以根据严重程度控制显示哪些日志消息。例如，您可以配置应用程序仅记录警告或错误，这在生产环境中非常有用，可以减少噪音。

2. 自定义日志输出：Effect 的日志记录工具允许您更改日志的处理方式。您可以使用自定义记录器将日志消息定向到各种目标，如服务或文件。这种灵活性确保日志以最适合您应用程序需求的方式存储和处理。

3. 细粒度日志记录：Effect 支持对程序的每个部分进行细粒度的日志记录控制。您可以为应用程序的不同部分设置不同的日志级别，为每个特定组件定制详细程度。这对于调试和故障排除非常有价值，因为您可以专注于最重要的信息。

4. 基于环境的日志记录：Effect 的日志记录工具可以与部署环境结合使用，实现细粒度的日志记录策略。例如，在开发期间，您可能选择记录跟踪级别及以上的所有内容以进行详细调试。相比之下，您的生产版本可以配置为仅记录错误或关键问题，最大限度地减少对性能的影响和生产日志中的噪音。

5. 附加功能：Effect 的日志记录工具还提供附加功能，如测量时间跨度的能力、基于每个 Effect 更改日志级别，以及集成跨度进行性能监控。

log

Effect.log 函数允许您在默认的 INFO 级别记录消息。

示例（记录简单消息）

import { Effect } from "effect"

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

Effect.runFork(program)
/*
Output:
timestamp=... level=INFO fiber=#0 message="Application started"
*/

Effect 中的默认记录器为每个日志条目添加了几个有用的详细信息：

注解	描述
timestamp	生成日志消息时的时间戳。
level	记录消息的日志级别（例如，INFO、ERROR）。
fiber	执行程序的纤程标识符。
message	日志消息内容，可以包含多个字符串或值。
span	（可选）跨度的持续时间（以毫秒为单位），提供对操作时间的洞察。

自定义记录器

有关如何定制日志记录设置以满足特定需求的信息，例如集成自定义日志记录框架或调整日志格式，请参阅自定义记录器部分。

您也可以一次记录多个消息。

示例（记录多个消息）

import { Effect } from "effect"

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

Effect.runFork(program)
/*
Output:
timestamp=... level=INFO fiber=#0 message=message1 message=message2 message=message3
*/

为了增加上下文，您还可以在日志中包含一个或多个 Cause 实例， 这些实例在附加的 cause 注解下提供详细的错误信息：

示例（使用原因记录日志）

import { Effect, Cause } from "effect"

const program = Effect.log(
  "message1",
  "message2",
  Cause.die("Oh no!"),
  Cause.die("Oh uh!")
)

Effect.runFork(program)
/*
Output:
timestamp=... level=INFO fiber=#0 message=message1 message=message2 cause="Error: Oh no!
Error: Oh uh!"
*/

日志级别

logDebug

默认情况下，DEBUG 消息不会显示。要启用 DEBUG 日志，您可以使用 Logger.withMinimumLogLevel 调整日志记录配置，将最小级别设置为 LogLevel.Debug。

示例（启用调试日志）

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

const task1 = Effect.gen(function* () {
  yield* Effect.sleep("2 seconds")
  yield* Effect.logDebug("task1 done") // 记录调试消息
}).pipe(Logger.withMinimumLogLevel(LogLevel.Debug)) // 启用 DEBUG 级别

const task2 = Effect.gen(function* () {
  yield* Effect.sleep("1 second")
  yield* Effect.logDebug("task2 done") // 此消息不会被记录
})

const program = Effect.gen(function* () {
  yield* Effect.log("start")
  yield* task1
  yield* task2
  yield* Effect.log("done")
})

Effect.runFork(program)
/*
Output:
timestamp=... level=INFO message=start
timestamp=... level=DEBUG message="task1 done" <-- 2 seconds later
timestamp=... level=INFO message=done <-- 1 second later
*/

按 Effect 控制日志级别

通过使用 Logger.withMinimumLogLevel(effect, level)，您可以为程序的特定部分启用不同的日志级别，提供对日志记录行为的细粒度控制。

logInfo

INFO 日志级别默认显示。此级别通常用于一般应用程序事件或进度更新。

示例（在信息级别记录日志）

import { Effect } from "effect"

const program = Effect.gen(function* () {
  yield* Effect.logInfo("start")
  yield* Effect.sleep("2 seconds")
  yield* Effect.sleep("1 second")
  yield* Effect.logInfo("done")
})

Effect.runFork(program)
/*
Output:
timestamp=... level=INFO message=start
timestamp=... level=INFO message=done <-- 3 seconds later
*/

logWarning

WARN 日志级别默认显示。此级别用于潜在问题或警告，这些问题不会立即中断程序流程，但应该被监控。

示例（在警告级别记录日志）

import { Effect, Either } from "effect"

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

const program = Effect.gen(function* () {
  const failureOrSuccess = yield* Effect.either(task)
  if (Either.isLeft(failureOrSuccess)) {
    yield* Effect.logWarning(failureOrSuccess.left)
    return 0
  } else {
    return failureOrSuccess.right
  }
})

Effect.runFork(program)
/*
Output:
timestamp=... level=WARN fiber=#0 message="Oh uh!"
*/

logError

ERROR 日志级别默认显示。这些消息表示需要解决的问题。

示例（在错误级别记录日志）

import { Effect, Either } from "effect"

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

const program = Effect.gen(function* () {
  const failureOrSuccess = yield* Effect.either(task)
  if (Either.isLeft(failureOrSuccess)) {
    yield* Effect.logError(failureOrSuccess.left)
    return 0
  } else {
    return failureOrSuccess.right
  }
})

Effect.runFork(program)
/*
Output:
timestamp=... level=ERROR fiber=#0 message="Oh uh!"
*/

logFatal

FATAL 日志级别默认显示。此日志级别通常保留给不可恢复的错误。

示例（在致命级别记录日志）

import { Effect, Either } from "effect"

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

const program = Effect.gen(function* () {
  const failureOrSuccess = yield* Effect.either(task)
  if (Either.isLeft(failureOrSuccess)) {
    yield* Effect.logFatal(failureOrSuccess.left)
    return 0
  } else {
    return failureOrSuccess.right
  }
})

Effect.runFork(program)
/*
Output:
timestamp=... level=FATAL fiber=#0 message="Oh uh!"
*/

自定义注解

您可以使用 Effect.annotateLogs 函数添加自定义注解来增强日志输出。 这允许您为每个日志条目附加额外的元数据，提高可追溯性并提供额外的上下文。

添加单个注解

您可以将单个注解作为键/值对应用于 Effect 内的所有日志条目。

示例（单个键/值注解）

import { Effect } from "effect"

const program = Effect.gen(function* () {
  yield* Effect.log("message1")
  yield* Effect.log("message2")
}).pipe(
  // 注解作为键/值对
  Effect.annotateLogs("key", "value")
)

Effect.runFork(program)
/*
Output:
timestamp=... level=INFO fiber=#0 message=message1 key=value
timestamp=... level=INFO fiber=#0 message=message2 key=value
*/

在此示例中，program 内生成的所有日志都将包含注解 key=value。

注解的作用域

使用 Effect.annotateLogs 应用的注解会自动添加到注解 Effect 作用域内生成的所有日志中，包括来自嵌套 Effect 的日志。

嵌套 Effect 的注解

注解会传播到嵌套或下游 Effect 内生成的所有日志。这确保来自任何子 Effect 的日志都继承父 Effect 的注解。

示例（将注解传播到嵌套 Effect）

在此示例中，注解 key=value 包含在所有日志中，甚至包括来自嵌套 anotherProgram Effect 的日志。

import { Effect } from "effect"

// 定义一个记录错误的子程序
const anotherProgram = Effect.gen(function* () {
  yield* Effect.logError("error1")
})

// 定义主程序
const program = Effect.gen(function* () {
  yield* Effect.log("message1")
  yield* Effect.log("message2")
  yield* anotherProgram // 调用嵌套程序
}).pipe(
  // 为作用域内的所有日志附加注解
  Effect.annotateLogs("key", "value")
)

Effect.runFork(program)
/*
Output:
timestamp=... level=INFO fiber=#0 message=message1 key=value
timestamp=... level=INFO fiber=#0 message=message2 key=value
timestamp=... level=ERROR fiber=#0 message=error1 key=value
*/

添加多个注解

您还可以通过传递包含键/值对的对象一次应用多个注解。每个键/值对都将添加到 Effect 内的每个日志条目中。

示例（多个注解）

import { Effect } from "effect"

const program = Effect.gen(function* () {
  yield* Effect.log("message1")
  yield* Effect.log("message2")
}).pipe(
  // 添加多个注解
  Effect.annotateLogs({ key1: "value1", key2: "value2" })
)

Effect.runFork(program)
/*
Output:
timestamp=... level=INFO fiber=#0 message=message1 key2=value2 key1=value1
timestamp=... level=INFO fiber=#0 message=message2 key2=value2 key1=value1
*/

在这种情况下，每个日志都将包含 key1=value1 和 key2=value2。

作用域注解

如果您想限制注解的作用域，使其仅应用于某些日志条目，可以使用 Effect.annotateLogsScoped。此函数将注解限制在特定作用域内产生的日志。

示例（作用域注解）

import { Effect } from "effect"

const program = Effect.gen(function* () {
  yield* Effect.log("no annotations") // 无注解
  yield* Effect.annotateLogsScoped({ key: "value" }) // 作用域注解
  yield* Effect.log("message1") // 应用注解
  yield* Effect.log("message2") // 应用注解
}).pipe(
  Effect.scoped,
  // 作用域外，无注解
  Effect.andThen(Effect.log("no annotations again"))
)

Effect.runFork(program)
/*
Output:
timestamp=... level=INFO fiber=#0 message="no annotations"
timestamp=... level=INFO fiber=#0 message=message1 key=value
timestamp=... level=INFO fiber=#0 message=message2 key=value
timestamp=... level=INFO fiber=#0 message="no annotations again"
*/

日志跨度

Effect 提供对日志跨度的内置支持，允许您测量和记录特定任务或代码段的持续时间。此功能有助于跟踪某些操作需要多长时间，让您更好地了解应用程序的性能。

示例（使用日志跨度测量任务持续时间）

import { Effect } from "effect"

const program = Effect.gen(function* () {
  // 模拟延迟以表示任务需要时间
  yield* Effect.sleep("1 second")
  // 记录表示作业完成的消息
  yield* Effect.log("The job is finished!")
}).pipe(
  // 应用标记为 "myspan" 的日志跨度来测量
  // 此操作的持续时间
  Effect.withLogSpan("myspan")
)

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

禁用默认日志记录

有时，也许在测试执行期间，您可能希望在应用程序中禁用默认日志记录。Effect 提供了几种在需要时关闭日志记录的方法。在本节中，我们将了解在 Effect 框架中禁用日志记录的不同方法。

示例（使用 Logger.withMinimumLogLevel）

禁用日志记录的一种便捷方法是使用 Logger.withMinimumLogLevel 函数。这允许您将最小日志级别设置为 None，有效地关闭所有日志输出。

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

const program = Effect.gen(function* () {
  yield* Effect.log("Executing task...")
  yield* Effect.sleep("100 millis")
  console.log("task done")
})

// 默认行为：启用日志记录
Effect.runFork(program)
/*
Output:
timestamp=... level=INFO fiber=#0 message="Executing task..."
task done
*/

// 通过将最小日志级别设置为 'None' 来禁用日志记录
Effect.runFork(program.pipe(Logger.withMinimumLogLevel(LogLevel.None)))
/*
Output:
task done
*/

示例（使用层）

禁用日志记录的另一种方法是创建一个将最小日志级别设置为 LogLevel.None 的层，有效地关闭所有日志输出。

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

const program = Effect.gen(function* () {
  yield* Effect.log("Executing task...")
  yield* Effect.sleep("100 millis")
  console.log("task done")
})

// 创建禁用日志记录的层
const layer = Logger.minimumLogLevel(LogLevel.None)

// 应用层以禁用日志记录
Effect.runFork(program.pipe(Effect.provide(layer)))
/*
Output:
task done
*/

示例（使用自定义运行时）

您还可以通过创建包含关闭日志记录配置的自定义运行时来禁用日志记录：

import { Effect, Logger, LogLevel, ManagedRuntime } from "effect"

const program = Effect.gen(function* () {
  yield* Effect.log("Executing task...")
  yield* Effect.sleep("100 millis")
  console.log("task done")
})

// 创建禁用日志记录的自定义运行时
const customRuntime = ManagedRuntime.make(
  Logger.minimumLogLevel(LogLevel.None)
)

// 使用自定义运行时运行程序
customRuntime.runFork(program)
/*
Output:
task done
*/

从配置加载日志级别

要从配置动态加载日志级别并将其应用于程序，可以使用 Logger.minimumLogLevel 层。这允许您的应用程序根据外部配置调整其日志记录行为。

示例（从配置加载日志级别）

import {
  Effect,
  Config,
  Logger,
  Layer,
  ConfigProvider,
  LogLevel
} from "effect"

// 模拟带有日志的程序
const program = Effect.gen(function* () {
  yield* Effect.logError("ERROR!")
  yield* Effect.logWarning("WARNING!")
  yield* Effect.logInfo("INFO!")
  yield* Effect.logDebug("DEBUG!")
})

// 从配置加载日志级别并将其作为层应用
const LogLevelLive = Config.logLevel("LOG_LEVEL").pipe(
  Effect.andThen((level) =>
    // 设置最小日志级别
    Logger.minimumLogLevel(level)
  ),
  Layer.unwrapEffect // 将 Effect 转换为层
)

// 为程序提供加载的日志级别
const configured = Effect.provide(program, LogLevelLive)

// 使用模拟配置提供者测试程序
const test = Effect.provide(
  configured,
  Layer.setConfigProvider(
    ConfigProvider.fromMap(
      new Map([["LOG_LEVEL", LogLevel.Warning.label]])
    )
  )
)

Effect.runFork(test)
/*
Output:
... level=ERROR fiber=#0 message=ERROR!
... level=WARN fiber=#0 message=WARNING!
*/

使用 ConfigProvider 进行测试

ConfigProvider.fromMap 函数通过模拟配置值对测试很有用。您还可以参考在测试中模拟配置以获取在测试期间使用模拟配置的更多详细信息。

自定义记录器

在本节中，您将学习如何定义自定义记录器并将其设置为应用程序中的默认记录器。自定义记录器让您可以控制日志消息的处理方式，例如将它们路由到外部服务、写入文件或以特定方式格式化日志。

定义自定义记录器

您可以使用 Logger.make 函数定义自己的记录器。此函数允许您指定应如何处理日志消息。

示例（定义简单的自定义记录器）

import { Logger } from "effect"

// 将日志消息输出到控制台的自定义记录器
const logger = Logger.make(({ logLevel, message }) => {
  globalThis.console.log(`[${logLevel.label}] ${message}`)
})

在此示例中，自定义记录器将消息记录到控制台，日志级别和消息格式化为 [LogLevel] Message。

在程序中使用自定义记录器

假设您有以下任务和一个记录一些消息的程序：

import { Effect, Logger } from "effect"

// 将日志消息输出到控制台的自定义记录器
const logger = Logger.make(({ logLevel, message }) => {
  globalThis.console.log(`[${logLevel.label}] ${message}`)
})

const task1 = Effect.gen(function* () {
  yield* Effect.sleep("2 seconds")
  yield* Effect.logDebug("task1 done")
})

const task2 = Effect.gen(function* () {
  yield* Effect.sleep("1 second")
  yield* Effect.logDebug("task2 done")
})

const program = Effect.gen(function* () {
  yield* Effect.log("start")
  yield* task1
  yield* task2
  yield* Effect.log("done")
})

要用自定义记录器替换默认记录器，可以使用 Logger.replace 函数。创建替换默认记录器的层后，使用 Effect.provide 将其提供给程序。

示例（用自定义记录器替换默认记录器）

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

// 将日志消息输出到控制台的自定义记录器
const logger = Logger.make(({ logLevel, message }) => {
  globalThis.console.log(`[${logLevel.label}] ${message}`)
})

const task1 = Effect.gen(function* () {
  yield* Effect.sleep("2 seconds")
  yield* Effect.logDebug("task1 done")
})

const task2 = Effect.gen(function* () {
  yield* Effect.sleep("1 second")
  yield* Effect.logDebug("task2 done")
})

const program = Effect.gen(function* () {
  yield* Effect.log("start")
  yield* task1
  yield* task2
  yield* Effect.log("done")
})

// 用自定义记录器替换默认记录器
const layer = Logger.replace(Logger.defaultLogger, logger)

Effect.runFork(
  program.pipe(
    Logger.withMinimumLogLevel(LogLevel.Debug),
    Effect.provide(layer)
  )
)

当您运行上述程序时，以下日志消息将打印到控制台：

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

内置记录器

Effect 提供了几个内置记录器，您可以根据日志记录需求使用它们。这些记录器提供不同的格式，每种格式都适合不同的环境或目的，例如开发、生产或与外部日志记录服务集成。

每个记录器都有两种形式：记录器本身，以及使用记录器并将其输出发送到 Console 默认服务的层。例如，structuredLogger 记录器以详细的基于对象的格式生成日志，而 structured 层使用相同的记录器并将输出写入 Console 服务。

stringLogger（默认）

stringLogger 记录器以人类可读的键值样式生成日志。这种格式在开发和生产中很常用，因为它简单且在控制台中易于阅读。

此记录器没有对应的层，因为它是默认记录器。

import { Effect } from "effect"

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

Effect.runFork(program)

输出：

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

logfmtLogger 记录器以人类可读的键值格式生成日志，类似于 stringLogger 记录器。主要区别是 logfmtLogger 删除额外的空格以使日志更紧凑。

import { Effect, Logger } from "effect"

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

Effect.runFork(program.pipe(Effect.provide(Logger.logFmt)))

输出：

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

prettyLogger 记录器通过使用颜色和缩进来增强日志输出的可读性，在开发期间在控制台中可视化扫描日志时特别有用。

import { Effect, Logger } from "effect"

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

Effect.runFork(program.pipe(Effect.provide(Logger.pretty)))

输出：

[11:37:14.265] [32mINFO[0m (#0) myspan=101ms: [1;36mmsg1[0m
  msg2
  [ [32m'msg3'[0m, [32m'msg4'[0m ]
  key2: value2
  key1: value1

structuredLogger

structuredLogger 记录器以详细的基于对象的格式生成日志。当您需要更可追踪的日志时，此格式很有用，特别是当其他系统分析它们或存储它们以供以后审查时。

import { Effect, Logger } from "effect"

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

Effect.runFork(program.pipe(Effect.provide(Logger.structured)))

输出：

{
  message: [ 'msg1', 'msg2', [ 'msg3', 'msg4' ] ],
  logLevel: '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.
logLevel	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

jsonLogger 记录器以 JSON 格式生成日志。这对于解析和存储 JSON 日志的工具或服务很有用。 它对 structuredLogger 记录器创建的对象调用 JSON.stringify。

import { Effect, Logger } from "effect"

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

Effect.runFork(program.pipe(Effect.provide(Logger.json)))

输出：

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

组合记录器

zip

Logger.zip 函数将两个记录器组合成一个新的记录器。这个新记录器将日志消息转发给两个原始记录器。

示例（组合两个记录器）

import { Effect, Logger } from "effect"

// 定义一个记录到控制台的自定义记录器
const logger = Logger.make(({ logLevel, message }) => {
  globalThis.console.log(`[${logLevel.label}] ${message}`)
})

// 组合默认记录器和自定义记录器
//
//      ┌─── Logger<unknown, [void, void]>
//      ▼
const combined = Logger.zip(Logger.defaultLogger, logger)

const program = Effect.log("something")

Effect.runFork(
  program.pipe(
    // 用组合记录器替换默认记录器
    Effect.provide(Logger.replace(Logger.defaultLogger, combined))
  )
)
/*
Output:
timestamp=2025-01-09T13:50:58.655Z level=INFO fiber=#0 message=something
[INFO] something
*/