自定义采集规则¶

自动采集无法表达业务语义时，可以手动上报 View、Action、Resource、Error 和 Long Task。.NET / C# 使用 RumSdk，Native C/C++ 使用 guance_rum.h 中的 C ABI；两种接入产生相同的 Windows RUM 数据类型。

避免重复采集

手动 API 和自动采集写入同一 Session。已经由窗口、控件、HttpClient、WinHTTP 或 WebView2 自动采集的数据，不要再次手动上报。

View¶

.NET / C#Native C/C++

RumSdk.StartView(
    "OrderDetail",
    new Dictionary<string, object?>
    {
        ["order_type"] = "subscription"
    });

// 页面结束时执行。
RumSdk.StopView();

guance_rum_start_view(rum, "OrderDetail");

// 页面或窗口结束时执行。
guance_rum_stop_view(rum);

启动新的 View 会自动结束当前活动 View。View 名称应描述稳定页面，不要包含订单号、用户 ID、对象地址或搜索词。

Action¶

作用域 Action¶

用于采集一段业务操作及其内部 Resource、Error 和 Long Task：

.NET / C#Native C/C++

using (RumSdk.StartAction("SaveOrder", "click"))
{
    await SaveOrderAsync();
}

释放 RumActionScope 时结束 Action。

const char* action_id = guance_rum_start_action(rum, "SaveOrder", "click");

save_order();

guance_rum_stop_action(rum, action_id);

action_id 只用于结束当前 Action，不要长期保存或跨 SDK Handle 使用。

已知耗时的 Action¶

.NET / C#Native C/C++

RumSdk.AddAction(
    name: "ExportReport",
    type: "custom",
    duration: TimeSpan.FromMilliseconds(320),
    properties: new Dictionary<string, object?>
    {
        ["format"] = "csv"
    });

constexpr int64_t duration_ns = 320LL * 1000 * 1000;
guance_rum_add_action(rum, "ExportReport", "custom", duration_ns);

Resource¶

.NET / C#Native C/C++

var resourceId = RumSdk.StartResource(
    "https://api.example.com/orders",
    "GET");

RumSdk.StopResource(
    resourceId,
    statusCode: 200,
    timing: RumResourceTiming.FromTotalElapsed(
        TimeSpan.FromMilliseconds(120),
        source: "manual"),
    responseSize: 2048,
    requestSize: 0,
    resourceType: "http");

如果应用已经测量 DNS、TCP、TLS 和 TTFB，可以使用 RumResourceTiming.FromPhases() 写入阶段耗时；没有可靠数据时只写总耗时。

C++ 应用可以使用 ResourceScope 保证异常或提前返回时仍结束 Resource：

#include "guance_rum.hpp"

guance::rum::ResourceScope resource(
    rum,
    "https://api.example.com/orders",
    "GET",
    "http");

const auto response = send_request();
resource.complete(
    response.status_code,
    response.body_size,
    response.request_size);

纯 C 应用可以配对调用 guance_rum_start_resource() 与 guance_rum_stop_resource()；需要写入 trace_id、span_id、请求大小或 HTTP 协议时使用 guance_rum_stop_resource_ext()。

请求失败时仍需结束 Resource，并将状态码设为 0。启用了 HttpClient 或 WinHTTP 自动 Resource 后，不要为同一请求再次调用手动 API。

Error¶

.NET / C#Native C/C++

try
{
    await LoadOrdersAsync();
}
catch (Exception exception)
{
    RumSdk.AddError(
        exception,
        new Dictionary<string, object?>
        {
            ["operation"] = "load_orders"
        });
    throw;
}

非 Exception 错误可以使用 RumSdk.AddError(stack, message, errorType, source)。

guance_rum_add_error(
    rum,
    "OrderRepository::load_orders",
    "Order request failed",
    "NetworkError",
    "custom");

Native 崩溃监控在下次启动时恢复崩溃 Error；不要在崩溃处理器中再调用手动 Error API。

Long Task¶

.NET / C#Native C/C++

RumSdk.AddLongTask(
    duration: TimeSpan.FromMilliseconds(850),
    stack: "ReportRenderer.Render");

constexpr int64_t duration_ns = 850LL * 1000 * 1000;
guance_rum_add_long_task(rum, duration_ns, "ReportRenderer::render");

已开启 UI 线程阻塞监控时，不要对同一段阻塞再次手动上报。

Flush¶

手动事件先进入本地队列。如需在关键流程后立即尝试上报：

.NET / C#Native C/C++

await RumSdk.FlushAsync();

guance_rum_flush(rum);

应用正常退出时仍应调用 ShutdownAsync() 或 guance_rum_shutdown()。HTTP Trace 传播和应用日志分别参考 Trace 配置与 Log 配置。

自定义采集规则¶

View¶

Action¶

作用域 Action¶

已知耗时的 Action¶

Resource¶

Error¶

Long Task¶

Flush¶

文档内容是否对您有帮助？ ×