Skip to content

Commit a95e92f

Browse files
wu-shengwu-sheng
authored
Add mini-program monitoring blog (WeChat / Alipay) (#839)
1 parent 028f417 commit a95e92f

2 files changed

Lines changed: 248 additions & 0 deletions

File tree

  • content
    • blog/2026-04-30-mini-program-monitoring-with-skywalking
    • zh/2026-04-30-mini-program-monitoring-with-skywalking

‎content/blog/2026-04-30-mini-program-monitoring-with-skywalking/index.md‎

Lines changed: 124 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,124 @@
1+
---
2+
title: "Monitoring WeChat and Alipay Mini Programs with SkyWalking"
3+
author: "Sheng Wu"
4+
date: 2026-04-30
5+
description: "SkyAPM/mini-program-monitor and SkyWalking OAP together extend SkyWalking's end-user monitoring to WeChat and Alipay Mini Programs. This post focuses on the data path, the cross-platform abstraction, and the OAP-side integration."
6+
tags:
7+
- Mini Program
8+
- WeChat
9+
- Alipay
10+
- OTLP
11+
- End User Monitoring
12+
---
13+
14+
# Monitoring WeChat and Alipay Mini Programs with SkyWalking
15+
16+
Mini programs are a major part of the mobile experience in China, but the open-source observability ecosystem has long focused on web browsers and native apps. SkyWalking already covers browser (client-js), iOS, and the server side; mini programs and Android were the remaining gaps. With [SkyAPM/mini-program-monitor](https://github.com/SkyAPM/mini-program-monitor) joining the SkyWalking ecosystem, the mini-program half of that gap is closed — one SDK supports both WeChat and Alipay, and the matching OAP-side component IDs, MAL rules, and UI templates are merged on `main` and will ship with 10.5.0.
17+
18+
This post is for teams that already run a SkyWalking backend and want to bring their mini programs into the same observability stack. The interesting parts aren't *that* the project exists — they are how the data flows from a mini program to a SkyWalking dashboard, how the two platforms coexist, and what design trade-offs you should know about before rolling this out.
19+
20+
## Data path
21+
22+
The SDK uses two protocols:
23+
24+
- **OTLP HTTP** (error logs, performance metrics, request metrics) → OAP `/v1/logs`, `/v1/metrics`
25+
- **SkyWalking native** (distributed tracing segments, optional) → OAP `/v3/segments`
26+
27+
Why not a single protocol? OTLP already covers logs and metrics, so there's no point reinventing native endpoints for those. But for tracing, OAP's native `SegmentObject` maps more cleanly onto SkyWalking's trace model, and `sw8` header propagation to the backend works without any conversion. So traces go native, everything else goes OTLP, and neither side has to translate.
28+
29+
OTLP defaults to protobuf; JSON is available for debugging. The SDK has zero runtime dependencies.
30+
31+
## Two platforms, two independent Layers and dashboards
32+
33+
Many teams maintain a WeChat mini program and an Alipay mini program against a shared backend. Rather than collapsing them into a single tagged service, the design promotes each platform to its own Layer — `WECHAT_MINI_PROGRAM` and `ALIPAY_MINI_PROGRAM` — with its own dashboard set. The SDK tags every signal with a resource attribute `miniprogram.platform = wechat | alipay` and assigns each platform its own component ID (WeChat = 10002, Alipay = 10003).
34+
35+
On the OAP side, the MAL rule's `filter` routes data into the right Layer at ingest:
36+
37+
```yaml
38+
metricPrefix: meter_wechat_mp
39+
filter: "{ tags -> tags.miniprogram_platform == 'wechat' }"
40+
```
41+
42+
The Alipay rule mirrors this with `'alipay'`. The two rules are mutually exclusive — no double counting — and produce distinct metric prefixes (`meter_wechat_mp_*` vs `meter_alipay_mp_*`) that feed each Layer's dashboards. Even when both platforms use the same `service.name` (e.g. `mini-program-demo`), the UI exposes two completely separate entry points.
43+
44+
## Asymmetric metric semantics
45+
46+
This is the design choice I want to highlight. WeChat's base library exposes `PerformanceObserver`, which gives you renderer-authoritative timings: app launch, first render, route navigation, script execution, sub-package load — all real measurements. Alipay's base library doesn't offer an equivalent, so the SDK falls back to lifecycle hooks: the `App.onLaunch → App.onShow` delta is used as an approximation of launch time, and renderer-level timings simply aren't available.
47+
48+
So the two MAL rule sets are deliberately not the same:
49+
50+
- **WeChat**: `app_launch_duration`, `first_render_duration`, `route_duration`, `script_duration`, `package_load_duration`, `request_duration_percentile`, `request_cpm`
51+
- **Alipay**: `app_launch_duration`, `first_render_duration`, `request_duration_percentile`, `request_cpm`
52+
53+
The Alipay `app_launch_duration` is a lifecycle approximation and is not directly comparable to WeChat's renderer timing — the dashboard tooltip says so explicitly. Putting the two numbers side by side is comparing two different measurement definitions.
54+
55+
## What the SDK does
56+
57+
Four signals:
58+
59+
- **Errors** — JS exceptions, unhandled promise rejections, and `pageNotFound` go out as OTLP logs, following the OTel `exception.*` semantic conventions (`exception.type`, `exception.stacktrace`). Anything downstream that speaks OTLP — SkyWalking, OTel Collector, Grafana — recognizes them.
60+
- **Performance** — the metrics listed above. OTLP gauge.
61+
- **Requests** — `wx.request` / `my.request` / `downloadFile` / `uploadFile` are reported as OTLP delta histograms, one batch per `flushInterval` (default 5s). The `le` bucket labels are already in milliseconds, and the MAL rule explicitly declares `MILLISECONDS` to disable the default SECONDS→MS rescale. Failed requests (4xx / 5xx / timeout) additionally emit an error log so you can pivot from a dashboard to a concrete failure.
62+
- **Tracing (opt-in)** — when enabled, outbound requests get `sw8` header injection, and the resulting segments stitch together with backend traces into one end-to-end view. Trace data goes out as SkyWalking `SegmentObject`, not OTLP traces.
63+
64+
Two reliability and cardinality details worth calling out:
65+
66+
**Persisting events on app hide.** Mini programs get killed by the framework after some time in background, and weak networks make in-flight events easy to lose. The SDK writes unsent events to `wx.setStorage` / `my.setStorage` on `onAppHide` and restores them on the next launch.
67+
68+
**Avoiding cardinality explosions.** Set `serviceInstance` to the app version (e.g. `1.4.2`), not a device ID — at a million DAU the device-ID dimension blows up the OAP instance index. For request paths, the SDK exposes `urlGroupRules` regex patterns to fold parameterized URLs like `/api/user/12345` into `/api/user/{id}` so the endpoint dimension doesn't blow up either.
69+
70+
## What OAP needs
71+
72+
If you're on `main` or a release ≥ 10.5.0, the following are already shipped:
73+
74+
- `config/component-libraries.yml` registers `WeChat-MiniProgram: 10002` and `AliPay-MiniProgram: 10003`
75+
- `config/otel-rules/miniprogram/` holds four MAL rules — service-scoped and instance-scoped for each platform
76+
- `config/ui-initialized-templates/wechat_mini_program/` and `alipay_mini_program/` carry root / service / instance / endpoint dashboards
77+
- `config/ui-initialized-templates/menu.yaml` registers both layers under the Mobile menu group
78+
79+
The only thing left is enabling the OTel receiver and giving the SDK an OTLP HTTP port it can reach. SkyWalking OAP binds its OTLP HTTP handler onto the receiver-sharing-server port, and that port defaults to `0` — meaning it's folded into the core REST port (12800). If you want the SDK to use the standard OTLP HTTP port 4318, set the sharing port to 4318:
80+
81+
```bash
82+
docker run -d --name sw-oap \
83+
-p 11800:11800 -p 12800:12800 -p 4318:4318 \
84+
-e SW_STORAGE=banyandb \
85+
-e SW_STORAGE_BANYANDB_TARGETS=banyandb:17912 \
86+
-e SW_OTEL_RECEIVER=default \
87+
-e SW_RECEIVER_SHARING_REST_PORT=4318 \
88+
apache/skywalking-oap-server:latest
89+
```
90+
91+
All receivers (OTLP, native segment, browser perf, log report) move to 4318 together, while GraphQL stays on 12800 for the UI.
92+
93+
Minimal SDK config:
94+
95+
```js
96+
import MiniProgramMonitor from 'mini-program-monitor';
97+
98+
MiniProgramMonitor.init({
99+
service: 'mini-program-demo',
100+
serviceInstance: '1.4.2', // Recommended: app version
101+
collector: 'http://your-oap:4318',
102+
enable: {
103+
error: true,
104+
perf: true,
105+
request: true,
106+
tracing: false, // Off by default; enable as needed
107+
},
108+
});
109+
```
110+
111+
WeChat and Alipay use the same config — the SDK detects the platform at runtime and tags the data accordingly.
112+
113+
## Compatibility
114+
115+
- WeChat base library ≥ 2.11
116+
- Alipay base library ≥ 2.0
117+
- Apache SkyWalking OAP `main` or ≥ 10.5.0, with the OTLP HTTP receiver enabled
118+
- Any other OTLP-compatible backend (OpenTelemetry Collector, Grafana, etc.) also works, but you won't get the SkyWalking-specific cross-platform dashboards
119+
120+
## What's next
121+
122+
To get involved, head over to [SkyAPM/mini-program-monitor](https://github.com/SkyAPM/mini-program-monitor) and open an issue or PR. The repo also ships a `make preview` target that boots OAP, the UI, and both platform simulators locally — handy if you want to play with it end-to-end.
123+
124+
Android end-user experience monitoring is still a gap in the SkyWalking ecosystem; contributors interested in closing that one are very welcome.

‎content/zh/2026-04-30-mini-program-monitoring-with-skywalking/index.md‎

Lines changed: 124 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,124 @@
1+
---
2+
title: "用 SkyWalking 监控微信和支付宝小程序"
3+
author: "吴晟"
4+
date: 2026-04-30
5+
description: "SkyAPM/mini-program-monitor 与 SkyWalking OAP 配合，把微信和支付宝小程序纳入 SkyWalking 的端用户体验监控。本文聚焦数据通路、双平台抽象与 OAP 端集成。"
6+
tags:
7+
- Mini Program
8+
- WeChat
9+
- Alipay
10+
- OTLP
11+
- End User Monitoring
12+
---
13+
14+
# 用 SkyWalking 监控微信和支付宝小程序
15+
16+
小程序是国内移动端体验里绕不过去的一块，但开源监控生态长期偏向 Web 浏览器和原生 App。SkyWalking 自身已经覆盖了浏览器（client-js）、iOS、服务端，缺口主要在小程序和 Android。[SkyAPM/mini-program-monitor](https://github.com/SkyAPM/mini-program-monitor) 加入 SkyWalking 生态后，把这块缺口的小程序部分补上了 —— 一份 SDK 同时支持微信和支付宝，OAP 端的 component、MAL 规则、UI 模板已经合进 main 分支，会随 10.5.0 一起发布。
17+
18+
这篇博客面向已经跑着 SkyWalking 后端、希望把小程序也接进来的团队。重点不是"项目存在"这件事，而是数据从小程序到 SkyWalking dashboard 走的是哪条路、双平台是怎么共存的、以及上线之前需要知道哪些设计取舍。
19+
20+
## 数据通路
21+
22+
SDK 走两条腿：
23+
24+
- **OTLP HTTP**（错误日志、性能指标、请求指标）→ OAP 的 `/v1/logs`、`/v1/metrics`
25+
- **SkyWalking 原生协议**（链路追踪 segment，可选）→ OAP 的 `/v3/segments`
26+
27+
为什么不是单协议？OTLP 已经覆盖了 logs 和 metrics 两类信号，没必要再造一份原生 endpoint；但分布式追踪上 OAP 的原生 `SegmentObject` 比 OTLP traces 表达力更贴 SkyWalking 自己的 trace 模型，且与服务端通过 `sw8` header 透传时无需任何转换。所以追踪走原生，其它走 OTLP，两边都不绕路。
28+
29+
OTLP 默认用 protobuf，调试时可切成 JSON。SDK 没有任何运行时依赖。
30+
31+
## 双平台对应两个独立的 Layer 与监控面板
32+
33+
很多团队会同时维护一个微信小程序和一个支付宝小程序，业务逻辑共享一个后端。这套设计没有把它们塞进同一个 service 用 tag 区分，而是直接做成两个独立的 Layer：`WECHAT_MINI_PROGRAM` 和 `ALIPAY_MINI_PROGRAM`，对应两套独立的监控面板。SDK 在每个信号上打 resource 属性 `miniprogram.platform = wechat | alipay`，并给两端各分配独立的 component ID（微信 10002、支付宝 10003）。
34+
35+
OAP 这一头是用 MAL 规则的 `filter` 把数据在 ingest 阶段就分流到对应 Layer 的：
36+
37+
```yaml
38+
metricPrefix: meter_wechat_mp
39+
filter: "{ tags -> tags.miniprogram_platform == 'wechat' }"
40+
```
41+
42+
支付宝那份规则同理过滤 `alipay`。两份规则互斥，不会重复计数；输出的 metric 前缀也不一样（`meter_wechat_mp_*` vs `meter_alipay_mp_*`），各自落在对应 Layer 的 dashboard 上。即使两端用同一个 `service.name`（比如都叫 `mini-program-demo`），UI 里也是两套完全独立的入口。
43+
44+
## 不对等的指标语义
45+
46+
这是这套设计里我特别想强调的一处诚实选择。微信的基础库提供 `PerformanceObserver`，能拿到来自渲染层的权威时序：app launch、first render、route navigation、script execution、sub-package load 都是真实指标。支付宝的基础库不提供等价 API，SDK 只能用生命周期回退做近似：`App.onLaunch → App.onShow` 的 delta 当作启动时间，渲染相关的拿不到。
47+
48+
所以两份 OAP 规则里的 metric 集合不对等：
49+
50+
- 微信：`app_launch_duration`、`first_render_duration`、`route_duration`、`script_duration`、`package_load_duration`、`request_duration_percentile`、`request_cpm`
51+
- 支付宝：`app_launch_duration`、`first_render_duration`、`request_duration_percentile`、`request_cpm`
52+
53+
支付宝侧的 `app_launch_duration` 是生命周期近似值，与微信的渲染层数值不可直接对比，这一点在 dashboard 的字段提示里也写明了。把两个数字放一起做横评等于在比较两种不同测量定义。
54+
55+
## SDK 端做了什么
56+
57+
四类信号：
58+
59+
- **错误**：JS 异常 / unhandled promise rejection / pageNotFound 走 OTLP logs，按 OTel `exception.*` 语义约定（`exception.type`、`exception.stacktrace`），下游不光 SkyWalking，OTel Collector / Grafana 也都认。
60+
- **性能**：上面那张表里那些。OTLP gauge。
61+
- **请求**：`wx.request` / `my.request` / `downloadFile` / `uploadFile` 都走 OTLP delta histogram，每个 flush 间隔（默认 5s）发一次增量。`le` 桶标签直接用 ms，OAP MAL 里显式声明 `MILLISECONDS` 阻止默认的 SECONDS→MS 缩放。失败请求（4xx/5xx/超时）额外发一条错误日志，方便从 dashboard 跳到具体错误。
62+
- **追踪（可选）**：开启后给出站请求注入 `sw8` 头，落到 OAP 后能与服务端 trace 拼成一条完整链路。trace 段以 SkyWalking `SegmentObject` 形式发出，不走 OTLP traces。
63+
64+
可靠性和基数控制的两个细节值得一提：
65+
66+
**App hide 时落本地存储**。小程序后台一段时间会被框架杀掉，弱网时也容易丢包。SDK 在 `onAppHide` 时把未发送的事件写到 `wx.setStorage` / `my.setStorage`，下次启动恢复并继续上报。
67+
68+
**反基数膨胀**。强烈建议把 `serviceInstance` 设成应用版本号（如 `1.4.2`），不要用设备 ID —— 小程序日活百万级时设备 ID 维度直接把 OAP 的 instance 索引打爆。请求路径方面 SDK 提供 `urlGroupRules` 正则把 `/api/user/12345` 这类参数化路径归并到 `/api/user/{id}`，避免 endpoint 维度也膨胀。
69+
70+
## OAP 端要做什么
71+
72+
如果你用的是 main 分支或者 10.5.0 之后的发布版，下面这些已经内置：
73+
74+
- `config/component-libraries.yml`：注册了 `WeChat-MiniProgram: 10002` 和 `AliPay-MiniProgram: 10003`
75+
- `config/otel-rules/miniprogram/`：四份 MAL 规则，按 service / instance 维度分别定义
76+
- `config/ui-initialized-templates/wechat_mini_program/` 和 `alipay_mini_program/`：root / service / instance / endpoint 四张 dashboard
77+
- `config/ui-initialized-templates/menu.yaml`：把两个 layer 注册到 Mobile 菜单组下
78+
79+
唯一需要做的就是确认 OTel receiver 启用、给 OTLP HTTP 一个 SDK 能直连的端口。SkyWalking OAP 的 OTLP HTTP handler 默认绑在 receiver-sharing-server 的端口上，而该端口默认值是 0（即复用 core REST 端口 12800）。如果想让 SDK 用标准 OTLP HTTP 端口 4318，把 sharing 端口设到 4318：
80+
81+
```bash
82+
docker run -d --name sw-oap \
83+
-p 11800:11800 -p 12800:12800 -p 4318:4318 \
84+
-e SW_STORAGE=banyandb \
85+
-e SW_STORAGE_BANYANDB_TARGETS=banyandb:17912 \
86+
-e SW_OTEL_RECEIVER=default \
87+
-e SW_RECEIVER_SHARING_REST_PORT=4318 \
88+
apache/skywalking-oap-server:latest
89+
```
90+
91+
这样所有 receiver（OTLP + native segment + browser perf + log report）一起搬到 4318，GraphQL 仍在 12800 给 UI 用。
92+
93+
SDK 端配置最小集：
94+
95+
```js
96+
import MiniProgramMonitor from 'mini-program-monitor';
97+
98+
MiniProgramMonitor.init({
99+
service: 'mini-program-demo',
100+
serviceInstance: '1.4.2', // 推荐：应用版本号
101+
collector: 'http://your-oap:4318',
102+
enable: {
103+
error: true,
104+
perf: true,
105+
request: true,
106+
tracing: false, // 默认关，按需开
107+
},
108+
});
109+
```
110+
111+
微信和支付宝两端配置一模一样，平台标签由 SDK 在运行时自动判定。
112+
113+
## 兼容性
114+
115+
- 微信基础库 ≥ 2.11
116+
- 支付宝基础库 ≥ 2.0
117+
- Apache SkyWalking OAP main 分支或 ≥ 10.5.0；OTLP HTTP receiver 启用即可
118+
- 也可对接任意 OTLP 后端（OpenTelemetry Collector、Grafana 等），但那条路上拿不到 SkyWalking 专属的双平台 dashboard
119+
120+
## 后续
121+
122+
参与方式直接去 [SkyAPM/mini-program-monitor](https://github.com/SkyAPM/mini-program-monitor) 提 issue / PR。仓库里有一个 `make preview` 一键拉起 OAP、UI、两端模拟器的本地 demo 环境，想看效果可以直接跑。
123+
124+
Android 端的端用户体验监控目前还是 SkyWalking 生态的空白，欢迎对这块感兴趣的同学一起补齐。

0 commit comments

Comments
 (0)