为 Elixir 与 Node.js 异构系统构建统一可观测性平面的架构决策与实现

架构设计

文章字数: 3.7k

阅读时长: 15 分

问题的定义：异构系统中的调试黑洞

我们面临的场景并不罕见：一个面向用户的产品，其技术栈由多个语言和框架构成。前端采用 React 与 Styled-components 构建高度动态化的用户界面；一个 Node.js 服务作为 BFF (Backend for Frontend)，负责聚合数据、处理部分视图逻辑，并为前端提供一个稳定的 GraphQL 或 REST API；后端核心服务则由 Elixir 构建，利用 BEAM 虚拟机的并发与容错能力处理海量 WebSocket 连接和实时数据流。

这个架构在职责划分上是清晰的：Node.js 擅长 I/O 密集与快速原型开发，非常适合 BFF 层；Elixir 则在处理大规模并发连接和构建高可用系统方面无出其右。问题在于，当一个用户操作（例如，在前端点击按钮发送一条实时消息）出现性能瓶颈或偶发性失败时，我们陷入了一个调试的黑洞。

请求的生命周期横跨了三个完全不同的技术领域：

浏览器: 用户交互，由 Styled-components 渲染的组件发起 API 请求。
Node.js (BFF): 接收请求，可能需要调用多个下游服务，进行数据转换。
Elixir (Core): 接收来自 BFF 的RPC调用，通过 GenServer 处理业务逻辑，并向其他客户端广播消息。

当用户反馈“消息发送慢了3秒”时，延迟发生在哪里？是前端渲染、网络传输、Node.js 的事件循环被阻塞，还是 Elixir 的某个进程邮箱积压？如果 Node.js 返回了一个 502 Bad Gateway，是 BFF 自身的问题，还是 Elixir 服务短暂不可用或返回了错误？传统的排查方式——在三个系统中分别翻阅日志——效率低下且极度依赖工程师的个人经验。日志的时间戳可能因时钟不同步而产生误导，并且我们无法将分散在各处的日志条目与同一次用户操作精确关联起来。这正是典型的异构系统可观测性缺失问题。

方案A：竖井式监控与日志聚合

第一个被提出的方案是基于现有工具的增强。每个技术栈都有其成熟的监控方案。

Node.js: 我们可以使用 pino 进行结构化日志记录，配合 Prometheus 客户端库暴露核心业务指标（如请求延迟、错误率），并通过 pm2 或类似工具进行进程监控。
Elixir: BEAM 虚拟机本身提供了丰富的遥测（Telemetry）事件。我们可以利用 telemetry_metrics 和 prometheus.ex 将这些指标（如进程数、内存使用、ETS 表大小）暴露给 Prometheus。日志方面，Elixir 内置的 Logger 可以配置输出结构化的 JSON。
前端: 使用 RUM (Real User Monitoring) 工具监控页面加载性能、API 请求耗时和 JS 错误。

然后，我们将所有系统的结构化日志发送到一个集中的日志管理平台，如 Elasticsearch (ELK Stack) 或 Loki。

方案A的优势

技术成熟: 每个组件都是其生态系统内的标准实践，有大量的文档和社区支持。
实现简单: 各团队可以独立负责其服务的可观测性建设，无需强制统一技术栈。
低侵入性: 主要依赖库和配置，对现有业务代码的改动相对较小。

方案A的劣势

这是一个致命的缺陷：数据孤岛。尽管所有数据都集中了，但它们之间缺乏关联。在日志平台上，我们可以通过某个 userId 或 requestId 搜索，但这要求在每一层都手动、严格地传递和记录这个 ID。即便如此，我们也只能看到离散的事件点，无法构建出完整的调用链条。我们能看到 Node.js 在 T1 时刻调用了 Elixir，Elixir 在 T2 时刻返回，但我们不知道 Elixir 在 T1 到 T2 之间内部发生了什么，比如它又调用了哪个数据库或第三方服务。

这种方案就像给了我们一堆散落的拼图碎片，却没有拼图的盒子封面作为参考。在复杂问题面前，它依然无法高效地定位根因。对于跨服务的性能分析，几乎无能为力。

方案B：基于 OpenTelemetry 的统一可观测性平面

第二个方案是建立一个统一的可观测性数据平面，其核心是拥抱 OpenTelemetry (OTel) 标准。OTel 是一个由 CNCF 托管的开源项目，旨在提供一套统一的、厂商中立的 API、SDK 和工具，用于生成、收集和导出遥测数据（traces, metrics, logs）。

这个方案的架构如下：

