Effect 中的指标

在复杂且高度并发的应用程序中，管理各种相互关联的组件可能相当具有挑战性。确保一切运行顺利并避免应用程序停机在这种设置中变得至关重要。

现在，让我们想象一下我们有一个复杂的基础设施，包含众多服务。这些服务在我们的服务器上被复制和分布。然而，我们通常缺乏对这些服务中发生的事情的洞察，包括错误率、响应时间和服务正常运行时间。这种可见性的缺乏可能使有效识别和解决问题变得困难。这就是 Effect Metrics 发挥作用的地方；它允许我们捕获和分析各种指标，为后续调查提供有价值的数据。

Effect Metrics 支持五种不同类型的指标：

指标	描述
Counter	计数器用于跟踪随时间增长的值，例如请求计数。它们帮助我们跟踪特定事件或操作发生的次数。
Gauge	仪表表示可以随时间上下波动的单个数值。它们通常用于监控像内存使用量这样可以持续变化的指标。
Histogram	直方图用于跟踪观察值在不同桶中的分布。它们通常用于像请求延迟这样的指标，让我们了解响应时间是如何分布的。
Summary	摘要提供对时间序列滑动窗口的洞察，并为时间序列的特定百分位数（通常称为分位数）提供指标。这对于理解延迟相关指标（如请求响应时间）特别有用。
Frequency	频率指标计算不同字符串值的出现次数。当您想要跟踪应用程序中不同事件或条件发生的频率时，它们很有用。

Counter

在指标的世界中，Counter 是一个表示单个数值的指标，该数值可以随时间递增和递减。可以将其视为跟踪变化的计数器，例如应用程序接收到的特定类型请求的数量，无论是增加还是减少。

与其他一些类型的指标（如 gauges）不同，我们关心的是特定时刻的值，而对于计数器，我们关心的是随时间累积的值。这意味着它提供了变化的运行总计，可以上升和下降，反映了某些指标的动态性质。

计数器的一些典型用例包括：

• 请求计数：监控服务器接收到的传入请求数量。
• 已完成任务：跟踪已成功完成的任务或进程数量。
• 错误计数：计算应用程序中错误的发生次数。

如何创建计数器

要创建计数器，您可以使用 Metric.counter 构造函数。

示例（创建计数器）

import { Metric, Effect } from "effect"

const requestCount = Metric.counter("request_count", {
  // 可选
  description: "用于跟踪请求的计数器"
})

创建后，计数器可以接受返回 number 的 effect，这将增加或减少计数器。

示例（使用计数器）

import { Metric, Effect } from "effect"

const requestCount = Metric.counter("request_count")

const program = Effect.gen(function* () {
  // 将计数器增加 1
  const a = yield* requestCount(Effect.succeed(1))
  // 将计数器增加 2
  const b = yield* requestCount(Effect.succeed(2))
  // 将计数器减少 4
  const c = yield* requestCount(Effect.succeed(-4))

  // 获取计数器的当前状态
  const state = yield* Metric.value(requestCount)
  console.log(state)

  return a * b * c
})

Effect.runPromise(program).then(console.log)
/*
输出：
CounterState {
  count: -1,
  ...
}
-8
*/

类型保持

将计数器应用于 effect 不会改变其原始类型。指标只是添加跟踪而不影响 effect 的输出类型。

计数器类型

您可以指定计数器跟踪 number 还是 bigint。

import { Metric } from "effect"

const numberCounter = Metric.counter("request_count", {
  description: "用于跟踪请求的计数器"
  // bigint: false // 默认值
})

const bigintCounter = Metric.counter("error_count", {
  description: "用于跟踪错误的计数器",
  bigint: true
})

仅递增计数器

如果您需要一个只递增的计数器，可以使用 incremental: true 选项。

示例（使用仅递增计数器）

import { Metric, Effect } from "effect"

const incrementalCounter = Metric.counter("count", {
  description: "只增加其值的计数器",
  incremental: true
})

const program = Effect.gen(function* () {
  const a = yield* incrementalCounter(Effect.succeed(1))
  const b = yield* incrementalCounter(Effect.succeed(2))
  // 这对计数器没有影响
  const c = yield* incrementalCounter(Effect.succeed(-4))

  const state = yield* Metric.value(incrementalCounter)
  console.log(state)

  return a * b * c
})

