sentry-miniapp 1.9.0 → 1.11.0

package/README.en.md

@@ -10,7 +10,7 @@
 
 [简体中文](./README.md) | English
 
-A **mini program monitoring SDK** built on `@sentry/core`, providing **error monitoring**, **performance monitoring**, offline caching, and distributed tracing. Supports WeChat, Alipay, ByteDance, Baidu, QQ, DingTalk, Kuaishou mini programs and cross-platform frameworks (Taro / uni-app).
+A **mini program monitoring SDK** built on `@sentry/core`, providing **error monitoring**, **performance monitoring**, offline caching, and distributed tracing. Supports WeChat, Alipay, ByteDance, Baidu, QQ, DingTalk, Kuaishou mini programs, **WeChat / Douyin mini games**, and cross-platform frameworks (Taro / uni-app).
 
 > **What are Mini Programs?** Mini programs (小程序) are lightweight apps that run inside super-apps like WeChat, Alipay, and ByteDance/Douyin. They form a massive ecosystem in China with **hundreds of millions of daily active users**, but have no direct equivalent in the Western tech stack. Think of them as a hybrid between PWAs and native apps, but hosted within a platform's sandbox.
 
@@ -38,6 +38,7 @@ See [CHANGELOG.md](./CHANGELOG.md) for full details.
 
 - **Modern Architecture**: Built on the latest Sentry JavaScript V10 SDK core modules.
 - **True Multi-Platform Support**: Built-in API abstraction engine — one codebase seamlessly supports **WeChat, Alipay, ByteDance, Baidu, QQ, DingTalk, and Kuaishou** mini program platforms.
+- **Mini Game Support**: Auto-detects mini-game environments — error / network / device monitoring works out of the box, plus mini-game-specific **cold-start first-frame timing** and **frame-rate / jank (FPS) monitoring** (see "Mini Game Support" below).
 - **Automatic Exception Capture**: No business code intrusion required. Automatically hooks into lifecycle error listeners (`onError`, `onUnhandledRejection`, `onPageNotFound`, `onMemoryWarning`).
 - **Rich Context Breadcrumbs**: Automatically records device info, user tap/touch interactions, network requests (XHR/Fetch), and page lifecycle events.
 - **Built-in SourceMap Path Normalization**: Handles virtual stack paths across WeChat, Alipay, ByteDance and other platforms. Works with sentry-cli for seamless SourceMap resolution.
@@ -45,7 +46,7 @@ See [CHANGELOG.md](./CHANGELOG.md) for full details.
 - **Deep Performance Monitoring**: Integrates mini program Performance API for navigation timing (FCP/LCP), render performance, resource loading, and custom performance marks.
 - **Smart Deduplication & Filtering**: Built-in error deduplication and sample rate controls to prevent log storms.
 - **Cross-Platform Framework Friendly**: Works seamlessly with Taro, uni-app, and other cross-platform compilation frameworks.
-- **Distributed Tracing**: Automatically injects `sentry-trace` / `baggage` headers into network requests, connecting mini program and backend service call chains.
+- **Distributed Tracing**: Automatically injects `sentry-trace` / `baggage` headers into network requests and reports mini program API timing as `http.client` spans, connecting mini program and backend service call chains.
 - **Session Health Monitoring**: Automatic session lifecycle management with crash rate and session health data in the Sentry Release Health dashboard.
 - **Network Status Monitoring**: Real-time tracking of network changes (WiFi/4G/offline) to help diagnose network-related exceptions.
 - **Stack Trace Parsing**: Built-in multi-platform stack parser supporting V8/Safari/JavaScriptCore formats for precise error location with SourceMap.
