商场
作者 NativeScript.org
nativescript-trace-sentry
由 Tim Doege 编写 | v1.0.0
使用 @sentry/browser 编写的自定义 NativeScript TraceWriter，用于将日志写入 Sentry.io
npm i --save nativescript-trace-sentry

NativeScript Sentry TraceWriter apple android

npm npm

此插件提供了一个自定义的 NativeScript TraceWriter，它将使用官方 Sentry SDK for Browsers 将消息记录到 Sentry.io。这对于从用户 iOS 和 Android 设备捕获生产环境中的跟踪消息非常有用。此插件基于 Todd Anglin 的 NativeScript Raven TraceWriter (https://github.com/toddanglin/nativescript-trace-raven) 插件，该插件使用已弃用（但受支持）的 Raven.JS 库。

入门指南

要将插件添加到 NativeScript 项目中

tns plugin add nativescript-trace-sentry

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

用法

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

app.ts

import * as app from 'application';
import * as trace from 'trace';
import { TraceSentry } from 'nativescript-trace-Sentry';

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 TraceSentry(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。

扩展使用

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

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

记录异常

与使用 trace 记录 Error 不同，Sentry.captureException API 还会尝试将堆栈跟踪信息包含在日志中。

import Sentry = require("Sentry-js");

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

添加面包屑

您可以手动创建将被包含在 Sentry 日志中的 "面包屑"。面包屑旨在显示导致异常、应用程序崩溃或日志消息的操作路径。例如，要添加一个在按钮点击时创建的面包屑

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

最后事件 ID

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

let eventId = Sentry.lastEventId();

注意事项

Sentry.io为日志事件提供慷慨的免费套餐，但最终会根据日志量收费。因此，请谨慎只记录对生产环境故障排除有帮助的事件。

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

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

最佳实践

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

原生错误

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

自动面包屑

除了提供自定义TraceWriter外，此插件还将自动为这些全局Page事件建立自动面包屑

  • onNavigatedTo
  • onLoaded
  • onShownModally

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

new TraceSentry("[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密钥，则应用程序将在启动时崩溃。

贡献

想帮助使此插件更好？在GitHub上报告问题

https://github.com/timdoege/nativescript-trace-sentry/issues

欢迎pull requests。