Effect.runPromise(program).then(console.log)
/*
输出：
CounterState {
  count: 3,
  ...
}
-8
*/

在此配置中，计数器只接受正值。任何递减尝试都不会产生影响，确保计数器严格向上计数。

具有常量输入的计数器

您可以配置计数器在每次调用时始终按固定值递增。

示例（常量输入）

import { Metric, Effect } from "effect"

const taskCount = Metric.counter("task_count").pipe(
  Metric.withConstantInput(1) // 自动递增 1
)

const task1 = Effect.succeed(1).pipe(Effect.delay("100 millis"))
const task2 = Effect.succeed(2).pipe(Effect.delay("200 millis"))
const task3 = Effect.succeed(-4).pipe(Effect.delay("300 millis"))

const program = Effect.gen(function* () {
  const a = yield* taskCount(task1)
  const b = yield* taskCount(task2)
  const c = yield* taskCount(task3)

  const state = yield* Metric.value(taskCount)
  console.log(state)

  return a * b * c
})

Effect.runPromise(program).then(console.log)
/*
输出：
CounterState {
  count: 3,
  ...
}
-8
*/

Gauge

在指标的世界中，Gauge 是一个表示可以设置或调整的单个数值的指标。可以将其视为可以随时间变化的动态变量。仪表的一个常见用例是监控应用程序的当前内存使用情况。

与计数器不同，我们关心的是随时间累积的值，而对于仪表，我们关注的是特定时间点的当前值。

当您想要监控可以增加和减少的值，并且不关心跟踪其变化率时，仪表是最佳选择。换句话说，仪表帮助我们测量在特定时刻具有特定值的事物。

仪表的一些典型用例包括：

• 内存使用量：关注应用程序当前使用的内存量。
• 队列大小：监控等待处理任务的队列的当前大小。
• 进行中的请求计数：跟踪服务器当前正在处理的请求数量。
• 温度：测量可以上下波动的当前温度。

如何创建仪表

要创建仪表，您可以使用 Metric.gauge 构造函数。

示例（创建仪表）

import { Metric } from "effect"

const memory = Metric.gauge("memory_usage", {
  // 可选
  description: "用于内存使用量的仪表"
})

创建后，可以通过传递产生您想要为仪表设置的值的 effect 来更新仪表。

示例（使用仪表）

import { Metric, Effect, Random } from "effect"

// 创建一个跟踪温度的仪表
const temperature = Metric.gauge("temperature")

// 模拟获取随机温度
const getTemperature = Effect.gen(function* () {
  // 获取 -10 到 10 之间的随机温度
  const t = yield* Random.nextIntBetween(-10, 10)
  console.log(`new temperature: ${t}`)
  return t
})

// 多次更新仪表的程序
const program = Effect.gen(function* () {
  const series: Array<number> = []
  // 用新的温度读数更新仪表
  series.push(yield* temperature(getTemperature))
  series.push(yield* temperature(getTemperature))
  series.push(yield* temperature(getTemperature))

  // 检索仪表的当前状态
  const state = yield* Metric.value(temperature)
  console.log(state)

  return series
})

Effect.runPromise(program).then(console.log)
/*
示例输出：
new temperature: 9
new temperature: -9
new temperature: 2
GaugeState {
  value: 2, // 仪表中设置的最新值
  ...
}
[ 9, -9, 2 ]
*/

仪表行为

仪表捕获设置的最新值，因此如果您正在跟踪一系列更新，最终状态将只显示最后记录的值，而不是整个系列。

仪表类型

您可以指定仪表跟踪 number 还是 bigint。

import { Metric } from "effect"

const numberGauge = Metric.gauge("memory_usage", {
  description: "用于内存使用量的仪表"
  // bigint: false // 默认值
})

const bigintGauge = Metric.gauge("cpu_load", {
  description: "用于 CPU 负载的仪表",
  bigint: true
})

Histogram

Histogram 是一个用于分析数值随时间分布情况的指标。直方图不关注单个数据点，而是将值分组到预定义的范围（称为桶）中，并跟踪有多少值落入每个范围。

