商场
作者 NativeScript.org
native-script-trace-raven
由 Todd Anglin 编写 | v1.1.1
使用 Raven 记录日志到 Sentry.io 的自定义 NativeScript TraceWriter
npm i --save native-script-trace-raven

NativeScript Raven TraceWriter

此插件提供了一个自定义的 NativeScript TraceWriter，它将使用 Raven.js JavaScript 库 将消息记录到 Sentry.io。这对于从用户的 iOS 和 Android 设备捕获生产中的跟踪消息非常有用。

入门

要将插件添加到 NativeScript 项目中

tns plugin add native-script-trace-raven

注意：要使用此插件，需要来自 Sentry.io 的 "DSN" 密钥。此密钥用于初始化插件并将日志发送到特定的 Sentry.io 项目。

用法

一旦安装了插件，只需初始化新的 TraceWriter。这可以通过不同的方式完成，但为了方便全局使用，在应用启动时设置新的 TraceWriter

app.ts

import * as app from 'application';
import * as trace from 'trace';
import { TraceRaven } from 'nativescript-trace-raven';

app.on(app.launchEvent, (args: app.ApplicationEventData) => {
    let sentryDsn = "[YOUR SENTRY DSN KEY]";

    trace.setCategories(trace.categories.concat(trace.categories.Error, trace.categories.Debug));
    trace.addWriter(new TraceRaven(sentryDsn));
    trace.enable();
});

然后，在您的应用中，只需像往常一样使用 trace。现在输出将被发送到 Sentry.io。

示例

trace.write("Something happened in the app", trace.categories.Error, trace.messageType.error);

注意：Sentry.io 按日志量收费，因此作为最佳实践，在常规开发期间不要启用此自定义 TraceWriter

除了跟踪消息外，此插件还会将以下附加详细信息与每个日志一起发送到 Sentry

  • NativeScript 运行时版本
  • 设备平台（iOS/Android）
  • 设备操作系统版本
  • 设备类型（手机/平板电脑等）
  • 设备型号（iPhone，Galaxy S3 等）
  • 设备语言（en-US 等）
  • 设备 UUID
  • 设备方向（纵向/横向）
  • 电池电量（0 - 100，如果可用）
  • 应用版本名称
  • 环境名称（默认 "Debug"）
  • 用户 IP 地址

日志级别

Sentry.io 为分类日志提供三个级别：info、warning 和 error。

使用 TraceWriter 和 trace API 记录日志时，trace.messageType 将映射到 Sentry 日志级别

  • trace.messageType.log === 日志类型：info
  • trace.messageType.info === 日志类型：info
  • trace.messageType.warn === 日志类型：warning
  • trace.messageType.error === 日志类型：error

如果省略了 trace.messageType，则默认日志级别为 error。

扩展使用

初始化 Raven 时，您可以可选地提供一个 environment 字符串来描述发送日志消息时应用正在运行的位置。默认情况下，此字符串设置为 debug。如果您想指定自己的环境字符串，只需在初始化时添加您的 DSN 密钥即可

trace.addWriter(new TraceRaven(sentryDsn, "production"));

额外的 Raven API

默认 TraceWriter API 只提供 write 方法，但 Raven.js 库还提供了其他功能，例如记录异常详细信息。要使用这些附加 API，您可以直接使用 Raven 库。只要您在应用启动时初始化了 TraceRaven，所有 Raven 配置都将设置好，不需要重新初始化。有关 Raven API 的更多信息，请访问 Sentry.io 上的 JavaScript 文档。

记录异常

与使用 trace 记录错误不同，Raven.captureException API 还会尝试将堆栈跟踪信息与日志一起包含。

import Raven = require("raven-js");

try { 
  throw new Error("This is an example error with stack trace");
} catch (err) {
  Raven.captureException(err);
}

添加面包屑

您可以手动创建“面包屑”，这些面包屑将包含在Sentry日志中。面包屑的目的是显示导致异常、应用崩溃或日志消息的操作路径。例如，当按钮被点击时添加面包屑

public buttonTap(args: EventData) {
  let btn = <Button>args.object;
  Raven.captureBreadcrumb({
    message: `Button tapped`,
    category: "action",
    data: {
      id: btn.id,
      text: btn.text
    },
    level: "info"
  });
}

最后的事件ID

EventId 是Sentry为所有日志生成的全局唯一字符串。Raven提供了获取最近日志的EventId的能力，以便您可以向用户展示并用于客户服务报告。要使用Raven获取最新的EventId

let eventId = Raven.lastEventId();

注意事项

Sentry.io为日志事件提供慷慨的免费层，但最终会根据日志量收费。因此，请小心仅记录对生产中故障排除有帮助的事件。

这意味着：不要在向Sentry记录日志时使用trace.categories.All

这种详细的日志记录可能会产生比所需多得多的日志，并迅速增加您的Sentry.io账单。

最佳实践

  1. 仅在生产环境中向Sentry记录日志
  2. 最小化记录的trace类别（最小：trace.categories.Error）

原生错误

由于此插件在NativeScript JavaScript层运行，它可能无法捕获所有原生iOS或Android错误。这通常是可以接受的，因为与应用代码相关的错误将被捕获，但如果需要原生iOS/Android日志记录，请使用不同的插件。

自动面包屑

除了提供自定义TraceWriter外，此插件还将自动为以下全局Page事件设置自动面包屑

  • onNavigatedTo
  • onLoaded
  • onShownModally

每当这些事件之一发生时，都会将新的面包屑添加到历史记录中。要禁用此行为，使用额外的参数初始化TraceRaven

new TraceRaven("[YOUR DSN KEY]", "production", false)

最后一个参数将启用/禁用此插件创建的自动面包屑。默认为true（启用）。

使用示例

要尝试此插件的示例，请按照以下步骤操作

  1. 从Sentry.io获取DSN密钥
  2. 克隆此存储库
  3. 导航到demo文件夹，并在代码编辑器中打开app.ts
  4. 将sentryDsn字符串替换为您的DSN密钥
  5. 导航回克隆存储库的根目录
  6. 运行npm run demo.ios或npm run demo.android

如果运行示例之前未添加DSN密钥，则应用在启动时会崩溃。

已知问题

  • 异常的堆栈跟踪详细信息不会从Android模拟器发送（不确定是否适用于设备）
  • 在当前的Raven-JS插件中，没有在JavaScript API中禁用控制台、xhr等自动面包屑的方法。

贡献

想要帮助改进此插件吗？在GitHub上报告问题

https://github.com/toddanglin/nativescript-trace-raven/issues

欢迎pull requests。