Phoenix LiveDashboard 指标历史数据配置指南

Phoenix LiveDashboard 指标历史数据配置指南

什么是指标历史数据

在 Phoenix LiveDashboard 中，指标历史数据功能允许开发者查看各项性能指标随时间变化的趋势图。这对于监控系统性能、排查问题以及分析系统行为模式非常有价值。

基础配置方法

要为 LiveDashboard 配置指标历史数据功能，需要在路由配置中添加 metrics_history 参数。这个参数指向一个实现了历史数据存储和查询功能的模块。

live_dashboard "/dashboard",
  metrics: MyAppWeb.Telemetry,
  metrics_history: {MyAppWeb.MetricsStorage, :metrics_history, []}

历史数据存储模块实现

核心要求

历史数据存储模块需要实现以下关键功能：

1. 能够接收并存储来自 Telemetry 的指标数据
2. 能够按需返回特定指标的历史数据
3. 历史数据格式必须包含:label、:measurement和:time三个字段

推荐实现方案

我们推荐使用 GenServer 配合环形缓冲区(Circular Buffer)来实现这一功能，这种方案具有以下优点：

• 内存占用可控
• 自动淘汰旧数据
• 实现简单高效

具体实现代码

defmodule MyAppWeb.MetricsStorage do
  use GenServer

  # 设置历史数据缓冲区大小
  @history_buffer_size 50

  # 客户端API：获取指标历史数据
  def metrics_history(metric) do
    GenServer.call(__MODULE__, {:data, metric})
  end

  # 启动GenServer
  def start_link(args) do
    GenServer.start_link(__MODULE__, args, name: __MODULE__)
  end

  # 初始化：为每个指标设置Telemetry处理器
  @impl true
  def init(metrics) do
    Process.flag(:trap_exit, true)
    
    metric_histories_map =
      metrics
      |> Enum.map(fn metric ->
        attach_handler(metric)
        {metric, CircularBuffer.new(@history_buffer_size)}
      end)
      |> Map.new()

    {:ok, metric_histories_map}
  end

  # 清理：退出时移除所有Telemetry处理器
  @impl true
  def terminate(_, metrics) do
    for metric <- metrics do
      :telemetry.detach({__MODULE__, metric, self()})
    end
    :ok
  end

  # 私有函数：为每个指标附加Telemetry处理器
  defp attach_handler(%{event_name: name_list} = metric) do
    :telemetry.attach(
      {__MODULE__, metric, self()},
      name_list,
      &__MODULE__.handle_event/4,
      metric
    )
  end

  # 处理Telemetry事件
  def handle_event(_event_name, data, metadata, metric) do
    if data = Phoenix.LiveDashboard.extract_datapoint_for_metric(metric, data, metadata) do
      GenServer.cast(__MODULE__, {:telemetry_metric, data, metric})
    end
  end

  # 处理指标数据更新请求
  @impl true
  def handle_cast({:telemetry_metric, data, metric}, state) do
    {:noreply, update_in(state[metric], &CircularBuffer.insert(&1, data))}
  end

  # 处理历史数据查询请求
  @impl true
  def handle_call({:data, metric}, _from, state) do
    if history = state[metric] do
      {:reply, CircularBuffer.to_list(history), state}
    else
      {:reply, [], state}
    end
  end
end

部署到应用

完成模块编写后，需要将其添加到应用的监控树中：

# 在application.ex中
children = [
  # 其他子进程...
  {MyAppWeb.MetricsStorage, MyAppWeb.Telemetry.metrics()}
]

技术细节解析

1. 环形缓冲区选择：使用环形缓冲区可以自动限制内存使用，最新的数据会覆盖最旧的数据，非常适合监控场景。

2. Telemetry处理器：为每个指标动态附加处理器，确保只收集需要的指标数据。

3. 数据格式转换：使用Phoenix.LiveDashboard.extract_datapoint_for_metric/4确保数据格式符合要求。

4. 并发处理：GenServer的设计确保了在多客户端访问时的线程安全。

高级配置选项

1. 缓冲区大小调整：可以根据实际需求调整@history_buffer_size的值，平衡内存使用和历史数据深度。

2. 多指标支持：模块设计支持同时监控多个指标，每个指标有独立的缓冲区。

3. 自定义存储后端：虽然示例使用了内存存储，但可以轻松修改为使用Redis、数据库等持久化存储方案。

常见问题解答

Q: 为什么我的历史数据图表没有显示？ A: 请检查以下几点：

• 确保MetricsStorage模块已正确添加到应用监控树
• 确认Telemetry事件是否正常触发
• 检查extract_datapoint_for_metric是否返回了有效数据

Q: 如何扩展存储更多历史数据？ A: 可以增大缓冲区大小或实现基于磁盘的存储方案，但要注意性能影响。

通过本文的配置，你的Phoenix应用将能够展示丰富的指标历史数据图表，为性能监控和问题排查提供有力支持。