当记录一个值时，它会根据其范围被分配到直方图的某个桶中。每个桶都有一个上边界，如果值小于或等于其边界，该桶的计数就会增加。一旦记录，单个值就会被丢弃，重点转移到有多少值落入每个桶中。

直方图还跟踪：

• 总计数：已观察到的值的数量。
• 总和：所有观察值的总和。
• 最小值：观察到的最小值。
• 最大值：观察到的最大值。

直方图对于计算百分位数特别有用，通过分析每个桶中有多少值，可以帮助您估计数据集中的特定点。

这个概念受到 Prometheus（一个知名的监控和告警工具包）的启发。

直方图在性能分析和系统监控中特别有用。通过检查响应时间、延迟或其他指标的分布情况，您可以获得对系统行为的宝贵洞察。这些数据帮助您识别异常值、性能瓶颈或可能需要优化的趋势。

直方图的常见用例包括：

• 百分位数估计：直方图允许您近似观察值的百分位数，如响应时间的第 95 百分位数。
• 已知范围：如果您可以提前估计值的范围，直方图可以将数据组织到预定义的桶中以便更好地分析。
• 性能指标：使用直方图跟踪请求延迟、内存使用量或随时间变化的吞吐量等指标。
• 聚合：直方图可以跨多个实例聚合，使其成为分布式系统的理想选择，在这些系统中您需要从不同来源收集数据。

直方图桶和精度

请记住，直方图不保留确切的值。相反，它们将值分组到桶中，因此数据的精度取决于您如何定义这些桶。

示例（具有线性桶的直方图）

在此示例中，我们定义了一个具有线性桶的直方图，其中值的范围从 0 到 100，增量为 10。此外，我们还包括一个用于大于 100 的值的最终桶，称为”无穷大”桶。此配置对于跟踪特定范围内的数值（如请求延迟）很有用。

程序生成 1 到 120 之间的随机数，将它们记录在直方图中，然后打印直方图的状态，显示落入每个桶的值的计数。

import { Effect, Metric, MetricBoundaries, Random } from "effect"

// 定义一个跟踪请求延迟的直方图，使用线性桶
const latency = Metric.histogram(
  "request_latency",
  // 从 0-100 的桶，加上一个额外的无穷大桶
  MetricBoundaries.linear({ start: 0, width: 10, count: 11 }),
  // 可选
  "测量请求延迟的分布。"
)

const program = Effect.gen(function* () {
  // 生成 100 个随机值并将它们记录在直方图中
  yield* latency(Random.nextIntBetween(1, 120)).pipe(Effect.repeatN(99))

  // 获取并显示直方图的状态
  const state = yield* Metric.value(latency)
  console.log(state)
})

Effect.runPromise(program)
/*
示例输出：
HistogramState {
  buckets: [
    [ 0, 0 ],    // 0-10 范围内没有值
    [ 10, 7 ],   // 10-20 范围内有 7 个值
    [ 20, 11 ],  // 20-30 范围内有 11 个值
    [ 30, 20 ],  // 30-40 范围内有 20 个值
    [ 40, 27 ],  // 以此类推...
    [ 50, 38 ],
    [ 60, 53 ],
    [ 70, 64 ],
    [ 80, 73 ],
    [ 90, 84 ],
    [ Infinity, 100 ] // 所有 100 个值都已记录
  ],
  count: 100,  // 观察值的总计数
  min: 1,      // 观察到的最小值
  max: 119,    // 观察到的最大值
  sum: 5980,   // 所有观察值的总和
  ...
}
*/

计时器指标

在此示例中，我们演示如何使用计时器指标来跟踪特定工作流的持续时间。计时器捕获某些任务执行所需的时间，将此信息存储在直方图中，从而提供对这些持续时间分布的洞察。

我们生成随机值来模拟不同的等待时间，在计时器中记录持续时间，然后打印出直方图的状态。

示例（使用计时器指标跟踪工作流持续时间）

import { Metric, Array, Random, Effect } from "effect"

// 创建一个具有从 1 到 10 预定义边界的计时器指标
const timer = Metric.timerWithBoundaries("timer", Array.range(1, 10))

