第 3 章 采集代理部署方式

3.1 部署方式全景对比

慢帧采集代理的部署直接影响数据完整性与运维成本。在生产环境中，根据应用架构和团队能力，可选择三种主流部署方式：Agent 安装模式、SDK 集成方式 和 配置中心下发。三种方式在侵入性、灵活性和运维复杂度上各有侧重。

3.2 Agent 安装模式

Agent 安装模式通过在主机上部署独立的守护进程（Daemon），借助系统级钩子（如 eBPF、ptrace 或内核模块）或 JDK 代理接口（JVMTI）挂载到目标进程中，无侵入地采集慢帧数据。实现流程如下：

1. 下载 Agent 包：从 APM 仓库获取适配主机架构的二进制包。
2. 安装与注册：在目标主机上解压并执行安装脚本，将 Agent 注册为系统服务。
3. 配置 attach：通过配置文件指定需监控的进程 PID、监听端口或应用名称。
4. 验证连接：Agent 与 APM 后端建立 gRPC/HTTP 长连接，上报心跳与慢帧指标。

# 示例：安装 APM Agent
curl -fsSL https://apm-repo.example.com/install/agent.sh | bash

# 配置文件路径：/etc/apm-agent/config.toml
[target]
processes = ["java", "node"]
sampling_rate = 0.05          # 慢帧采样率，5%
slow_threshold_ms = 100       # 帧渲染超时阈值

[backend]
endpoint = "apm-collector.service.consul:4318"
tls = true

3.3 SDK 集成方式

SDK 集成方式要求开发人员在应用代码中显式引入 APM SDK 并初始化探针。该方式能精确控制采集粒度，适合需要定制埋点、依赖注入或与现有链路追踪（如 OpenTelemetry）集成的场景。

• 引入依赖：以 Maven/Gradle/Go mod 方式添加 SDK 包。
• 初始化配置：在应用启动阶段创建 Tracer 实例，设置采样率与阈值。
• 埋点采集：利用 SDK 提供的装饰器或中间件自动拦截关键方法（如 UI 渲染、服务调用）。
• 数据导出：采集结果通过 SDK 内置的 Exporter 异步发送至后端。

// Java SDK 初始化示例
APMConfig config = APMConfig.builder()
    .serviceName("user-service")
    .samplingRate(0.2)           // 20% 采样
    .slowFrameThreshold(200)     // 慢帧阈值 200ms
    .exporter(Exporter.otlp("localhost:4318"))
    .build();

APM.init(config);

// 方法级埋点（自动捕获渲染耗时）
@Monitor("renderFrame")
public void renderFrame() {
    // ... 渲染逻辑
}

3.4 配置中心下发

配置中心下发模式并非独立的部署方式，而是对 Agent / SDK 的动态管理增强。通过在配置中心（如 etcd、Apollo、Consul）中维护统一的采配策略，所有已部署的代理实例通过长轮询或 Watch 机制实时拉取最新阈值与采样率。

# 配置中心 Key-Value 结构示例（JSON）
{
  "apm": {
    "global": {
      "sampling_rate": 0.1,
      "slow_threshold_ms": 150
    },
    "service_specific": {
      "payment-svc": {
        "sampling_rate": 0.5,
        "slow_threshold_ms": 80
      }
    }
  }
}

// Agent 端配置监听代码片段（伪代码）
func watchConfig() {
    watcher := configCenter.Watch("/apm/")
    for change := range watcher.Chan() {
        if change.Key == "sampling_rate" {
            agent.ReloadSamplingRate(change.Value)
        }
    }
}

3.5 整体架构流程

下图展示了三种部署方式在典型微服务架构中的协同关系：Agent 以独立进程附着于主机，SDK 嵌入在每个服务实例内部，二者均可通过配置中心实现动态调整。

3.6 常见错误与稳定性优化