一、前提条件
iOS 项目已集成 QAPM 5.4.9+。
二、基础集成（快速接入）
1. 下载 QAPMMonitorClientInterceptor 文件。
2. 将 QAPMMonitorClientInterceptor.swift 文件添加到 Xcode 工程。
3. 创建拦截器工厂。
import Foundationimport GRPCimport Logging// 假设GreeterClientInterceptorFactoryProtocol、HelloRequest、HelloResponse 是通过业务工程的hello.proto生成的协议final class QAPMInterceptorFactory: GreeterClientInterceptorFactoryProtocol, @unchecked Sendable { func makeSayHelloInterceptors() -> [ClientInterceptor<HelloRequest, HelloResponse>] { let interceptor = QAPMMonitorClientInterceptor<HelloRequest, HelloResponse>() return [interceptor] } }
4. 新建 GrpcModels+QAPM.swift 文件，实现协议拓展。
//假设上述已经实现了HelloRequest、HelloResponse extension HelloRequest: QAPMGRPCDataProtocol { public var gRPCRequestData: Data? { return try? self.serializedData() } } extension HelloResponse: QAPMGRPCDataProtocol { public var gRPCRequestData: Data? { return try? self.serializedData() } }
5. 创建 gRPC 客户端。
final class SyncGreeterClient { private let group: EventLoopGroup private let client: GreeterNIOClient init(host: String, port: Int) throws { self.group = MultiThreadedEventLoopGroup(numberOfThreads: 1) let interceptorFactory = QAPMInterceptorFactory() let channel = try GRPCChannelPool.with( target: .host(host, port: port), transportSecurity: .plaintext, eventLoopGroup: group ) self.client = GreeterNIOClient( channel: channel, interceptors: interceptorFactory ) }}
三、高阶配置（定制化监控）
如果当前拦截器采集的数据不能满足你的业务需求，你可以使用自定义回调接口上报更多的数据，调用方式如下：
final class QAPMInterceptorFactory: GreeterClientInterceptorFactoryProtocol, @unchecked Sendable { // onStart、sendMessage、onMessage、onClose 通过回调接口注入业务特定数据，可选配置 private var onStart: ((inout QAPMGrpcMeta) -> Void)? private var sendMessage: ((inout QAPMGrpcMeta) -> Void)? private var onMessage: ((inout QAPMGrpcMeta) -> Void)? private var onClose: ((inout QAPMGrpcMeta) -> Void)? init( onStart: ((inout QAPMGrpcMeta) -> Void)? = nil, sendMessage: ((inout QAPMGrpcMeta) -> Void)? = nil, onMessage: ((inout QAPMGrpcMeta) -> Void)? = nil, onClose: ((inout QAPMGrpcMeta) -> Void)? = nil ) { self.onStart = onStart self.sendMessage = sendMessage self.onMessage = onMessage self.onClose = onClose } func makeSayHelloInterceptors() -> [ClientInterceptor<HelloRequest, HelloResponse>] { let interceptor = QAPMMonitorClientInterceptor<HelloRequest, HelloResponse>() interceptor.onStart = onStart interceptor.sendMessage = sendMessage interceptor.onMessage = onMessage interceptor.onClose = onClose return [interceptor] }}
实现上述接口，我们会在5个不同的时机分别回调。
| 回调方法 | 回调时机 |
| onStart | 接口开始执行 |
| sendMessage | 每次发送消息的时候 |
| onMessage | 每次接收消息的时候 |
| onClose | 请求结束的时候 |
uv & ud 字段详解。
| 字段类型 | 命名规则 | 数据类型 | 数量限制 | 典型应用场景 |
| uv | uv1 ~ uv10 | Int | 10个 | 分段耗时等，主要用于指标的聚合 |
| ud | ud1~ud5 | String | 5个 | 地区、服务端 IP 等，主要用于日志上下文的展示 |
使用示例。
let factory = QAPMInterceptorFactory( onStart: { meta in meta.ud1 = UUID().uuidString }, sendMessage: { meta in meta.uv1 = Int(Date().timeIntervalSince1970 * 1000) }, onClose: { meta in meta.ud2 = "server.ip" meta.ud3 = "region" meta.uv2 = Int(Date().timeIntervalSince1970 * 1000) })
四、校验功能是否正常
gRPC 监控数据聚合上报，每1min上报一次，如打印以下日志，则代表原生网络监控数据上报成功。
检索 Plugin:42，且 protocol 对应的 value 为 grpc。