// 定义一个模拟随机等待时间的任务
const task = Effect.gen(function* () {
  // 生成 1 到 10 之间的随机值
  const n = yield* Random.nextIntBetween(1, 10)
  // 基于随机值模拟延迟
  yield* Effect.sleep(`${n} millis`)
})

const program = Effect.gen(function* () {
  // 跟踪任务的持续时间并重复 100 次
  yield* Metric.trackDuration(task, timer).pipe(Effect.repeatN(99))

  // 检索并打印计时器直方图的当前状态
  const state = yield* Metric.value(timer)
  console.log(state)
})

Effect.runPromise(program)
/*
示例输出：
HistogramState {
  buckets: [
    [ 1, 3 ],   // 3 个任务在 <= 1 ms 内完成
    [ 2, 13 ],  // 13 个任务在 <= 2 ms 内完成
    [ 3, 17 ],  // 以此类推...
    [ 4, 26 ],
    [ 5, 35 ],
    [ 6, 43 ],
    [ 7, 53 ],
    [ 8, 56 ],
    [ 9, 65 ],
    [ 10, 72 ],
    [ Infinity, 100 ]      // 所有 100 个任务都已完成
  ],
  count: 100,              // 观察到的任务总数
  min: 0.25797,            // 最短任务持续时间（毫秒）
  max: 12.25421,           // 最长任务持续时间（毫秒）
  sum: 683.0266810000002,  // 所有任务花费的总时间
  ...
}
*/

Summary

Summary 是一个通过计算特定百分位数来洞察一系列数据点的指标。百分位数帮助我们了解数据是如何分布的。例如，如果您正在跟踪过去一小时内请求的响应时间，您可能想要检查关键百分位数，如第 50、90、95 或 99 百分位数，以更好地了解系统的性能。

Summary 与直方图类似，都观察 number 值，但采用不同的方法。Summary 不是立即将值分类到桶中并丢弃它们，而是在内存中保留观察到的值。但是，为了避免存储过多数据，summary 使用两个参数：

• maxAge：值在被丢弃之前可以拥有的最大年龄。
• maxSize：summary 中存储的最大值数量。

这创建了一个最近值的滑动窗口，因此 summary 始终表示固定数量的最新观察值。

Summary 通常用于在此滑动窗口上计算分位数。分位数是介于 0 和 1 之间的数字，表示小于或等于某个阈值的值的百分比。例如，分位数 0.5（或第 50 百分位数）是中位数值，而 0.95（或第 95 百分位数）将表示 95% 的观察数据都低于该值。

分位数对于监控重要的性能指标（如延迟）以及确保系统满足性能目标（如服务级别协议或 SLA）很有帮助。

Effect Metrics API 还允许您使用误差边界配置 summary。此边界为分位数引入了可接受值的范围，提高了结果的准确性。

Summary 在以下情况下特别有用：

• 您观察的值范围事先未知或未估计，使得直方图不太实用。
• 您不需要跨多个实例聚合数据或平均结果。Summary 在应用程序端计算其结果，这意味着它们专注于使用它们的特定实例。

示例（创建和使用 Summary）

在此示例中，我们将创建一个 summary 来跟踪响应时间。该 summary 将：

• 保存多达 100 个样本。
• 丢弃超过 1 天 的样本。
• 在计算分位数时具有 3% 的误差边界。
• 报告 10%、50% 和 90% 分位数，这有助于跟踪响应时间分布。

我们将把 summary 应用于生成随机整数的 effect，模拟响应时间。

import { Metric, Random, Effect } from "effect"

// 定义响应时间的 summary
const responseTimeSummary = Metric.summary({
  name: "response_time_summary", // summary 指标的名称
  maxAge: "1 day", // 最大样本年龄
  maxSize: 100, // 要保留的最大样本数
  error: 0.03, // 分位数计算的误差边界
  quantiles: [0.1, 0.5, 0.9], // 要观察的分位数（10%、50%、90%）
  // 可选
  description: "测量响应时间的分布"
})

const program = Effect.gen(function* () {
  // 记录 100 个 1 到 120 ms 之间的随机响应时间
  yield* responseTimeSummary(Random.nextIntBetween(1, 120)).pipe(
    Effect.repeatN(99)
  )

  // 检索并记录 summary 的当前状态
  const state = yield* Metric.value(responseTimeSummary)
  console.log("%o", state)
})