@@ -108,10 +109,11 @@ Sentry.init({
 
   // --- Sampling ---
   sampleRate: 1.0, // Error reporting sample rate (0.0 - 1.0)
+  tracesSampleRate: 1.0, // Performance tracing sample rate; API requests are reported as http.client spans
 
   // --- Distributed Tracing ---
   enableTracePropagation: true, // Auto-inject sentry-trace/baggage headers (default: true)
-  tracePropagationTargets: ['api.example.com'], // Only inject tracing headers for specified domains
+  tracePropagationTargets: ['api.example.com'], // Only inject tracing headers for specified domains; spans still follow tracing sampling
 
   // --- Session & Network Monitoring ---
   enableAutoSessionTracking: true, // Auto session lifecycle management (default: true)
@@ -298,6 +300,59 @@ App({
 
 ---
 
+## Mini Game Support
+
+`sentry-miniapp` also works in **mini games** (WeChat / ByteDance mini games, etc.). Mini games have no `App()`/`Page()`/page routing, but expose platform APIs like `wx.onError`, `wx.request`, `wx.getDeviceInfo`, and `wx.getPerformance`. Most SDK capabilities work out of the box, plus mini-game-specific cold-start and frame-rate monitoring.
+
+**Initialization is identical to mini programs** — the SDK auto-detects the mini-game environment and enables the relevant features:
+
+```js
+import * as Sentry from 'sentry-miniapp';
+
+Sentry.init({
+  dsn: 'YOUR_DSN',
+  // Enabled by default in mini-game environments; set to false to disable:
+  // enableMinigameLifecycle: true,  // cold-start first-frame timing + launch scene + onShow/onHide breadcrumbs
+  // enableMinigameFrameRate: true,  // FPS / jank monitoring
+
+  // Fine-tune frame-rate monitoring (FPS warning threshold, jank threshold, report interval, etc.):
+  // minigameFrameRateOptions: { fpsWarningThreshold: 45 },
+});
+```
+
+### Capability matrix
+
+| Capability | Mini Game | Notes |
+|------------|:---------:|-------|
+| Exception / unhandled rejection capture | ✅ | `wx.onError` / `wx.onUnhandledRejection` |
+| API request monitoring (count / duration / status) | ✅ | wraps `wx.request`; creates `http.client` spans when tracing is enabled |
+| Network status monitoring | ✅ | `wx.onNetworkStatusChange` |
+| Device info / context breadcrumbs | ✅ | `wx.getDeviceInfo` etc. |
+| Resource load timing | ✅ | `wx.getPerformance()` |
+| **Cold-start first-frame timing + launch scene** | ✅ New | `MinigameIntegration` (first `requestAnimationFrame` ≈ first frame) |
+| **Frame rate / jank monitoring** | ✅ New | `MinigameFrameRateIntegration` (RAF FPS sampling, long frames → jank, periodic `minigame.framerate` context) |
+| Page lifecycle / tap breadcrumbs | ➖ | No pages in mini games — auto-skipped; use `onShow/onHide` breadcrumbs or manual `addBreadcrumb` |
+
+> These two integrations are enabled by default only in mini-game environments. In particular, **frame-rate monitoring relies on a global `requestAnimationFrame`**: mini games have one (bound to the real render loop), whereas mini programs use a dual-thread architecture whose logic layer has no global `requestAnimationFrame` — so even if enabled there, it safely no-ops (it cannot measure page render frame rate).
+
+#### Independent performance reporting (Performance page)
+
+Cold-start and frame-rate data are **not only attached to error events** — with tracing enabled they are reported as independent transactions, so you can aggregate trends / distributions / P95 across sessions on the Sentry Performance page:
+
+- **Cold start** → a `minigame.coldstart` transaction (with a `cold_start` measurement).
+- **Frame rate / jank** → accumulated per session and flushed as a single `minigame.framerate.summary` transaction on **background (onHide) / session end** (with `fps_avg` / `fps_p95` / `fps_min` / `jank_count` measurements) — no per-window events, quota-friendly.
+
+```js
+Sentry.init({
+  dsn: 'YOUR_DSN',
+  tracesSampleRate: 1.0, // enable performance sampling (decoupled from error sampleRate)
+});
+```
+
+> Requires `tracesSampleRate` (or `tracesSampler`) for performance transactions to be sent; this sampling is **independent of** the error `sampleRate`. Without tracing enabled, it degrades to the original behavior: performance data is only attached to error events as `minigame` / `minigame.framerate` contexts + breadcrumbs.
+
+---
+
 ## FAQ
 
 ### 1. Do I need to manually report errors in `onError`?

package/README.md

@@ -10,7 +10,7 @@
 
 简体中文 | [English](./README.en.md)
 
-一个基于 `@sentry/core` 核心构建的**小程序监控 SDK**，提供**异常监控**、**性能监控**、离线缓存、分布式追踪等能力。支持微信、支付宝、字节跳动、百度、QQ、钉钉、快手等多端小程序及 Taro / uni-app 等跨端框架。
+一个基于 `@sentry/core` 核心构建的**小程序监控 SDK**，提供**异常监控**、**性能监控**、离线缓存、分布式追踪等能力。支持微信、支付宝、字节跳动、百度、QQ、钉钉、快手等多端小程序，以及微信 / 抖音等**小游戏**，并兼容 Taro / uni-app 等跨端框架。
 
 > **📰 最新文章**：[《我给 Sentry 提了个 PR，后来 sentry-miniapp 进了官方文档》](https://juejin.cn/post/7636106283963760681) — sentry-miniapp 已被收录进 Sentry 官方文档的 community-supported SDK 列表，这篇文章记录这件事的来龙去脉。觉得有用请帮忙点个 ⭐ Star，让更多小程序团队找到它。
 
@@ -36,6 +36,7 @@
 
 - **🚀 现代架构**：基于最新的 Sentry JavaScript V10 SDK 核心模块构建。
 - **📱 真正的多端支持**：内置 API 抹平引擎，一套代码无缝兼容**微信、支付宝、字节、百度、QQ、钉钉、快手**等主流小程序平台。
+- **🎮 小游戏支持**：自动识别小游戏环境，异常 / 网络 / 设备监控开箱即用，并提供小游戏专属的**冷启动首帧耗时**与**帧率 / 卡顿（FPS / jank）监控**（详见下文「小游戏支持」）。
 - **🎯 全自动异常捕获**：无需侵入业务代码，自动监听并上报生命周期异常（`onError`、`onUnhandledRejection`、`onPageNotFound`、`onMemoryWarning`）。
 - **🍞 丰富的上下文面包屑**：自动记录设备信息、用户点击/触摸操作、网络请求（XHR/Fetch）以及页面生命周期。
 - **🗺️ 内置 SourceMap 路径抹平**：自动处理微信、支付宝、字节等多端小程序的虚拟堆栈路径，配合 sentry-cli 极简实现 SourceMap 解析。
@@ -43,7 +44,7 @@
 - **⚡ 深度性能监控**：集成小程序 Performance API，全面采集导航性能（FCP/LCP）、渲染性能、资源加载耗时及用户自定义性能标记。
 - **🛡️ 智能降噪与过滤**：内置强大的错误去重和采样率控制机制，避免日志风暴。
 - **🔧 跨端框架友好**：完美支持在 Taro、uni-app 等第三方多端编译框架中集成使用。
-- **🔗 分布式追踪**：自动在网络请求中注入 `sentry-trace` / `baggage` 头，串联小程序与后端服务的完整调用链。
+- **🔗 分布式追踪**：自动在网络请求中注入 `sentry-trace` / `baggage` 头，并将小程序 API 请求耗时上报为 `http.client` span，串联小程序与后端服务的完整调用链。
 - **📊 Session 健康监控**：自动管理会话生命周期，在 Sentry Release Health 面板展示崩溃率和会话健康数据。
 - **📶 网络状态监控**：实时追踪网络变化（WiFi/4G/离线），帮助排查网络相关的异常。
 - **🔍 堆栈解析**：内置多平台堆栈解析器，支持 V8/Safari/JavaScriptCore 格式，配合 SourceMap 精准定位错误。
@@ -108,10 +109,11 @@ Sentry.init({
   
   // --- 性能与采样率 ---
   sampleRate: 1.0, // 异常上报采样率 (0.0 - 1.0)
+  tracesSampleRate: 1.0, // 性能追踪采样率；开启后 API 请求会作为 http.client span 上报
 
   // --- 分布式追踪 ---
   enableTracePropagation: true, // 自动在请求头中注入 sentry-trace/baggage（默认 true）
-  tracePropagationTargets: ['api.example.com'], // 仅对指定域名注入追踪头（为空则全部注入）
+  tracePropagationTargets: ['api.example.com'], // 仅对指定域名注入追踪头（为空则全部注入；span 仍按 tracing 采样记录）
 
   // --- Session 与网络监控 ---
   enableAutoSessionTracking: true, // 自动管理 Session 生命周期（默认 true）
@@ -311,6 +313,59 @@ App({
 
 ---
 
+## 🎮 小游戏支持
+
+`sentry-miniapp` 同样适用于**小游戏**（微信小游戏 / 抖音小游戏等）。小游戏没有 `App()`/`Page()`/页面路由，但具备 `wx.onError`、`wx.request`、`wx.getDeviceInfo`、`wx.getPerformance` 等平台能力，因此 SDK 的大部分能力开箱即用，并额外提供小游戏专属的冷启动与帧率监控。
+
+**初始化与小程序完全一致**，SDK 会自动检测小游戏环境并启用对应能力：
+
+```js
+import * as Sentry from 'sentry-miniapp';
+
+Sentry.init({
+  dsn: 'YOUR_DSN',
+  // 小游戏环境下，以下两项默认即为开启，可显式关闭：
+  // enableMinigameLifecycle: true,  // 冷启动首帧耗时 + 启动场景 + onShow/onHide 面包屑
+  // enableMinigameFrameRate: true,  // 帧率(FPS)/卡顿(jank)监控
+
+  // 帧率监控细调（FPS 告警阈值、卡顿阈值、上报间隔等）：
+  // minigameFrameRateOptions: { fpsWarningThreshold: 45 },
+});
+```
+
+### 能力矩阵
+
+| 能力 | 小游戏 | 说明 |
+|------|:------:|------|
+| 异常 / 未处理 Promise 捕获 | ✅ | `wx.onError` / `wx.onUnhandledRejection` |
+| API 请求监控（请求数 / 耗时 / 状态码） | ✅ | 包裹 `wx.request`；开启 tracing 后生成 `http.client` span |
+| 网络状态监控 | ✅ | `wx.onNetworkStatusChange` |
+| 设备信息 / 上下文面包屑 | ✅ | `wx.getDeviceInfo` 等 |
+| 资源加载耗时 | ✅ | `wx.getPerformance()` |
+| **冷启动首帧耗时 + 启动场景** | ✅ 新增 | `MinigameIntegration`（首个 `requestAnimationFrame` 近似首帧） |
+| **帧率 / 卡顿监控** | ✅ 新增 | `MinigameFrameRateIntegration`（RAF 采样 FPS，长帧记 jank，周期上报 `minigame.framerate` 上下文） |
+| 页面生命周期 / 点击面包屑 | ➖ | 小游戏无页面，自动跳过；行为追踪请用 `onShow/onHide` 面包屑或手动 `addBreadcrumb` |
+
+> 上述两个集成仅在小游戏环境默认启用。其中**帧率监控依赖全局 `requestAnimationFrame`**：小游戏有（绑定真实渲染帧），而小程序为双线程架构、逻辑层没有全局 `requestAnimationFrame`，因此在小程序中即使开启也会安全 no-op（无法测量页面渲染帧率）。
+
+#### 性能数据独立上报（进 Performance 页）
+
+冷启动与帧率数据**不只挂在 error 事件上**——开启 tracing 后会作为独立 transaction 上报，可在 Sentry Performance 页做跨会话的趋势 / 分布 / P95 聚合：
+
+- **冷启动** → `minigame.coldstart` transaction（含 `cold_start` measurement）。
+- **帧率 / 卡顿** → 会话维度累积，在**退后台（onHide）/ 会话结束**时发一个 `minigame.framerate.summary` transaction（含 `fps_avg` / `fps_p95` / `fps_min` / `jank_count` measurements）——不每窗口发事件，配额友好。
+
+```js
+Sentry.init({
+  dsn: 'YOUR_DSN',
+  tracesSampleRate: 1.0, // 启用性能采样（与 error sampleRate 解耦）
+});
+```
+
+> 需设置 `tracesSampleRate`（或 `tracesSampler`）才会上报性能 transaction；其采样**独立于** error 的 `sampleRate`。未启用 tracing 时退化为原有行为：性能数据仅作为 `minigame` / `minigame.framerate` 上下文 + 面包屑挂在 error 事件上。
+
+---
+
 ## ❓ 常见问题 (FAQ)
 
 ### 1. 初始化后无法自动上报异常，必须在 `onError` 中手动调 API 吗？