From a3f1c992e85cb6b7c13b1f1d483d792a193efe25 Mon Sep 17 00:00:00 2001 From: Fiona Date: Wed, 12 Aug 2026 06:49:59 -0700 Subject: [PATCH] docs(rum): document the axios integration for HarmonyOS MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The network section described two integration paths and told everyone else to fall back to getHeaders(), which returns trace headers but no way to report the resource — so axios users, the largest group not covered, had to assemble the resource lifecycle themselves and get the sampling flag, the span id encoding and the first-party gate right on their own. 0.4.0 ships `@flashcatcloud/axios`, and `startTracedResource()` for stacks that do not have a package. The section now opens with a table mapping each network library to its integration, and covers all four. Module versions move to 0.4.0. The `0.3.2` on the advanced-config page stays — it dates a behaviour change rather than naming the current release. --- en/rum/sdk/harmony/data-collection.mdx | 11 +++-- en/rum/sdk/harmony/sdk-integration.mdx | 68 +++++++++++++++++++++----- zh/rum/sdk/harmony/data-collection.mdx | 10 ++-- zh/rum/sdk/harmony/sdk-integration.mdx | 67 ++++++++++++++++++++----- 4 files changed, 124 insertions(+), 32 deletions(-) diff --git a/en/rum/sdk/harmony/data-collection.mdx b/en/rum/sdk/harmony/data-collection.mdx index bb850ce4..ba945a57 100644 --- a/en/rum/sdk/harmony/data-collection.mdx +++ b/en/rum/sdk/harmony/data-collection.mdx @@ -107,9 +107,14 @@ Action events include `action.id`, `action.type`, `action.target.name`, and `act A resource represents a network request. The SDK generates resources in these cases: -- You use an `rcp` session with `FlashcatTrace.interceptor()`, with `setTrackNetworkRequests(true)` enabled -- You use `FlashcatHttp.request()` to wrap `@kit.NetworkKit` requests, with `setTrackNetworkRequests(true)` enabled -- You manually call `GlobalRumMonitor.get().startResource()` and `stopResource()`, which the toggle does not affect +- You use an `rcp` session with `FlashcatTrace.interceptor()` +- You use `FlashcatHttp.request()` to wrap `@kit.NetworkKit` requests +- You wire an axios instance up with `trackAxios()` from `@flashcatcloud/axios` +- You wire another network stack up with `FlashcatTrace.startTracedResource()` + +All four require `setTrackNetworkRequests(true)`. You can also record resources +manually with `GlobalRumMonitor.get().startResource()` and `stopResource()`, +which the toggle does not affect. ```ts import { diff --git a/en/rum/sdk/harmony/sdk-integration.mdx b/en/rum/sdk/harmony/sdk-integration.mdx index 98c63dfe..d51c8d69 100644 --- a/en/rum/sdk/harmony/sdk-integration.mdx +++ b/en/rum/sdk/harmony/sdk-integration.mdx @@ -7,7 +7,7 @@ keywords: ["RUM", "HarmonyOS SDK", "ArkTS", "user monitoring"] The HarmonyOS SDK provides RUM, Trace, and Crash capabilities through ArkTS HAR modules. After initialization, the SDK reports views, user actions, network requests, errors, and crashes to Flashduty RUM, with `source: "harmony"` identifying the data source. -The current SDK module version is `0.3.2`. The examples use `@flashcatcloud/core`, `@flashcatcloud/rum`, `@flashcatcloud/trace`, and `@flashcatcloud/crash`. +The current SDK module version is `0.4.0`. The examples use `@flashcatcloud/core`, `@flashcatcloud/rum`, `@flashcatcloud/trace`, and `@flashcatcloud/crash`. Applications using axios also need `@flashcatcloud/axios`. ## Prerequisites @@ -26,10 +26,12 @@ Add the Flashduty modules you need to the application module's `oh-package.json5 ```json5 oh-package.json5 { dependencies: { - "@flashcatcloud/core": "0.3.2", - "@flashcatcloud/rum": "0.3.2", - "@flashcatcloud/trace": "0.3.2", - "@flashcatcloud/crash": "0.3.2" + "@flashcatcloud/core": "0.4.0", + "@flashcatcloud/rum": "0.4.0", + "@flashcatcloud/trace": "0.4.0", + "@flashcatcloud/crash": "0.4.0", + // Only needed when the application uses @ohos/axios + "@flashcatcloud/axios": "0.4.0" } } ``` @@ -160,10 +162,17 @@ monitor.stopAction(RumActionType.SCROLL, 'product_feed'); ## Track network requests and Trace -The HarmonyOS SDK supports two network integration paths. Both only produce resource events when RUM is configured with `setTrackNetworkRequests(true)`, which is disabled by default. +The HarmonyOS SDK offers an integration path per network library. **All of them only produce resource events when RUM is configured with `setTrackNetworkRequests(true)`, which is disabled by default.** + +| Network library in use | Integration | +|---|---| +| `rcp` from `@kit.RemoteCommunicationKit` | Add `FlashcatTrace.interceptor()` | +| `@kit.NetworkKit` | Use `FlashcatHttp.request()` instead | +| `@ohos/axios` | Call `trackAxios(instance)` | +| Anything else | Wire it up with `FlashcatTrace.startTracedResource()` | -The SDK does not automatically hook `http.createHttp()` from `@kit.NetworkKit`. Requests you send with it directly are not collected. Use one of the integration paths below, or the [manual resource API](/en/rum/sdk/harmony/data-collection#resource-events). +The SDK does not automatically hook `http.createHttp()` from `@kit.NetworkKit`. Requests you send with it directly are not collected — use the integration for your library from the table above. ### rcp interceptor @@ -195,17 +204,50 @@ const response = await FlashcatHttp.request('https://api.example.com/orders', { }); ``` - -`traceparent` and `tracestate` are injected only when tracking consent is `TrackingConsent.GRANTED`. `FlashcatHttp` also honors `setFirstPartyHosts()`; when no first-party host is configured, it injects into all hosts. If a request already has `traceparent`, the SDK does not overwrite the existing Trace context. - +### axios + +`@ohos/axios` has its own network adapter and travels neither path above. Install `@flashcatcloud/axios` and call `trackAxios()` once per axios instance. + +```ts +import axios from '@ohos/axios'; +import { trackAxios } from '@flashcatcloud/axios'; + +const apiClient = axios.create({ baseURL: 'https://api.example.com' }); +trackAxios(apiClient); +``` + +Put it wherever you already create the instance — usually the file that wires up auth tokens and shared error handling. -For other network stacks, use `FlashcatTrace.getHeaders()` to get `traceparent` and `tracestate` headers for manual injection. + +Interceptors are registered **per instance**: the default `axios` export and anything from `axios.create()` do not share them. Call this once for each instance you want reported, and exactly once — calling it twice reports every request twice. + + +### Other network stacks + +For a custom client or a library not covered above, use `FlashcatTrace.startTracedResource()`. It registers the resource and returns the headers to send; consent and first-party gating, the sampling decision and id encoding all happen inside the SDK. ```ts -const headers = FlashcatTrace.getHeaders(); -// Merge headers into your custom network request +import { FlashcatTrace, TracedResource } from '@flashcatcloud/trace'; + +const traced: TracedResource = FlashcatTrace.startTracedResource(url, 'GET'); +// merge traced.headers into the request, then send it +try { + const response = await send(url, traced.headers); + FlashcatTrace.stopTracedResource(traced.key, response.status, response.size); +} catch (e) { + // A response — even a 404 — belongs to stopTracedResource, which keeps it a + // resource carrying that status. Only a request that never got a response + // goes here. + FlashcatTrace.failTracedResource(traced.key, `${e}`); +} ``` +Pass the **full url**: a relative path has no host to match, so the first-party check skips injection and the resource is reported without one. Pair every `startTracedResource` with a `stopTracedResource` or `failTracedResource`, including on the failure path, or the resource never closes. + + +`traceparent` and `tracestate` are injected only when tracking consent is `TrackingConsent.GRANTED`, and only into hosts matching `setFirstPartyHosts()`; when no first-party host is configured, they go to all hosts. If a request already carries a `traceparent`, the SDK does not overwrite the existing Trace context. This applies to all four integrations. + + ## Identify users After sign-in, set the current user. The SDK writes these fields to the `usr` object on subsequent RUM events. diff --git a/zh/rum/sdk/harmony/data-collection.mdx b/zh/rum/sdk/harmony/data-collection.mdx index 4159b42c..896a4e5f 100644 --- a/zh/rum/sdk/harmony/data-collection.mdx +++ b/zh/rum/sdk/harmony/data-collection.mdx @@ -107,9 +107,13 @@ Action 事件包含 `action.id`、`action.type`、`action.target.name` 和 `acti Resource 表示网络请求。SDK 会在以下场景生成 resource： -- 使用 `rcp` session 并添加 `FlashcatTrace.interceptor()`，需要启用 `setTrackNetworkRequests(true)` -- 使用 `FlashcatHttp.request()` 包装 `@kit.NetworkKit` 请求，需要启用 `setTrackNetworkRequests(true)` -- 通过 `GlobalRumMonitor.get().startResource()` 和 `stopResource()` 手动记录，不受该开关影响 +- 使用 `rcp` session 并添加 `FlashcatTrace.interceptor()` +- 使用 `FlashcatHttp.request()` 包装 `@kit.NetworkKit` 请求 +- 使用 `@flashcatcloud/axios` 的 `trackAxios()` 接入 axios 实例 +- 用 `FlashcatTrace.startTracedResource()` 接入其他网络栈 + +以上四种都需要启用 `setTrackNetworkRequests(true)`。此外还可以通过 +`GlobalRumMonitor.get().startResource()` 和 `stopResource()` 手动记录，该方式不受此开关影响。 ```ts import { diff --git a/zh/rum/sdk/harmony/sdk-integration.mdx b/zh/rum/sdk/harmony/sdk-integration.mdx index 6ae2484c..2981d654 100644 --- a/zh/rum/sdk/harmony/sdk-integration.mdx +++ b/zh/rum/sdk/harmony/sdk-integration.mdx @@ -7,7 +7,7 @@ keywords: ["RUM", "HarmonyOS SDK", "鸿蒙 SDK", "ArkTS", "用户监控"] HarmonyOS SDK 通过 ArkTS HAR 模块提供 RUM、Trace 和 Crash 能力。初始化后，SDK 会把应用中的视图、用户操作、网络请求、错误和崩溃事件上报到 Flashduty RUM，并使用 `source: "harmony"` 标识数据来源。 -当前 SDK 模块版本为 `0.3.2`。示例使用 `@flashcatcloud/core`、`@flashcatcloud/rum`、`@flashcatcloud/trace` 和 `@flashcatcloud/crash` 四个模块。 +当前 SDK 模块版本为 `0.4.0`。示例使用 `@flashcatcloud/core`、`@flashcatcloud/rum`、`@flashcatcloud/trace` 和 `@flashcatcloud/crash`。使用 axios 的应用还需要 `@flashcatcloud/axios`。 ## 前提条件 @@ -26,10 +26,12 @@ HarmonyOS SDK 通过 ArkTS HAR 模块提供 RUM、Trace 和 Crash 能力。初 ```json5 oh-package.json5 { dependencies: { - "@flashcatcloud/core": "0.3.2", - "@flashcatcloud/rum": "0.3.2", - "@flashcatcloud/trace": "0.3.2", - "@flashcatcloud/crash": "0.3.2" + "@flashcatcloud/core": "0.4.0", + "@flashcatcloud/rum": "0.4.0", + "@flashcatcloud/trace": "0.4.0", + "@flashcatcloud/crash": "0.4.0", + // 仅在应用使用 @ohos/axios 时需要 + "@flashcatcloud/axios": "0.4.0" } } ``` @@ -160,10 +162,17 @@ monitor.stopAction(RumActionType.SCROLL, 'product_feed'); ## 采集网络请求和 Trace -HarmonyOS SDK 提供两种网络接入方式。两者都只有在 RUM 配置中启用 `setTrackNetworkRequests(true)` 后才会生成 resource 事件，该开关默认关闭。 +HarmonyOS SDK 按网络库提供三种接入方式。**它们都只有在 RUM 配置中启用 `setTrackNetworkRequests(true)` 后才会生成 resource 事件，该开关默认关闭。** + +| 应用使用的网络库 | 接入方式 | +|---|---| +| `@kit.RemoteCommunicationKit` 的 `rcp` | 添加 `FlashcatTrace.interceptor()` | +| `@kit.NetworkKit` | 改用 `FlashcatHttp.request()` | +| `@ohos/axios` | 调用 `trackAxios(instance)` | +| 其他网络栈 | 用 `FlashcatTrace.startTracedResource()` 自行接入 | -SDK 不会自动挂钩 `@kit.NetworkKit` 的 `http.createHttp()`。直接用它发起的请求不会被采集，请改用下面两种接入方式之一，或使用[手动 resource API](/zh/rum/sdk/harmony/data-collection#resource-事件)。 +SDK 不会自动挂钩 `@kit.NetworkKit` 的 `http.createHttp()`。直接用它发起的请求不会被采集，请改用上表中对应的接入方式。 ### rcp 拦截器 @@ -195,17 +204,49 @@ const response = await FlashcatHttp.request('https://api.example.com/orders', { }); ``` - -`traceparent` 和 `tracestate` 只有在追踪同意状态为 `TrackingConsent.GRANTED` 时才会注入。`FlashcatHttp` 还会按 `setFirstPartyHosts()` 限制注入域名；未配置一方域名时会对所有 host 注入。请求已带有 `traceparent` 时，SDK 不会覆盖已有 Trace 上下文。 - +### axios + +`@ohos/axios` 有自己的网络适配层，不经过上面两条路径，需要安装 `@flashcatcloud/axios` 并对每个 axios 实例调用一次 `trackAxios()`。 + +```ts +import axios from '@ohos/axios'; +import { trackAxios } from '@flashcatcloud/axios'; + +const apiClient = axios.create({ baseURL: 'https://api.example.com' }); +trackAxios(apiClient); +``` + +放在你已经创建 axios 实例的地方即可，通常是统一封装 token 和错误处理的那个文件。 -对于其他网络栈，可以通过 `FlashcatTrace.getHeaders()` 获取包含 `traceparent` 和 `tracestate` 的手动注入请求头。 + +拦截器是**按实例**注册的：`axios` 默认导出和 `axios.create()` 创建的实例互不共享。每个需要上报的实例都要调用一次，且**只调一次**——重复调用会导致同一请求上报两次。 + + +### 其他网络栈 + +自研网络库或上面未覆盖的三方库，用 `FlashcatTrace.startTracedResource()` 接入。它登记 resource 并返回要注入的请求头，采集同意与一方域名门控、采样判断、id 编码都在 SDK 内部完成。 ```ts -const headers = FlashcatTrace.getHeaders(); -// 将 headers 合并到你的自定义网络请求中 +import { FlashcatTrace, TracedResource } from '@flashcatcloud/trace'; + +const traced: TracedResource = FlashcatTrace.startTracedResource(url, 'GET'); +// 把 traced.headers 合并进请求后再发送 +try { + const response = await send(url, traced.headers); + FlashcatTrace.stopTracedResource(traced.key, response.status, response.size); +} catch (e) { + // 拿到了响应（哪怕是 404）应传给 stopTracedResource，保留为对应状态码的 + // resource；只有完全没拿到响应的传输失败才用 failTracedResource。 + FlashcatTrace.failTracedResource(traced.key, `${e}`); +} ``` +务必传入**完整 URL**：相对路径解析不出域名，一方域名检查会因此跳过注入，resource 上也会缺少 host。每次 `startTracedResource` 都要配对一次 `stopTracedResource` 或 `failTracedResource`，包括失败路径，否则 resource 不会关闭。 + + +`traceparent` 和 `tracestate` 只有在追踪同意状态为 `TrackingConsent.GRANTED` 时才会注入，并按 `setFirstPartyHosts()` 限制注入域名；未配置一方域名时会对所有 host 注入。请求已带有 `traceparent` 时，SDK 不会覆盖已有 Trace 上下文。以上对四种接入方式一致生效。 + + ## 关联用户信息 登录后，你可以设置当前用户。SDK 会把用户字段写入后续 RUM 事件的 `usr` 对象。