Effect.runPromise(program)
/*
示例输出：
SummaryState {
  error: 0.03,    // 用于分位数计算的误差边界
  quantiles: [
    [ 0.1, { _id: 'Option', _tag: 'Some', value: 17 } ],   // 第 10 百分位数：17 ms
    [ 0.5, { _id: 'Option', _tag: 'Some', value: 62 } ],   // 第 50 百分位数（中位数）：62 ms
    [ 0.9, { _id: 'Option', _tag: 'Some', value: 109 } ]   // 第 90 百分位数：109 ms
  ],
  count: 100,    // 记录的样本总数
  min: 4,        // 观察到的最小值
  max: 119,      // 观察到的最大值
  sum: 6058,     // 所有记录值的总和
  ...
}
*/

Frequency

Frequency 是帮助计算特定值出现次数的指标。可以将它们视为一组计数器，每个计数器都与一个唯一值相关联。当观察到新值时，频率指标会自动为这些值创建新的计数器。

Frequency 对于跟踪不同字符串值出现的频率特别有用。一些示例用例包括：

• 计算应用程序中每个服务的调用次数，其中每个服务都有一个逻辑名称。
• 监控不同类型故障发生的频率。

示例（跟踪错误发生次数）

在此示例中，我们将创建一个 Frequency 来观察不同错误代码出现的频率。这可以应用于返回 string 值的 effect：

import { Metric, Random, Effect } from "effect"

// 定义一个跟踪错误的频率指标
const errorFrequency = Metric.frequency("error_frequency", {
  // 可选
  description: "计算错误的发生次数。"
})

const task = Effect.gen(function* () {
  const n = yield* Random.nextIntBetween(1, 10)
  return `Error-${n}`
})

// 模拟随机错误并跟踪其发生次数的程序
const program = Effect.gen(function* () {
  yield* errorFrequency(task).pipe(Effect.repeatN(99))

  // 检索并记录频率的当前状态
  const state = yield* Metric.value(errorFrequency)
  console.log("%o", state)
})

Effect.runPromise(program)
/*
示例输出：
FrequencyState {
  occurrences: Map(9) {
    'Error-7' => 12,
    'Error-2' => 12,
    'Error-4' => 14,
    'Error-1' => 14,
    'Error-9' => 8,
    'Error-6' => 11,
    'Error-5' => 9,
    'Error-3' => 14,
    'Error-8' => 6
  },
  ...
}
*/

标记指标

标签是您可以添加到指标的键值对，以提供额外的上下文。它们有助于对指标进行分类和过滤，使分析应用程序性能或行为的特定方面变得更容易。

创建指标时，您可以向其添加标签。标签是提供额外上下文的键值对，有助于对指标进行分类和过滤。这使得分析和监控应用程序的特定方面变得更容易。

标记特定指标

您可以使用 Metric.tagged 函数标记单个指标。 这允许您向单个指标添加特定标签，提供详细的上下文而不全局应用标签。

示例（标记单个指标）

import { Metric } from "effect"

// 创建一个请求计数的计数器指标
// 并用 "environment: production" 标记它
const counter = Metric.counter("request_count").pipe(
  Metric.tagged("environment", "production")
)

在这里，request_count 指标被标记为 "environment": "production"，允许您稍后按此标签过滤或分析指标。

标记多个指标

您可以使用 Effect.tagMetrics 将标签应用于同一上下文中的所有指标。当您想要在多个指标中应用通用标签（如环境，例如 “production” 或 “development”）时，这很有用。

示例（标记多个指标）

import { Metric, Effect } from "effect"

// 创建两个独立的计数器
const counter1 = Metric.counter("counter1")
const counter2 = Metric.counter("counter2")

// 定义一个模拟一些工作并稍有延迟的任务
const task = Effect.succeed(1).pipe(Effect.delay("100 millis"))

// 在同一上下文中将环境标签应用于两个计数器
Effect.gen(function* () {
  yield* counter1(task)
  yield* counter2(task)
}).pipe(Effect.tagMetrics("environment", "production"))

如果您只想在特定 作用域 内应用标签，可以使用 Effect.tagMetricsScoped。这将标签应用限制在该作用域内的指标，允许更精确的标记控制。