sentry-miniapp 1.10.0 → 1.11.0

package/README.en.md

@@ -46,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.
@@ -109,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)
@@ -324,7 +325,7 @@ Sentry.init({
 | Capability | Mini Game | Notes |
 |------------|:---------:|-------|
 | Exception / unhandled rejection capture | ✅ | `wx.onError` / `wx.onUnhandledRejection` |
-| API request monitoring (count / duration / status) | ✅ | wraps `wx.request` |
+| 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()` |
@@ -334,6 +335,22 @@ Sentry.init({
 
 > 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

package/README.md

@@ -44,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 精准定位错误。
@@ -109,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）
@@ -337,7 +338,7 @@ Sentry.init({
 | 能力 | 小游戏 | 说明 |
 |------|:------:|------|
 | 异常 / 未处理 Promise 捕获 | ✅ | `wx.onError` / `wx.onUnhandledRejection` |
-| API 请求监控（请求数 / 耗时 / 状态码） | ✅ | 包裹 `wx.request` |
+| API 请求监控（请求数 / 耗时 / 状态码） | ✅ | 包裹 `wx.request`；开启 tracing 后生成 `http.client` span |
 | 网络状态监控 | ✅ | `wx.onNetworkStatusChange` |
 | 设备信息 / 上下文面包屑 | ✅ | `wx.getDeviceInfo` 等 |
 | 资源加载耗时 | ✅ | `wx.getPerformance()` |
@@ -347,6 +348,22 @@ Sentry.init({
 
 > 上述两个集成仅在小游戏环境默认启用。其中**帧率监控依赖全局 `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)