graph TD
    subgraph Browser
        A[React App with Styled-components]
    end

    subgraph Node.js BFF
        B[Express.js / Koa.js]
        B -- instrumented by --> B_OTel[OTel SDK for Node.js]
    end

    subgraph Elixir Core Service
        C[Phoenix Framework]
        C -- instrumented by --> C_OTel[OTel SDK for Erlang/Elixir]
    end

    subgraph Observability Backend
        D[SkyWalking OAP Server]
        E[SkyWalking UI]
    end

    A -- HTTP Request with Trace Context --> B
    B_OTel -- OTLP Export --> D
    B -- gRPC/HTTP Call with Trace Context --> C
    C_OTel -- OTLP Export --> D
    D -- Stores & Analyzes Data --> E

    style D fill:#f9f,stroke:#333,stroke-width:2px

核心思想是：

统一标准: 在 Node.js 和 Elixir 服务中都集成 OpenTelemetry SDK。
上下文传播: 当请求从 Node.js 发往 Elixir 时，OTel SDK 会自动（或通过少量手动代码）将当前的追踪上下文（Trace Context），通常是 traceparent 和 tracestate 这两个 W3C 标准的 HTTP 头，注入到出站请求中。
链路生成: Elixir 端的 OTel SDK 会识别这个传入的 Trace Context，并创建一个新的 Span 作为 Node.js Span 的子 Span，从而将两个独立的操作链接成一个完整的 Trace。
统一后端: 所有服务都将其遥测数据通过 OTLP (OpenTelemetry Protocol) 协议发送到同一个支持该协议的后端，我们选择 Apache SkyWalking。SkyWalking 是一个成熟的 APM (Application Performance Monitoring) 系统，原生支持 OTLP，并提供强大的链路分析、拓扑图绘制和告警功能。

方案B的优势

消除黑洞: 提供了跨服务、跨技术栈的端到端请求视图。我们可以精确地看到一个用户操作在每个服务中花费的时间、内部调用以及潜在的错误。
标准化: 基于开放标准，避免了厂商锁定。未来如果需要更换后端（例如从 SkyWalking 换到 Jaeger 或其他商业方案），应用代码无需任何改动。
生态丰富: OpenTelemetry 社区提供了大量针对流行框架和库的自动插桩（auto-instrumentation）库，可以极大地减少手动埋点的工作量。

方案B的劣势

学习曲线: 团队需要理解 OpenTelemetry 的核心概念，如 Trace, Span, SpanContext, Baggage 等。
性能开销: 尽管 OTel SDK 设计得非常高效，但生成和导出遥测数据总会带来一定的 CPU 和网络开销。需要在生产环境中仔细评估并配置合理的采样策略。
集成复杂度: 对于 Elixir 这种非主流（相对于 Java/Go）的生态，OTel SDK 的成熟度和自动化程度可能略低，需要更多手动的配置和集成工作。

最终选择与理由

我们最终选择了方案B。尽管它有更高的初始复杂度，但它解决的是我们最核心的痛点。在一个日益复杂的微服务体系中，无法进行端到端追踪所带来的沟通成本和故障恢复时间（MTTR）的增加，远超过了学习和集成 OpenTelemetry 的成本。竖井式的监控方案（方案A）只能告诉我们“某个服务病了”，而统一追踪方案（方案B）则能告诉我们“请求在这条路径的这一步病了，病因是什么”。这对于维护一个健康的、可演进的系统至关重要。

核心实现概览

以下是关键部分的代码实现，展示了如何在 Node.js 和 Elixir 中配置 OpenTelemetry 并将其连接到 SkyWalking。

1. Node.js BFF (Express.js) 的追踪配置

首先，我们需要一个独立的 tracing.js 文件来初始化 OpenTelemetry SDK。这必须在应用代码加载之前执行。

package.json 关键依赖:

{
  "dependencies": {
    "@opentelemetry/api": "^1.7.0",
    "@opentelemetry/auto-instrumentations-node": "^0.39.0",
    "@opentelemetry/exporter-trace-otlp-grpc": "^0.48.0",
    "@opentelemetry/resources": "^1.21.0",
    "@opentelemetry/sdk-node": "^0.48.0",
    "@opentelemetry/semantic-conventions": "^1.21.0",
    "axios": "^1.6.5",
    "express": "^4.18.2"
  }
}

tracing.js:

// tracing.js
// 必须在所有其他模块之前导入，以确保所有模块都被正确地插桩
'use strict';

