You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@skywalking.apache.org by wu...@apache.org on 2026/04/20 11:43:58 UTC
(skywalking) 04/05: SWIP-12 Stage 4: user-facing docs, menu entry, changelog
This is an automated email from the ASF dual-hosted git repository.
wu-sheng pushed a commit to branch feature/swip12-miniprogram-impl
in repository https://gitbox.apache.org/repos/asf/skywalking.git
commit 79616170f6e2684455a4764ccdb9efde3884e8ec
Author: Wu Sheng <wu...@foxmail.com>
AuthorDate: Mon Apr 20 19:30:57 2026 +0800
SWIP-12 Stage 4: user-facing docs, menu entry, changelog
- docs/en/setup/backend/backend-wechat-mini-program-monitoring.md and
backend-alipay-mini-program-monitoring.md — prerequisites, OAP
configuration (when defaults are overridden), SDK setup snippet,
metric catalog per platform, error-log categories, entity model,
SDK version compatibility (v0.2.x / v0.3.x / v0.4.0+), dashboard
overview, and platform-specific limitations.
- docs/menu.yml — two new entries under Mobile Monitoring pointing
at the new setup guides.
- docs/en/changes/changes.md — entry under OAP Server summarizing the
layer / componentId / listener mapping / rules work, and an entry
under Documentation for the two new guides.
docs/en/swip/readme.md already lists SWIP-12 under Accepted (from the
earlier design PR) and docs/en/security/README.md's Client-Side
Monitoring section already covers mini-programs — both untouched.
---
docs/en/changes/changes.md | 2 +
.../backend-alipay-mini-program-monitoring.md | 167 ++++++++++++++++++++
.../backend-wechat-mini-program-monitoring.md | 169 +++++++++++++++++++++
docs/menu.yml | 4 +
4 files changed, 342 insertions(+)
diff --git a/docs/en/changes/changes.md b/docs/en/changes/changes.md
index 44d8371be5..592540ee98 100644
--- a/docs/en/changes/changes.md
+++ b/docs/en/changes/changes.md
@@ -35,6 +35,7 @@
* Add iOS/iPadOS app monitoring via OpenTelemetry Swift SDK (SWIP-11). Includes the `IOS` layer, `IOSHTTPSpanListener` for outbound HTTP client metrics (supports OTel Swift `.old`/`.stable`/`.httpDup` semantic-convention modes via stable-then-legacy attribute fallback), `IOSMetricKitSpanListener` for daily MetricKit metrics (exit counts split by foreground/background, app-launch / hang-time percentile histograms with finite 30 s overflow ceiling), LAL rules for crash/hang diagnostics, Mo [...]
* Fix LAL `layer: auto` mode dropping logs after extractor set the layer. Codegen now propagates `layer "..."` assignments to `LogMetadata.layer` so `FilterSpec.doSink()` sees the script-decided layer.
* Fix MetricKit histogram percentile metrics being reported at 1000× their true value — the listener now marks its `SampleFamily` with `defaultHistogramBucketUnit(MILLISECONDS)` so MAL's default SECONDS→MS rescale of `le` labels is not applied.
+* Add WeChat and Alipay Mini Program monitoring via the SkyAPM mini-program-monitor SDK (SWIP-12). Two new layers (`WECHAT_MINI_PROGRAM`, `ALIPAY_MINI_PROGRAM`); two new JavaScript componentIds (`WeChat-MiniProgram: 10002`, `AliPay-MiniProgram: 10003`); componentId-driven layer mapping in `CommonAnalysisListener` so native trace segments land on the correct layer with no new SPI; MAL rules per platform × scope under `otel-rules/miniprogram/` including chained `.endpoint(...)` per-page va [...]
#### UI
* Add mobile menu icon and i18n labels for the iOS layer.
@@ -43,6 +44,7 @@
#### Documentation
* Update LAL documentation with `sourceAttribute()` function and `layer: auto` mode.
* Add iOS app monitoring setup documentation.
+* Add WeChat / Alipay Mini Program monitoring setup documentation, plus a client-side-monitoring section in the security guide covering public-internet ingress (OTLP + `/v3/segments`) for mobile / browser / mini-program SDKs.
All issues and pull requests are [here](https://github.com/apache/skywalking/issues?q=milestone:10.5.0)
diff --git a/docs/en/setup/backend/backend-alipay-mini-program-monitoring.md b/docs/en/setup/backend/backend-alipay-mini-program-monitoring.md
new file mode 100644
index 0000000000..52fffcc731
--- /dev/null
+++ b/docs/en/setup/backend/backend-alipay-mini-program-monitoring.md
@@ -0,0 +1,167 @@
+# Alipay Mini Program Monitoring
+
+SkyWalking supports Alipay Mini Program monitoring via the
+[SkyAPM mini-program-monitor SDK](https://github.com/SkyAPM/mini-program-monitor) — the same
+SDK used for [WeChat](backend-wechat-mini-program-monitoring.md). The SDK detects the Alipay
+runtime and adapts the platform tag accordingly; the OAP-side rules then route traffic to the
+Alipay layer.
+
+Three data streams are captured:
+
+1. **OTLP logs** — JS errors, promise rejections, and AJAX failures (no `pageNotFound` — the
+ Alipay base library does not expose `my.onPageNotFound`)
+2. **OTLP metrics** — app launch and first render durations (lifecycle-based approximations
+ on Alipay, not renderer-authoritative) and a delta histogram of outbound request durations
+3. **SkyWalking native trace segments** (opt-in) — one `SegmentObject` per sampled outbound
+ `my.request`, with an `sw8` header injected on the wire so downstream backend services
+ join the same trace
+
+No new receiver is required — the SDK speaks OTLP/HTTP and the SkyWalking native v3 protocol.
+
+## Prerequisites
+
+- mini-program-monitor **≥ v0.4.0** is the recommended baseline. v0.3.x still works but with
+ the legacy per-device `serviceInstance` behavior (see [Compatibility](#compatibility)).
+- SkyWalking OAP with the changes from SWIP-12 — OTLP HTTP receiver enabled (default on core
+ REST port 12800), the two new component ids registered in `component-libraries.yml`, and the
+ four MAL rules under `otel-rules/miniprogram/` enabled.
+
+## OAP Configuration
+
+Append `miniprogram/*` to `enabledOtelMetricsRules` and `miniprogram` to `lalFiles` and
+`malFiles` in `application.yml` (preserve the existing defaults — don't replace them). These
+entries are included in the shipped defaults, so this section is only relevant if you have
+overridden the defaults via `SW_OTEL_RECEIVER_ENABLED_OTEL_METRICS_RULES`, `SW_LOG_LAL_FILES`,
+or `SW_LOG_MAL_FILES`:
+
+```yaml
+receiver-otel:
+ selector: ${SW_OTEL_RECEIVER:default}
+ default:
+ enabledHandlers: ${SW_OTEL_RECEIVER_ENABLED_HANDLERS:"otlp-traces,otlp-metrics,otlp-logs"}
+ enabledOtelMetricsRules: ${SW_OTEL_RECEIVER_ENABLED_OTEL_METRICS_RULES:"<existing defaults>,miniprogram/*"}
+
+log-analyzer:
+ selector: ${SW_LOG_ANALYZER:default}
+ default:
+ lalFiles: ${SW_LOG_LAL_FILES:"<existing defaults>,miniprogram"}
+ malFiles: ${SW_LOG_MAL_FILES:"<existing defaults>,miniprogram"}
+```
+
+Native trace segments (`/v3/segments`) need no additional config — the existing trace receiver
+handles them and assigns the `ALIPAY_MINI_PROGRAM` layer automatically based on the SDK's
+`AliPay-MiniProgram` componentId (10003).
+
+## Mini Program Setup
+
+```js
+// app.js
+const { init } = require('mini-program-monitor');
+App({
+ onLaunch() {
+ init({
+ service: 'my-mini-program',
+ serviceVersion: 'v1.2.0',
+ serviceInstance: 'v1.2.0', // version-scoped, recommended pattern
+ collector: 'https://<oap-or-collector-host>',
+ platform: 'alipay', // optional — auto-detected from runtime
+ enable: { tracing: true }, // opt-in: SkyWalking native segments
+ });
+ },
+});
+```
+
+> **Security:** mini-program SDKs send telemetry from end-user devices over the public
+> internet. See the [Security Notice](../../security/README.md) for deployment guidelines.
+
+## Metrics
+
+All MAL metrics are prefixed `meter_alipay_mp_*` (service-scope) or
+`meter_alipay_mp_instance_*` (instance-scope). Endpoint-scoped variants surface as
+`meter_alipay_mp_endpoint_*`.
+
+| Metric | Scope | Source |
+|----------------------------------|--------------------------------|-------------------------------------------------------|
+| `app_launch_duration` | service / instance / endpoint | App.onLaunch → App.onShow lifecycle delta (approx) |
+| `first_render_duration` | service / instance / endpoint | Page.onLoad → Page.onReady lifecycle delta (approx) |
+| `request_duration_percentile` | service / instance / endpoint | `miniprogram.request.duration` histogram (P50–P99) |
+| `error_count` | service | LAL-derived counter — log-MAL rule aggregates per exception type |
+
+> **Precision caveat:** on Alipay the perf values come from lifecycle hooks, not the native
+> PerformanceObserver entries WeChat uses (the Alipay base library doesn't expose them).
+> These are approximations of time-to-interactive, not authoritative renderer timings. Do
+> not compare WeChat and Alipay perf values directly.
+
+WeChat-only metrics (`route_duration`, `script_duration`, `package_load_duration`,
+`first_paint.time`) are absent from Alipay. The Alipay dashboard omits the Navigation row
+entirely.
+
+Outbound HTTP metrics come "for free" from the existing `core.oal` rules once the component-id
+mapping assigns the ALIPAY_MINI_PROGRAM layer to segments: `service_cpm`, `service_resp_time`,
+`service_sla`, `service_percentile`, `service_apdex`, `service_instance_cpm`,
+`service_instance_resp_time`, `service_instance_sla`, `endpoint_cpm`, `endpoint_resp_time`,
+`endpoint_sla`, `endpoint_percentile`, plus `ServiceRelation` / `EndpointRelation` topology
+edges to the backend services the mini-program calls.
+
+## Error Logs
+
+The LAL rule `lal/miniprogram.yaml` uses `layer: auto` mode and dispatches on the
+`miniprogram.platform` resource attribute — one rule file produces both the
+`WECHAT_MINI_PROGRAM` and `ALIPAY_MINI_PROGRAM` layers. For each error log, the extractor
+emits a `miniprogram_error_count` counter sample, which the log-MAL rule in
+`log-mal-rules/miniprogram.yaml` aggregates into the per-layer `error_count` metric.
+
+Error categories (`exception.type` tag):
+
+| Category | Source |
+|--------------------|------------------------------------------------------------------|
+| `js` | `my.onError` — unhandled JS errors |
+| `promise` | `my.onUnhandledRejection` — unhandled promise rejections |
+| `ajax` | `my.request` failures (network + non-2xx) |
+
+## Entities
+
+| SkyWalking Entity | Source | Cardinality | Rationale |
+|-------------------|-----------------------------------|-------------------|--------------------------------------------------------|
+| Service | `service.name` | 1 per app | Fleet-wide app health |
+| ServiceInstance | `service.instance.id` (pattern: set to `service.version`) | tens per app | Version regression / rollout monitoring |
+| Endpoint | `miniprogram.page.path` | dozens per app | Which in-app page is slow / error-prone |
+
+Per-device `service.instance.id` is intentionally not used as an aggregation dimension —
+unbounded cardinality means millions of entities on any real user base. The SDK (≥ v0.4.0)
+no longer auto-generates a device id; operators set `serviceInstance` to a version-scoped
+value.
+
+## Compatibility
+
+- **SDK ≤ v0.2.x** emits `componentId = 10001` (ajax-inherited). Its segments resolve to
+ `Layer.GENERAL` and do not benefit from this integration's layer / topology work.
+- **SDK ≤ v0.3.x** auto-generates `service.instance.id = mp-{random}` per session, creating
+ one OAP instance entity per device — usually undesirable. Operators on v0.3.x can avoid this
+ by passing `init({ serviceInstance: serviceVersion })` explicitly.
+- **SDK ≥ v0.4.0** leaves `service.instance.id` unset by default. The three signal pipelines
+ then handle absence differently: native segments produce a literal `-` instance entity; OTLP
+ logs and metrics create no instance entity at all. Per-instance dashboards are meaningful
+ only when the operator sets `serviceInstance`.
+- The recommended pattern (SDK docs + e2e CI) is to set `serviceInstance` to a version-scoped
+ value.
+
+## Dashboards
+
+- **Alipay Mini Program** in the **Mobile** menu group — service list landing page.
+- **Per-service** dashboard — launch / render durations (approx), request latency percentile,
+ outbound traffic (load, avg latency, success rate), error count, plus tabs for Instance,
+ Endpoint, Trace, and Log drill-down.
+- **Per-instance (version)** dashboard — same metric set scoped to a release.
+- **Per-endpoint (page)** dashboard — per-page perf, outbound traffic, request latency
+ percentile.
+
+## Limitations
+
+- Alipay perf metrics are lifecycle-based approximations, not renderer-authoritative.
+- No `pageNotFound` error category — the Alipay base library does not expose
+ `my.onPageNotFound`.
+- WebSocket, memory-warning, and network-status-change signals are not instrumented by the
+ current SDK.
+- Device-level per-user aggregation is not supported by design — `serviceInstance` is intended
+ to be a version-scoped identifier.
diff --git a/docs/en/setup/backend/backend-wechat-mini-program-monitoring.md b/docs/en/setup/backend/backend-wechat-mini-program-monitoring.md
new file mode 100644
index 0000000000..d8e467e97e
--- /dev/null
+++ b/docs/en/setup/backend/backend-wechat-mini-program-monitoring.md
@@ -0,0 +1,169 @@
+# WeChat Mini Program Monitoring
+
+SkyWalking supports WeChat Mini Program monitoring via the
+[SkyAPM mini-program-monitor SDK](https://github.com/SkyAPM/mini-program-monitor).
+The SDK emits three data streams over standard protocols:
+
+1. **OTLP logs** — JS errors, promise rejections, AJAX failures, and `pageNotFound` events
+2. **OTLP metrics** — app launch, first render, route, script, and sub-package load durations;
+ a `first_paint.time` epoch-ms timestamp; and a delta histogram of outbound request durations
+3. **SkyWalking native trace segments** (opt-in) — one `SegmentObject` per sampled outbound
+ `wx.request`, with an `sw8` header injected on the wire so downstream backend services join
+ the same trace
+
+No new receiver is required — the SDK speaks OTLP/HTTP and the SkyWalking native v3 protocol.
+
+## Prerequisites
+
+- mini-program-monitor **≥ v0.4.0** is the recommended baseline. v0.3.x still works but with
+ the legacy per-device `serviceInstance` behavior (see [Compatibility](#compatibility)).
+- SkyWalking OAP with the changes from SWIP-12 — OTLP HTTP receiver enabled (default on core
+ REST port 12800), the two new component ids registered in `component-libraries.yml`, and the
+ four MAL rules under `otel-rules/miniprogram/` enabled.
+
+## OAP Configuration
+
+Append `miniprogram/*` to `enabledOtelMetricsRules` and `miniprogram` to `lalFiles` and
+`malFiles` in `application.yml` (preserve the existing defaults — don't replace them). These
+entries are included in the shipped defaults, so this section is only relevant if you have
+overridden the defaults via `SW_OTEL_RECEIVER_ENABLED_OTEL_METRICS_RULES`, `SW_LOG_LAL_FILES`,
+or `SW_LOG_MAL_FILES`:
+
+```yaml
+receiver-otel:
+ selector: ${SW_OTEL_RECEIVER:default}
+ default:
+ enabledHandlers: ${SW_OTEL_RECEIVER_ENABLED_HANDLERS:"otlp-traces,otlp-metrics,otlp-logs"}
+ enabledOtelMetricsRules: ${SW_OTEL_RECEIVER_ENABLED_OTEL_METRICS_RULES:"<existing defaults>,miniprogram/*"}
+
+log-analyzer:
+ selector: ${SW_LOG_ANALYZER:default}
+ default:
+ lalFiles: ${SW_LOG_LAL_FILES:"<existing defaults>,miniprogram"}
+ malFiles: ${SW_LOG_MAL_FILES:"<existing defaults>,miniprogram"}
+```
+
+`miniprogram/*` picks up all four MAL files under
+`otel-rules/miniprogram/` (per-platform × per-scope, see [Metrics](#metrics)). Native trace
+segments (`/v3/segments`) need no additional config — the existing trace receiver handles them
+and assigns the `WECHAT_MINI_PROGRAM` layer automatically based on the SDK's
+`WeChat-MiniProgram` componentId (10002).
+
+## Mini Program Setup
+
+```js
+// app.js
+const { init } = require('mini-program-monitor');
+App({
+ onLaunch() {
+ init({
+ service: 'my-mini-program',
+ serviceVersion: 'v1.2.0',
+ // Recommended: set serviceInstance to a version-scoped value (mirroring
+ // service.version or a release tag). Leaving it unset means OTLP metrics + logs
+ // do not produce an instance entity at all (native segments produce a literal '-');
+ // per-version / per-release dashboards need this field populated.
+ serviceInstance: 'v1.2.0',
+ collector: 'https://<oap-or-collector-host>',
+ platform: 'wechat', // optional — auto-detected from runtime
+ enable: { tracing: true }, // opt-in: SkyWalking native segments
+ });
+ },
+});
+```
+
+> **Security:** mini-program SDKs send telemetry from end-user devices over the public
+> internet. See the [Security Notice](../../security/README.md) for deployment guidelines.
+
+## Metrics
+
+All MAL metrics are prefixed `meter_wechat_mp_*` (service-scope) or
+`meter_wechat_mp_instance_*` (instance-scope). Endpoint-scoped variants, where present, use
+the chained `.endpoint(...)` override inside the service-scope file and surface as
+`meter_wechat_mp_endpoint_*`.
+
+| Metric | Scope | Source |
+|----------------------------------|----------------------|-------------------------------------------------------|
+| `app_launch_duration` | service / instance / endpoint | `wx.getPerformance()` launch entry |
+| `first_render_duration` | service / instance / endpoint | PerformanceObserver `firstRender` entry |
+| `route_duration` | service / instance | PerformanceObserver `navigation` / `route` entry |
+| `script_duration` | service / instance | PerformanceObserver `script` entry |
+| `package_load_duration` | service / instance | PerformanceObserver `loadPackage` entry |
+| `request_duration_percentile` | service / instance / endpoint | `miniprogram.request.duration` histogram (P50–P99) |
+| `error_count` | service | LAL-derived counter — log-MAL rule aggregates per exception type |
+
+`first_paint.time` is emitted by the SDK as a wall-clock epoch-ms timestamp (not a duration).
+It is passed through as a raw gauge sample but not aggregated by MAL — surface it only on
+per-page trace / log views where the absolute timestamp has meaning.
+
+Outbound HTTP metrics come "for free" from the existing `core.oal` rules once the component-id
+mapping assigns the WECHAT_MINI_PROGRAM layer to segments. Under the WeChat Mini Program layer
+you get: `service_cpm`, `service_resp_time`, `service_sla`, `service_percentile`, `service_apdex`,
+`service_instance_cpm`, `service_instance_resp_time`, `service_instance_sla`,
+`service_instance_percentile`, `endpoint_cpm`, `endpoint_resp_time`, `endpoint_sla`,
+`endpoint_percentile`, plus `ServiceRelation` / `EndpointRelation` topology edges to the
+backend services the mini-program calls.
+
+## Error Logs
+
+The LAL rule `lal/miniprogram.yaml` uses `layer: auto` mode. It dispatches on the
+`miniprogram.platform` resource attribute — one rule file produces both the `WECHAT_MINI_PROGRAM`
+and `ALIPAY_MINI_PROGRAM` layers. For each error log, the extractor also emits a
+`miniprogram_error_count` counter sample, which the log-MAL rule in `log-mal-rules/miniprogram.yaml`
+aggregates into the per-layer `error_count` metric.
+
+Error categories (`exception.type` tag):
+
+| Category | Source |
+|--------------------|------------------------------------------------------------------|
+| `js` | `wx.onError` — unhandled JS errors |
+| `promise` | `wx.onUnhandledRejection` — unhandled promise rejections |
+| `ajax` | `wx.request` failures (network + non-2xx) |
+| `pageNotFound` | `wx.onPageNotFound` — page not found (WeChat only) |
+
+## Entities
+
+| SkyWalking Entity | Source | Cardinality | Rationale |
+|-------------------|-----------------------------------|-------------------|--------------------------------------------------------|
+| Service | `service.name` | 1 per app | Fleet-wide app health |
+| ServiceInstance | `service.instance.id` (pattern: set to `service.version`) | tens per app | Version regression / rollout monitoring |
+| Endpoint | `miniprogram.page.path` | dozens per app | Which in-app page is slow / error-prone |
+
+Per-device `service.instance.id` is intentionally not used as an aggregation dimension —
+unbounded cardinality means millions of entities on any real user base. The SDK (≥ v0.4.0)
+no longer auto-generates a device id; operators set `serviceInstance` to a version-scoped value.
+
+## Compatibility
+
+- **SDK ≤ v0.2.x** emits `componentId = 10001` (ajax-inherited). Its segments resolve to
+ `Layer.GENERAL` and do not benefit from this integration's layer / topology work. OTLP
+ metrics + logs still flow through MAL / LAL because they key on the `miniprogram.platform`
+ resource attribute, which v0.2 already emits.
+- **SDK ≤ v0.3.x** auto-generates `service.instance.id = mp-{random}` per session, creating
+ one OAP instance entity per device — usually undesirable. Operators on v0.3.x can avoid this
+ by passing `init({ serviceInstance: serviceVersion })` explicitly.
+- **SDK ≥ v0.4.0** leaves `service.instance.id` unset by default. The three signal pipelines
+ then handle absence differently: native segments produce a literal `-` instance entity; OTLP
+ logs and metrics create no instance entity at all. Per-instance dashboards are meaningful
+ only when the operator sets `serviceInstance`.
+- The recommended pattern (SDK docs + e2e CI) is to set `serviceInstance` to a version-scoped
+ value (mirroring `service.version` or a release tag). Then all three signal pipelines
+ aggregate under the same OAP instance entity.
+
+## Dashboards
+
+- **WeChat Mini Program** in the **Mobile** menu group — service list landing page.
+- **Per-service** dashboard — launch / render / route / script / package-load durations,
+ request latency percentile, outbound traffic (load, avg latency, success rate), error count,
+ plus tabs for Instance, Endpoint, Trace, and Log drill-down.
+- **Per-instance (version)** dashboard — same metric set scoped to a release.
+- **Per-endpoint (page)** dashboard — per-page perf, outbound traffic, request latency
+ percentile.
+
+## Limitations
+
+- WebSocket, memory-warning, and network-status-change signals are not instrumented by the
+ current SDK.
+- Device-level per-user aggregation is not supported by design — `serviceInstance` is intended
+ to be a version-scoped identifier.
+- `first_paint.time` is an epoch-ms timestamp, not a duration. It is not aggregated by MAL.
diff --git a/docs/menu.yml b/docs/menu.yml
index d2477663b6..f806393dee 100644
--- a/docs/menu.yml
+++ b/docs/menu.yml
@@ -108,6 +108,10 @@ catalog:
catalog:
- name: "iOS"
path: "/en/setup/backend/backend-ios-monitoring"
+ - name: "WeChat Mini Program"
+ path: "/en/setup/backend/backend-wechat-mini-program-monitoring"
+ - name: "Alipay Mini Program"
+ path: "/en/setup/backend/backend-alipay-mini-program-monitoring"
- name: "Gateway Monitoring"
catalog:
- name: "Nginx Monitoring"