Envoy Mobile 本地统计观测指南Local Stats 分支与 statsd 调试实战【免费下载链接】envoyCloud-native high-performance edge/middle/service proxy项目地址: https://gitcode.com/GitHub_Trending/en/envoy本指南围绕 Envoy Mobile 的 Local Stats 调试方案展开通过local-stats分支在开发机本地启动一个 statsd 服务器让运行于 Android/iOS 模拟器中的客户端把统计指标实时发送过来从而在开发终端中直接观察每一次指标发射。读完本文你将掌握该方案的网络拓扑、配置要点含 Android 模拟器的10.0.2.2特殊地址、完整操作步骤以及底层 Envoy statsd Sink 与统计收集机制的源码级原理可直接用于日常开发中的统计指标排障。背景为什么要本地观测统计指标Envoy Mobile 内置了一套基于 Pulse 的客户端统计库用于捕获应用侧的时序指标。根据 PulseStatsAPI 文档当前支持的指标类型包括Counter、Gauge、Timer和Distribution四种且每种指标都支持在创建与上报两个阶段附加自定义标签tags。这些指标最终由底层 Envoy 引擎汇总并周期性地刷出flush。在生产或预发环境中统计指标通常被送往远程的 metrics 后端但在本地开发阶段开发者往往需要快速、直观地确认客户端到底发射了哪些统计、值是多少、频率如何。local-stats分支正是为此而生它允许开发者在自己的电脑上运行一个本地 statsd 服务器并让模拟器/仿真器中的客户端把统计输出定向到该服务器所有指标会实时打印在运行 statsd 的终端窗口里。需要特别说明的是该分支方案面向模拟器/仿真器场景statsd 服务器运行在开发机的本地网络上物理真机若不额外配置网络隧道network tunneling无法直接访问开发机上的服务器因此该调试方式在物理设备上默认不可用。工作方式与网络拓扑Local Stats 的整体数据链路可以概括为Envoy Mobile 客户端模拟器/仿真器内 │ 按统计刷新周期发射指标 ▼ 本地 statsd 服务器运行在开发机Node.js 进程 │ backends 处理 ▼ 开发机终端窗口实时打印每条统计客户端侧local-stats分支中的配置模板已经把统计 sink 指向本地 statsd 服务器服务器侧statsd 默认监听 UDP 8125 端口该端口也是其事实上的标准默认端口通过 backends 把收到的指标输出到控制台展示侧所有统计以文本行形式出现在运行 statsd 的终端中无需额外搭建面板。配置说明把统计输出指向本地 statsdlocal-stats分支中的配置模板对应原 envoy-mobile 仓库的library/common/config_template.cc已经预先更新为使用本地 statsd 服务器因此拿到该分支后无需再手工改 sink 类型。唯一需要按平台调整的是服务器地址在 iOS 模拟器上模拟器与宿主机共享网络栈配置模板中的默认静态地址即可直接使用在 Android 模拟器上模拟器内的网络是隔离的访问宿主机需要使用 Android 模拟器网络约定中的特殊别名10.0.2.2它映射到宿主机的 loopback 接口。因此文档明确要求使用 Android 测试时把配置模板中的静态地址原文档对应第 203 行附近的服务器地址配置改为10.0.2.2具体可参照 Android 官方Set up Android Emulator networking说明。此外有一个关键约束客户端配置中的端口必须与 statsd 服务器的监听端口一致。原文档中的config_template.cc与示例config.js均以8125为准。从 config_template.cc 到当前仓库的对应实现需要指出的是config_template.cc是 envoy-mobile 仓库local-stats分支中的文件。在当前 Envoy 仓库的mobile/子目录中bootstrap 配置的构建逻辑已演进到由 C 的EngineBuilder负责其核心代码位于 engine_builder.cc当enableStatsCollection开启时会通过stats_matcher的 inclusion list 精确挑选需要收集的统计项例如cluster.stats.upstream_rq_、cluster.base.upstream_cx_等前缀以及pulse.前缀并关闭use_all_default_tags关闭收集时则直接reject_all(true)。可见统计收集是一个白名单式的受控过程本地调试时观测到的正是这批被纳入收集范围的指标。操作步骤步骤一构建目标产物按照 构建文档 中的要求构建所需的 dist 目标。构建前需要保证系统满足 Envoy 的基础构建环境并使用仓库指定的 Bazel 版本建议通过 bazelisk 自动管理Android 端 SDK/NDK 由 Bazel 的 hermetic toolchain 自动拉取iOS 端需要 Xcode 14.1 及以上、iOS 13.0 及以上。以 Hello World 示例运行说明 为例需要先构建对应的产物Android AAR 或 iOS framework随后可运行如下目标# AndroidJava 示例 bazel mobile-install //examples/java/hello_world:hello_envoy --fat_apk_cpuarch1,arch2 # AndroidKotlin 示例 bazel mobile-install //examples/kotlin/hello_world:hello_envoy_kt --fat_apk_cpuarch1,arch2 # iOSObjective-C 示例 bazel run //examples/objective-c/hello_world:app --configios # iOSSwift 示例 bazel run //examples/swift/hello_world:app --configios其中arch1,arch2按目标模拟器/真机架构替换如x86,arm64或x86_64等。步骤二在本地启动 statsdstatsd 是一个基于 Node.js 的统计采集守护进程。克隆 statsd 项目后在其仓库根目录执行node stats.js config.js一个可用的示例config.js如下注意端口必须与配置模板中的端口一致{ port: 8125 , backends: [ ./backends/console ] , servers: [{server: ./servers/tcp, debug: true}] , debug: true }各字段作用port: 8125statsd 监听 UDP 指标的端口必须与客户端配置模板中指向的端口保持一致backends: [./backends/console]选择控制台 backend收到的指标会直接打印到终端是最适合本地调试的输出方式servers: [{server: ./servers/tcp, debug: true}]额外启用 TCP server 并打开其调试日志statsd 默认通过 UDP 接收指标此配置补充了 TCP 通道debug: true开启全局调试模式打印更详细的接收与处理信息。步骤三运行示例应用构建完成后运行 Hello World 示例Android 使用bazel mobile-install安装到已启动的模拟器iOS 使用bazel run ... --configios启动模拟器应用。确保模拟器中的应用能够访问到宿主机上运行 statsd 的端口——Android 侧即对应前述10.0.2.2地址配置。步骤四在终端观察统计输出启动应用并产生流量后统计会陆续出现在运行 statsd 的那个终端窗口中。每条指标按指标名:值|类型的 statsd 文本协议形式输出例如计数器、计时器、计量值等你可以在不依赖任何远端面板的情况下直接核对客户端发起的统计内容与数值是否符合预期。底层原理Envoy 的 statsd Sink 与统计收集链路statsd sink 的两种传输模式Envoy 对 statsd 的支持由envoy.statsd扩展提供工厂实现位于 source/extensions/stat_sinks/statsd/config.cc。该工厂在创建 sink 时根据配置的statsd_specifier分派为两种模式address静态地址模式调用Network::Address::resolveProtoAddress解析出目标地址后构造UdpStatsdSink通过 UDP 数据报把统计发往指定主机端口——这正是 Local Stats 方案使用的模式tcp_cluster_name集群模式构造TcpStatsdSink经由指定 upstream cluster 以 TCP 方式发送。两种 sink 的实现细节可参见 source/extensions/stat_sinks/common/statsd/statsd.hUdpStatsdSink基于线程本地ThreadLocal槽位与 writer 完成数据报发送TcpStatsdSink则使用 16KiB 中间缓冲批量 flush并分别提供flushCounter、flushGauge等逐指标序列化方法。两种 sink 都支持prefix参数可为所有刷出的指标统一加前缀。统计收集开关与 stats matcher从 engine_builder.cc 的实现可以看出Envoy Mobile 的统计收集是可开关、可裁剪的enableStatsCollection()默认开启声明见 engine_builder.h决定是否向 bootstrap 注入 stats matcher开启时通过 inclusion list 放行特定前缀/精确名称如cluster.stats.upstream_rq_、pulse.、dns_cache等与若干正则模式同时把use_all_default_tags置为false关闭时则以reject_all(true)拒绝全部统计。这意味着本地用 statsd 观测到的指标集合正是该 inclusion list 覆盖范围内的统计理解这个白名单机制有助于解释为什么某些统计看不到。Pulse 指标类型与上报客户端侧最终送入统计通道的数据来自 Pulse 库mobile/library/common/stats/。PulseClient支持以点号.分隔的元素串作为指标标识如Element(foo), Element(bar)对应foo.bar并支持创建期与上报期两阶段附加自定义标签。结合本地 statsd 观测你可以在真实流量中验证这些自定义标签是否随指标正确发射。注意事项与常见问题物理设备不可用statsd 服务器位于开发机本地网络物理真机必须配置网络隧道才能访问默认情况下请使用模拟器/仿真器调试Android 模拟器地址务必把服务器地址改为10.0.2.2否则客户端无法到达宿主机上的 statsd端口一致性config.js中的port必须与客户端配置模板中的端口一致示例均为8125否则指标会被丢弃构建环境本地构建需要先完成 构建文档 中的环境准备同时该方案基于local-stats分支使用前请确保当前工作分支包含对应的配置模板改动统计白名单观测到的指标受 engine_builder.cc 中 stats matcher 白名单约束若某指标未出现可先核对是否在 inclusion list 范围内。通过以上方案开发者可以在不搭建任何远程监控设施的前提下把 Envoy Mobile 的客户端统计完整、实时地呈现在本地终端中为指标埋点验证、统计链路排障和性能调优提供最直接的反馈闭环。【免费下载链接】envoyCloud-native high-performance edge/middle/service proxy项目地址: https://gitcode.com/GitHub_Trending/en/envoy创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Envoy Mobile 本地统计观测指南：Local Stats 分支与 statsd 调试实战
Envoy Mobile 本地统计观测指南Local Stats 分支与 statsd 调试实战【免费下载链接】envoyCloud-native high-performance edge/middle/service proxy项目地址: https://gitcode.com/GitHub_Trending/en/envoy本指南围绕 Envoy Mobile 的 Local Stats 调试方案展开通过local-stats分支在开发机本地启动一个 statsd 服务器让运行于 Android/iOS 模拟器中的客户端把统计指标实时发送过来从而在开发终端中直接观察每一次指标发射。读完本文你将掌握该方案的网络拓扑、配置要点含 Android 模拟器的10.0.2.2特殊地址、完整操作步骤以及底层 Envoy statsd Sink 与统计收集机制的源码级原理可直接用于日常开发中的统计指标排障。背景为什么要本地观测统计指标Envoy Mobile 内置了一套基于 Pulse 的客户端统计库用于捕获应用侧的时序指标。根据 PulseStatsAPI 文档当前支持的指标类型包括Counter、Gauge、Timer和Distribution四种且每种指标都支持在创建与上报两个阶段附加自定义标签tags。这些指标最终由底层 Envoy 引擎汇总并周期性地刷出flush。在生产或预发环境中统计指标通常被送往远程的 metrics 后端但在本地开发阶段开发者往往需要快速、直观地确认客户端到底发射了哪些统计、值是多少、频率如何。local-stats分支正是为此而生它允许开发者在自己的电脑上运行一个本地 statsd 服务器并让模拟器/仿真器中的客户端把统计输出定向到该服务器所有指标会实时打印在运行 statsd 的终端窗口里。需要特别说明的是该分支方案面向模拟器/仿真器场景statsd 服务器运行在开发机的本地网络上物理真机若不额外配置网络隧道network tunneling无法直接访问开发机上的服务器因此该调试方式在物理设备上默认不可用。工作方式与网络拓扑Local Stats 的整体数据链路可以概括为Envoy Mobile 客户端模拟器/仿真器内 │ 按统计刷新周期发射指标 ▼ 本地 statsd 服务器运行在开发机Node.js 进程 │ backends 处理 ▼ 开发机终端窗口实时打印每条统计客户端侧local-stats分支中的配置模板已经把统计 sink 指向本地 statsd 服务器服务器侧statsd 默认监听 UDP 8125 端口该端口也是其事实上的标准默认端口通过 backends 把收到的指标输出到控制台展示侧所有统计以文本行形式出现在运行 statsd 的终端中无需额外搭建面板。配置说明把统计输出指向本地 statsdlocal-stats分支中的配置模板对应原 envoy-mobile 仓库的library/common/config_template.cc已经预先更新为使用本地 statsd 服务器因此拿到该分支后无需再手工改 sink 类型。唯一需要按平台调整的是服务器地址在 iOS 模拟器上模拟器与宿主机共享网络栈配置模板中的默认静态地址即可直接使用在 Android 模拟器上模拟器内的网络是隔离的访问宿主机需要使用 Android 模拟器网络约定中的特殊别名10.0.2.2它映射到宿主机的 loopback 接口。因此文档明确要求使用 Android 测试时把配置模板中的静态地址原文档对应第 203 行附近的服务器地址配置改为10.0.2.2具体可参照 Android 官方Set up Android Emulator networking说明。此外有一个关键约束客户端配置中的端口必须与 statsd 服务器的监听端口一致。原文档中的config_template.cc与示例config.js均以8125为准。从 config_template.cc 到当前仓库的对应实现需要指出的是config_template.cc是 envoy-mobile 仓库local-stats分支中的文件。在当前 Envoy 仓库的mobile/子目录中bootstrap 配置的构建逻辑已演进到由 C 的EngineBuilder负责其核心代码位于 engine_builder.cc当enableStatsCollection开启时会通过stats_matcher的 inclusion list 精确挑选需要收集的统计项例如cluster.stats.upstream_rq_、cluster.base.upstream_cx_等前缀以及pulse.前缀并关闭use_all_default_tags关闭收集时则直接reject_all(true)。可见统计收集是一个白名单式的受控过程本地调试时观测到的正是这批被纳入收集范围的指标。操作步骤步骤一构建目标产物按照 构建文档 中的要求构建所需的 dist 目标。构建前需要保证系统满足 Envoy 的基础构建环境并使用仓库指定的 Bazel 版本建议通过 bazelisk 自动管理Android 端 SDK/NDK 由 Bazel 的 hermetic toolchain 自动拉取iOS 端需要 Xcode 14.1 及以上、iOS 13.0 及以上。以 Hello World 示例运行说明 为例需要先构建对应的产物Android AAR 或 iOS framework随后可运行如下目标# AndroidJava 示例 bazel mobile-install //examples/java/hello_world:hello_envoy --fat_apk_cpuarch1,arch2 # AndroidKotlin 示例 bazel mobile-install //examples/kotlin/hello_world:hello_envoy_kt --fat_apk_cpuarch1,arch2 # iOSObjective-C 示例 bazel run //examples/objective-c/hello_world:app --configios # iOSSwift 示例 bazel run //examples/swift/hello_world:app --configios其中arch1,arch2按目标模拟器/真机架构替换如x86,arm64或x86_64等。步骤二在本地启动 statsdstatsd 是一个基于 Node.js 的统计采集守护进程。克隆 statsd 项目后在其仓库根目录执行node stats.js config.js一个可用的示例config.js如下注意端口必须与配置模板中的端口一致{ port: 8125 , backends: [ ./backends/console ] , servers: [{server: ./servers/tcp, debug: true}] , debug: true }各字段作用port: 8125statsd 监听 UDP 指标的端口必须与客户端配置模板中指向的端口保持一致backends: [./backends/console]选择控制台 backend收到的指标会直接打印到终端是最适合本地调试的输出方式servers: [{server: ./servers/tcp, debug: true}]额外启用 TCP server 并打开其调试日志statsd 默认通过 UDP 接收指标此配置补充了 TCP 通道debug: true开启全局调试模式打印更详细的接收与处理信息。步骤三运行示例应用构建完成后运行 Hello World 示例Android 使用bazel mobile-install安装到已启动的模拟器iOS 使用bazel run ... --configios启动模拟器应用。确保模拟器中的应用能够访问到宿主机上运行 statsd 的端口——Android 侧即对应前述10.0.2.2地址配置。步骤四在终端观察统计输出启动应用并产生流量后统计会陆续出现在运行 statsd 的那个终端窗口中。每条指标按指标名:值|类型的 statsd 文本协议形式输出例如计数器、计时器、计量值等你可以在不依赖任何远端面板的情况下直接核对客户端发起的统计内容与数值是否符合预期。底层原理Envoy 的 statsd Sink 与统计收集链路statsd sink 的两种传输模式Envoy 对 statsd 的支持由envoy.statsd扩展提供工厂实现位于 source/extensions/stat_sinks/statsd/config.cc。该工厂在创建 sink 时根据配置的statsd_specifier分派为两种模式address静态地址模式调用Network::Address::resolveProtoAddress解析出目标地址后构造UdpStatsdSink通过 UDP 数据报把统计发往指定主机端口——这正是 Local Stats 方案使用的模式tcp_cluster_name集群模式构造TcpStatsdSink经由指定 upstream cluster 以 TCP 方式发送。两种 sink 的实现细节可参见 source/extensions/stat_sinks/common/statsd/statsd.hUdpStatsdSink基于线程本地ThreadLocal槽位与 writer 完成数据报发送TcpStatsdSink则使用 16KiB 中间缓冲批量 flush并分别提供flushCounter、flushGauge等逐指标序列化方法。两种 sink 都支持prefix参数可为所有刷出的指标统一加前缀。统计收集开关与 stats matcher从 engine_builder.cc 的实现可以看出Envoy Mobile 的统计收集是可开关、可裁剪的enableStatsCollection()默认开启声明见 engine_builder.h决定是否向 bootstrap 注入 stats matcher开启时通过 inclusion list 放行特定前缀/精确名称如cluster.stats.upstream_rq_、pulse.、dns_cache等与若干正则模式同时把use_all_default_tags置为false关闭时则以reject_all(true)拒绝全部统计。这意味着本地用 statsd 观测到的指标集合正是该 inclusion list 覆盖范围内的统计理解这个白名单机制有助于解释为什么某些统计看不到。Pulse 指标类型与上报客户端侧最终送入统计通道的数据来自 Pulse 库mobile/library/common/stats/。PulseClient支持以点号.分隔的元素串作为指标标识如Element(foo), Element(bar)对应foo.bar并支持创建期与上报期两阶段附加自定义标签。结合本地 statsd 观测你可以在真实流量中验证这些自定义标签是否随指标正确发射。注意事项与常见问题物理设备不可用statsd 服务器位于开发机本地网络物理真机必须配置网络隧道才能访问默认情况下请使用模拟器/仿真器调试Android 模拟器地址务必把服务器地址改为10.0.2.2否则客户端无法到达宿主机上的 statsd端口一致性config.js中的port必须与客户端配置模板中的端口一致示例均为8125否则指标会被丢弃构建环境本地构建需要先完成 构建文档 中的环境准备同时该方案基于local-stats分支使用前请确保当前工作分支包含对应的配置模板改动统计白名单观测到的指标受 engine_builder.cc 中 stats matcher 白名单约束若某指标未出现可先核对是否在 inclusion list 范围内。通过以上方案开发者可以在不搭建任何远程监控设施的前提下把 Envoy Mobile 的客户端统计完整、实时地呈现在本地终端中为指标埋点验证、统计链路排障和性能调优提供最直接的反馈闭环。【免费下载链接】envoyCloud-native high-performance edge/middle/service proxy项目地址: https://gitcode.com/GitHub_Trending/en/envoy创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考