const process = require('process');
const { NodeSDK } = require('@opentelemetry/sdk-node');
const { getNodeAutoInstrumentations } = require('@opentelemetry/auto-instrumentations-node');
const { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-grpc');
const { Resource } = require('@opentelemetry/resources');
const { SemanticResourceAttributes } = require('@opentelemetry/semantic-conventions');

// 重要：配置 OTLP Exporter
// 默认指向 localhost:4317，确保你的 SkyWalking OAP 服务 gRPC 端口暴露在这里
// 在生产环境中，这应该是 SkyWalking OAP 服务的地址
const otlpExporter = new OTLPTraceExporter({
  // url: 'http://<skywalking-oap-hostname>:4317'
});

const sdk = new NodeSDK({
  // 定义服务资源属性，这会在 SkyWalking UI 中显示为服务名称
  resource: new Resource({
    [SemanticResourceAttributes.SERVICE_NAME]: 'nodejs-bff-service',
    [SemanticResourceAttributes.SERVICE_VERSION]: '1.0.0',
  }),
  traceExporter: otlpExporter,
  // 启用对常用库的自动插桩，例如 http, express, axios
  instrumentations: [getNodeAutoInstrumentations({
    '@opentelemetry/instrumentation-fs': {
        enabled: false, // 通常我们不关心文件系统操作的追踪，关闭以减少噪音
    },
  })],
});

// 优雅地关闭 SDK
process.on('SIGTERM', () => {
  sdk.shutdown()
    .then(() => console.log('Tracing terminated'))
    .catch((error) => console.log('Error terminating tracing', error))
    .finally(() => process.exit(0));
});

// 启动 SDK
try {
  sdk.start();
  console.log('OpenTelemetry SDK started for Node.js BFF service...');
} catch (error) {
  console.error('Error starting OpenTelemetry SDK', error);
}

app.js (Express 服务):

// app.js
const express = require('express');
const axios = require('axios');
const api = require('@opentelemetry/api');

const app = express();
const PORT = 3000;
// Elixir 服务的地址
const ELIXIR_SERVICE_URL = 'http://localhost:4000/api/process';

app.get('/user-action', async (req, res) => {
  // 获取当前的 tracer
  const tracer = api.trace.getTracer('nodejs-bff-tracer');
  // 创建一个自定义的 Span，作为自动生成的 Express Span 的子 Span
  await tracer.startActiveSpan('bff-logic:processing-user-action', async (span) => {
    try {
      console.log('BFF service received request, calling Elixir core service...');

      // 添加事件到 Span，这在调试时非常有用
      span.addEvent('Calling Elixir service');
      span.setAttribute('user.id', 'user-123');

      // 使用 axios 调用 Elixir 服务
      // OTel 的 http/https 插桩会自动注入 Trace Context 头
      const response = await axios.post(ELIXIR_SERVICE_URL, {
        userId: 'user-123',
        action: 'send_message'
      });
      
      span.addEvent('Received response from Elixir service');

      // 设置 Span 状态为成功
      span.setStatus({ code: api.SpanStatusCode.OK });
      res.status(200).json({ status: 'ok', data: response.data });

    } catch (error) {
      console.error('Error processing user action:', error.message);
      // 记录错误到 Span
      span.recordException(error);
      span.setStatus({ code: api.SpanStatusCode.ERROR, message: error.message });
      res.status(500).json({ status: 'error', message: 'Internal Server Error' });
    } finally {
      // 确保 Span 被关闭
      span.end();
    }
  });
});

app.listen(PORT, () => {
  console.log(`Node.js BFF service listening on port ${PORT}`);
});

要运行这个服务，需要先启动 tracing.js：
node -r ./tracing.js app.js

2. Elixir Core Service (Phoenix) 的追踪配置

在 Elixir 中，配置稍微不同，主要通过 mix.exs 和 config.exs 完成。

mix.exs 关键依赖:

def deps do
  [
    # ... 其他依赖
    {:opentelemetry_api, "~> 1.2"},
    {:opentelemetry, "~> 1.3"},
    {:opentelemetry_exporter, "~> 1.4"},
    {:opentelemetry_phoenix, "~> 1.2"},
    {:opentelemetry_cowboy, "~> 0.1.0"}, # Phoenix 1.7+ 使用 cowboy
    {:opentelemetry_ecto, "~> 1.1"}, # 如果使用 Ecto
  ]
end

config/config.exs:

import Config

# 配置 OpenTelemetry Exporter
# SkyWalking OAP gRPC 端口是 11800，HTTP 端口是 12800.
# OTLP gRPC 默认端口是 4317. SkyWalking OAP 同时支持原生协议和 OTLP.
# 这里我们配置使用 OTLP 协议以保持一致性。
config :opentelemetry, :processors,
  otel_batch_processor: %{
    exporter: {:opentelemetry_exporter, %{
      endpoints: ["http://localhost:4317"] # 指向 SkyWalking OAP gRPC endpoint
    }}
  }

# 配置资源属性
config :opentelemetry, :resource,
  service: %{
    name: "elixir-core-service",
    version: "1.0.0"
  }

在 application.ex 中启动 OpenTelemetry 进程:

# lib/my_app/application.ex
def start(_type, _args) do
  children = [
    # ...
    # 确保 OpenTelemetry application 在你的 app 之前启动
    # 在 mix.exs 的 :extra_applications 中添加 :opentelemetry
    MyWebApp.Endpoint
  ]
  # ...
end

然后在 mix.exs 中:
def application do [mod: {MyWebApp.Application, []}, extra_applications: [:logger, :runtime_tools, :opentelemetry]] end

创建 Plug 来处理传入的 Trace Context:

opentelemetry_phoenix 库提供了 OpenTelemetry.Phoenix.Pipeline，可以很方便地集成。

lib/my_web_app/endpoint.ex:

defmodule MyWebApp.Endpoint do
  use Phoenix.Endpoint, otp_app: :my_web_app

  # ...
  # 在 plug 管道的早期阶段插入 OpenTelemetry plug
  plug OpenTelemetry.Phoenix.Pipeline,
    tracer_id: :my_tracer,
    span_prefix: ["my_web_app", "phoenix", "endpoint"]

  plug Plug.Parsers,
    parsers: [:json],
    pass: ["*/*"],
    json_decoder: Jason

  plug MyWebApp.Router
  # ...
end

lib/my_web_app/router.ex 和 Controller:

# lib/my_web_app/router.ex
defmodule MyWebApp.Router do
  use MyWebApp, :router

  pipeline :api do
    plug :accepts, ["json"]
  end

  scope "/api", MyWebApp do
    pipe_through :api

    post "/process", ActionController, :process
  end
end

# lib/my_web_app/controllers/action_controller.ex
defmodule MyWebApp.ActionController do
  use MyWebApp, :controller
  require OpenTelemetry.API, as: OtelAPI
  import OpenTelemetry.Tracer

  def process(conn, _params) do
    # `opentelemetry_phoenix` 已经为我们创建了一个根 Span
    # 我们可以在其内部创建子 Span 来追踪更细粒度的操作
    with_span "elixir-logic:handle-message" do
      # 模拟一些耗时操作
      :timer.sleep(150)

      # 可以在 Span 上添加属性
      set_attribute("elixir.process.pid", inspect(self()))

      # 添加事件
      add_event("Finished core logic processing")
      
      json(conn, %{status: "processed by elixir", timestamp: DateTime.utc_now()})
    end
  end
end

现在，当 Node.js 服务调用 Elixir 服务的 /api/process 接口时，OpenTelemetry.Phoenix.Pipeline 会自动从请求头中提取 traceparent，并创建一个新的 Span，使其成为 Node.js 调用方 Span 的子节点。当我们在 ActionController 中使用 with_span 时，又创建了这个 Phoenix Span 的子 Span。这样，一条完整的、跨越两个服务的调用链就在 SkyWalking 中形成了。

架构的扩展性与局限性

这个基于 OpenTelemetry 的方案具有良好的扩展性。如果未来我们引入了第三个用 Go 或 Rust 编写的服务，只需为其集成相应的 OTel SDK，并指向同一个 SkyWalking 后端，它就能无缝地融入现有的追踪体系。我们甚至可以将追踪扩展到前端，使用 OpenTelemetry JS 库，从用户的点击事件开始捕获，从而获得包含前端性能在内的完整用户体验链路。

当然，该方案也存在局限性。首先，是采样带来的数据不完整性。在流量巨大的系统中，100% 的追踪是不可行的。采样策略（例如，头部采样或尾部采样）的选择是一个复杂的权衡，可能会导致某些偶发问题被遗漏。其次，自动插桩并非万能。对于一些不常见的库、或者非标准的 RPC 通信方式（例如直接通过 TCP socket），我们仍然需要手动创建 Span 并传播上下文，这增加了心智负担。最后，BEAM 虚拟机的并发模型与传统的线程模型不同，虽然 OpenTelemetry Erlang/Elixir 库对进程间上下文传递做了很好的支持，但在极其复杂的 GenServer 调用、任务监督树等场景下，要确保上下文始终正确传递，仍然需要开发者对 OTel 的工作原理有深刻的理解。未来的优化路径可能包括探索 eBPF 等技术实现更低开销、零侵入的自动化插桩。

Node.js Elixir SkyWalking Styled-components OpenTelemetry

使用AWS SQS与Apache Iceberg构建具备分布式一致性的DDD聚合根投影

2023-10-27 分布式系统

Apache Iceberg Domain-Driven Design (DDD) 分布式一致性 AWS SQS Transactional Outbox

基于 Quarkus 与图数据库构建 mTLS 双向认证的实时数据推送服务

2023-10-27 后端架构

RESTful API NoSQL Quarkus WebSockets mTLS