The HarmonyOS SDK assembles RUM data as NDJSON batches and uploads them to Flashduty. The current version collects four RUM event types: view, action, resource, and error. Crashes and hangs enter the same pipeline as error events with is_crash.
Default context
After initialization, the SDK attaches shared context to every event.
| Field | Source | Description |
|---|
source | Fixed value | Always harmony |
service | ConfigurationBuilder.setService() or application bundle id | Service name for filtering |
version | HarmonyOS bundle information | Application version |
application.id | RumConfigurationBuilder(applicationId) | RUM application ID |
session.id | Generated by SDK | User session ID |
os.name / os.version | @kit.BasicServicesKit.deviceInfo | OS name and version |
device.brand / device.model / device.type | deviceInfo | Device brand, model, and type |
connectivity.status | SDK network context | Currently defaults to unknown |
usr.id / usr.name / usr.email | setUserInfo() | Identified user information; the server does not accept other user fields |
context.* | Global or per-event attributes | Custom business context |
clientToken is only used for report authentication and is never attached to RUM events.
Session rules
The SDK manages sampling and lifecycle at the session level.
| Rule | Current behavior |
|---|
| Session sampling | The SDK performs one random sampling decision when a session is created; unsampled sessions write no events |
| Inactivity timeout | A session expires after 15 minutes without real events; keep-alive does not refresh inactivity |
| Maximum duration | A single session lasts up to 4 hours |
| View keep-alive | The active view refreshes time_spent every 30 seconds |
| Start condition | keepAlive never creates a new session; only real view, action, error, or resource events do |
View events
A view represents a page or business screen. Generate views through automatic route tracking or manual APIs.
import { GlobalRumMonitor } from '@flashcatcloud/rum';
const monitor = GlobalRumMonitor.get();
monitor.startView('product-detail', 'ProductDetail', {
'view.url': 'pages/ProductDetail'
});
monitor.stopView('product-detail');
| Field | Description |
|---|
view.id | Unique view ID generated by the SDK |
view.name | View name |
view.url | Uses the view.url attribute first, then falls back to the view key |
view.time_spent | Duration from view start to the current update, in nanoseconds |
view.is_active | Whether the view is still active |
view.action.count | Number of actions under the view |
view.error.count | Number of errors under the view |
view.resource.count | Number of resources under the view |
view.crash.count | Number of is_crash errors under the view, used to calculate crash-free rate |
_dd.document_version | Update version for the same view |
Action events
An action represents user interaction. Record instantaneous actions with addAction(), or timed actions with startAction() and stopAction().
import {
GlobalRumMonitor,
RumActionType
} from '@flashcatcloud/rum';
const monitor = GlobalRumMonitor.get();
monitor.addAction(RumActionType.TAP, 'pay_button');
monitor.startAction(RumActionType.SCROLL, 'feed_scroll');
monitor.stopAction(RumActionType.SCROLL, 'feed_scroll');
| Enum | Value |
|---|
RumActionType.TAP | tap |
RumActionType.SCROLL | scroll |
RumActionType.SWIPE | swipe |
RumActionType.CLICK | click |
RumActionType.BACK | back |
RumActionType.CUSTOM | custom |
action.id, action.type, action.target.name, and action.loading_time. Actions recorded through FlashcatRum.trackTap() use type tap.
Resource events
A resource represents a network request. The SDK generates resources in these cases:
- You use an
rcp session with FlashcatTrace.interceptor()
- You use
FlashcatHttp.request() to wrap @kit.NetworkKit requests
- You manually call
GlobalRumMonitor.get().startResource() and stopResource()
import {
GlobalRumMonitor,
RumResourceKind,
RumResourceMethod
} from '@flashcatcloud/rum';
const monitor = GlobalRumMonitor.get();
monitor.startResource('order-request', RumResourceMethod.GET, 'https://api.example.com/orders');
monitor.stopResource('order-request', 200, 2048, RumResourceKind.NATIVE);
| Field | Description |
|---|
resource.id | Resource ID generated by the SDK |
resource.type | Resource type; automatic network collection classifies by response Content-Type and falls back to native when unrecognized |
resource.url | Request URL |
resource.method | Request method |
resource.status_code | HTTP status code |
resource.size | Response body size in bytes |
resource.duration | Request duration in nanoseconds |
_dd.trace_id / _dd.span_id | Written when the request received traceparent, used to correlate backend Trace |
Response Content-Type | resource.type |
|---|
image/* | image |
video/* / audio/* | media |
font/* | font |
text/css | css |
text/javascript | js |
| Other or missing | native |
source: "network" and includes method, status code, and URL in error.resource.
Error events
Errors represent manually reported errors, unhandled ArkTS exceptions, network errors, crashes, or hangs.
import {
GlobalRumMonitor,
RumErrorSource
} from '@flashcatcloud/rum';
GlobalRumMonitor.get().addError(
'checkout failed',
RumErrorSource.CUSTOM,
'at checkout'
);
| Enum | Value | Description |
|---|
NETWORK | network | Network request failure |
SOURCE | source | ArkTS / JS runtime error or crash |
CONSOLE | console | Console-originated error |
WEBVIEW | webview | WebView-originated error |
AGENT | agent | Agent-originated error |
CUSTOM | custom | Business-defined manual error |
| Field | Description |
|---|
error.message | Error message |
error.source | Error source |
error.stack | Error stack, when present |
error.handling | handled or unhandled |
error.is_crash | true for crashes and hangs |
error.category | Crash module writes Exception or App Hang |
error.source_type | Crash module writes harmony |
error.binary_images | Dynamic library symbol information for native crashes |
build_id | Build-id used to match native symbols |
Crashes and hangs
The Crash module listens to HarmonyOS hiAppEvent for APP_CRASH and APP_FREEZE. The system persists faults and replays them on the next launch, so enable the Crash module early in startup.
Crash events are reported through the RUM error pipeline:
- ArkTS / JS stacks are parsed as V8-style frames
- Native C/C++ stacks are parsed in
#NN pc <address> <lib.so> form
- If you upload
sourceMaps.map, nameCache.json, and unstripped .so files, the server resolves source files, function names, lines, columns, and native symbols
Upload behavior
The SDK uploads events as NDJSON batches.
| Behavior | Current implementation |
|---|
| Upload URL | {site}/api/v2/rum; the default site is https://browser.flashcat.cloud |
| Request method | POST |
| Content-Type | text/plain;charset=UTF-8 |
| Authentication | DD-API-KEY: <clientToken> request header |
| User-Agent | flashcat-sdk-harmony/0.1.3 |
| Query parameters | ddsource=harmony; ddtags includes sdk_version:0.1.3 and appends env, service, and version when present |
| Default upload interval | 5 seconds |
| Network timeout | 30-second connect timeout and 30-second read timeout |
| Retry | Network errors, 401, 403, 408, 429, and 5xx keep the batch and retry with exponential backoff |
| Drop | Other 4xx responses are treated as permanent errors and drop the current batch |
| Force flush | Error and crash events trigger faster flushing |
| Background flush | When the application backgrounds, the SDK refreshes the active view and triggers upload |
Currently not collected
The current HarmonyOS SDK does not automatically collect:
- Session Replay
- Web Vitals or browser page performance metrics
- HarmonyOS page rendering performance metrics
- Automatic frustration events
- Network connectivity changes;
connectivity.status currently remains unknown
