mini-program-monitor

Monitoring agent for WeChat (微信) and Alipay (支付宝) Mini Programs, reporting to Apache SkyWalking via OTLP and SkyWalking native protocols.

What you get

• Error tracking — JS errors, unhandled promise rejections, page-not-found events. Reported as OTLP logs with OTel semantic conventions (exception.type, exception.stacktrace).
• Performance metrics — app launch, first render, first paint, route navigation, script execution, sub-package load. Reported as OTLP gauge metrics (miniprogram.app_launch.duration, etc.).
• Request metrics — wx.request/my.request, plus downloadFile/uploadFile, reported as an OTLP delta histogram (miniprogram.request.duration) bucketed per flush interval. Failed requests (4xx/5xx/timeout) also emit error logs with exception.type: ajax.
• Distributed tracing (opt-in) — sw8 header propagation across outgoing requests. Reported as SkyWalking SegmentObject to /v3/segments. Enable with enable: { tracing: true }.
• Per-platform distinguishable at the backend — every signal carries miniprogram.platform: wechat | alipay (resource attribute on OTLP, span tag on segments) and each platform has its own SkyWalking component ID (WeChat = 10002, Alipay = 10003). Operators with one WeChat + one Alipay app against the same backend can slice by platform without forcing distinct service.names.
• Queue persistence — unsent events are saved to storage on app hide and restored on next launch.
• OTLP wire format — protobuf by default (application/x-protobuf), JSON available via encoding: 'json'. No runtime dependencies.

Supported platforms

| Platform | Global | Error hooks | Perf API | Status | |---|---|---|---|---| | WeChat (微信) | wx.* | wx.onError, wx.onUnhandledRejection, wx.onPageNotFound | wx.getPerformance() + PerformanceObserver | Implemented | | Alipay (支付宝) | my.* | my.onError, my.onUnhandledRejection | Lifecycle-based fallback (App.onLaunch→onShow, Page.onLoad→onReady) | Implemented |

Install

npm install mini-program-monitor

Then in WeChat Developer Tools: Tools → Build npm (工具 → 构建 npm).

Quickstart

// app.js (WeChat)
const { init } = require('mini-program-monitor');

App({
  onLaunch() {
    init({
      service: 'my-mini-program',
      collector: 'https://your-skywalking-oap.example.com',
    });
  },
});

// app.js (Alipay)
const { init } = require('mini-program-monitor');

App({
  onLaunch() {
    init({
      service: 'my-mini-program',
      collector: 'https://your-skywalking-oap.example.com',
      platform: 'alipay',
    });
  },
});

Options

init({
  // Required
  service: 'my-mini-program',
  collector: 'https://oap.example.com',

  // Optional
  serviceVersion: 'v1.2.0',         // default 'v0.0.0'
  serviceInstance: 'v1.2.0',        // recommended: a version-scoped identifier (e.g. same as serviceVersion).
                                     // NOT a per-device id — per-device cardinality swamps OAP instance aggregation.
                                     // Default unset — OTLP omits `service.instance.id`; SkyWalking segments send `-`.
  platform: 'wechat',               // 'wechat' | 'alipay', auto-detected if omitted

  // Feature flags
  enable: {
    error: true,       // default true  — error logs via OTLP
    perf: true,        // default true  — perf metrics via OTLP
    request: true,     // default true  — request metrics via OTLP
    tracing: false,    // default false — sw8 header injection + trace segments
  },

  // Tracing options (when enable.tracing = true)
  tracing: {
    sampleRate: 1.0,
    urlBlacklist: [/\/heartbeat/],
  },

  // Request options
  request: {
    urlGroupRules: {                 // cardinality control for metric labels
      '/api/users/*': /\/api\/users\/\d+/,
    },
  },

  // Transport
  maxQueue: 200,        // default 200, ring buffer drop-oldest
  flushInterval: 5000,  // default 5000ms
  encoding: 'proto',    // default 'proto' | 'json' — OTLP wire format

  debug: false,         // default false
});

Data flow

Mini-program SDK               Backend (Apache SkyWalking OAP)
────────────────               ─────────────────────────────
Error logs      ──→ OTLP proto ──→ POST /v1/logs     ──→ LAL rules ──→ Log storage
Perf metrics    ──→ OTLP proto ──→ POST /v1/metrics  ──→ MAL rules ──→ Metric storage
Request metrics ──→ OTLP proto ──→ POST /v1/metrics  ──→ MAL rules ──→ Metric storage
Trace segments  ──→ SW native  ──→ POST /v3/segments ──→ Trace storage + topology

OTLP body encoding defaults to protobuf (application/x-protobuf). Pass encoding: 'json' to switch to JSON for debugging.

OTLP resource attributes identify the service:

| Attribute | Example | |---|---| | service.name | my-mini-program | | service.version | v1.2.0 | | miniprogram.platform | wechat or alipay | | telemetry.sdk.name | mini-program-monitor |

Compatibility

• WeChat base library ≥ 2.11 (for wx.getPerformance)
• Alipay base library ≥ 2.0
• Apache SkyWalking OAP ≥ 10.x (with OTLP HTTP receiver)
• Any OTLP-compatible backend (OTel Collector, Grafana, etc.)

What the SDK emits

• docs/SIGNALS.md — every metric name, log attribute, and trace-segment field the SDK produces, with the OTel semantic conventions each uses.
• docs/SAMPLES.md — concrete OTLP + SkyWalking payloads for each signal.

Preview / demo

Want to see the data in a real SkyWalking UI without wiring a mini-program into DevTools? Clone the repo and run:

make preview          # builds sim images, starts OAP + UI + mock-collector + OTel Collector + both sims
# open http://127.0.0.1:8080, wait ~30 s for topology to populate
make preview-down

The sim-wechat and sim-alipay containers drive realistic telemetry (miniprogram.app_launch.duration, request histograms, error logs, trace segments) against the running backend. Multi-arch images (linux/amd64, linux/arm64) are also published to GHCR per SHA — pin to any commit for third-party integration testing:

ghcr.io/skyapm/mini-program-monitor/sim-wechat:<sha>
ghcr.io/skyapm/mini-program-monitor/sim-alipay:<sha>

See sim/README.md for scenarios (demo, baseline, error-storm, slow-api) and env-var knobs.

Changelog

See CHANGES.md for per-version release notes.

License

Apache 2.0. See LICENSE.

Contributing

See DEVELOPER.md.