# @cmall/sentry-utils

> 提供 cmall 常用的上报过滤器，和更便捷的 cdn 加载方式

Latest version **1.1.5** (published 2021-12-02) · MIT license · 0 weekly downloads

## Install

```sh
npm install @cmall/sentry-utils
pnpm add @cmall/sentry-utils
yarn add @cmall/sentry-utils
bun add @cmall/sentry-utils
```

## Health

**Score 30/100 (F)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.1.5 |
| Published | 2021-12-02 |
| First published | 2021-12-02 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 57.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | vegawong |
| Maintainers | vegawong |

## Links

- npm: https://www.npmjs.com/package/@cmall/sentry-utils
- npm.io page: https://npm.io/package/@cmall/sentry-utils

## Recent versions

- 1.1.5 (latest) — 2021-12-02
- 1.1.4 — 2021-12-02
- 1.1.3 — 2021-12-02
- 1.1.2 — 2021-12-02

## README

# Sentry Utils

提供 cmall 常用的上报过滤器，和更便捷的 cdn 加载方式

## Features

### cdn 加载

```html
<script src="https://cmall-static-resource.s3.us-west-2.amazonaws.com/libs/sentry-utils/1.1.1/sentry-util.umd.js"></script>
<script>
  if (window.SentryUtil) {
    window.SentryUtil.loadScript({
      dsn: "请输入您的项目dsn字符串",
      release: {
        package: "请输入release的包名称",
        version: "请输入release的版本",
      },
    });
  }
</script>
```

### beforeSend 中间件

> 适用于npm包的使用方式。

```javascript
import Sentry from "@sentry/browser";
import { createPipeline, middlewares } from "@cmall/sentry-utils";

Sentry.init({
  // ..
  beforeSend(event, hints) {
    // 按中间件顺序执行beforeSend
    return createPipeline().use(middlewares.jqAjax).run(event, hints);
  },
});
```


## CONSTANTS

### EVENT_TYPE

已知的自定义异常类型，用于tags.eventType

### BURIED_POINT_ERROR_PHASE

自埋点错误阶段, 当tags.eventType等于EVENT_TYPE.BURIED_POINT_MUSTACHE有效，取与tags.phase
### DEFAULT_IGNORE_ERROS

默认的ignoreErros设置

### DEFAULT_BLACKLIST_URLS

默认的blackListUrls设置

### DEFAULT_MIDDLESARES

默认使用的中间件列表

## API

### loadScript(option)

以默认配置加载 cdn 并初始化 sdk

#### 参数

- option.dsn {string}

必填，sentry 项目的 dsn 字符串, 见文档：[https://docs.sentry.io/platforms/javascript/configuration/options/#dsn](https://docs.sentry.io/platforms/javascript/configuration/options/#dsn)

- option.release {object}

  必填，初始化到指定的 release，初始化成功后网页捕获的异常都或上报到此 release

  - release.package {string} 包名称

  - release.version {string} 包版本

  最终会通过`{release.package}@{release.version}`组成字符串传递给 sdk 配置的 release 项，见文档：[https://docs.sentry.io/platforms/javascript/configuration/options/#release](https://docs.sentry.io/platforms/javascript/configuration/options/#release)

- option.beforeSend {function}

  选填，相当于一个sentry.init的beforeSend函数或者一个中间件（等价的）， 在原有默认使用的中间件之后追加自定义的beforeSend操作。

### createPipeline()

创建一个 pipeline 对象

### pipeline.use(...middlewares)

向 pipeline 中注册一个或多个中间件

#### 参数

- middleware {function}

  必填，相当于一个 beforeSend 函数，返回 null 或者 event， 参考文档：[https://docs.sentry.io/platforms/javascript/configuration/options/#before-send](https://docs.sentry.io/platforms/javascript/configuration/options/#before-send

  > 中间件支持 async 异步， 返回 Promise<null | event>, 但是中间件的运行仍然是同步的

e.g.

```javascript
const middleware1 = (e, h) => e;
const middleware2 = (e, h) => e;
const middleware3 = (e, h) => e;

const pipeline = createPipeline();
// 逐个注册
pipeline.use(middleware1).use(middleware2).use(middleware3);
// 或者批量注册
pipeline.use(middleware1, middleware2, middleware3);
```

### pipeline.run(event, hints)

运行 pipeline， 会根据运行前注册的中间件逐个运行， 直至运行完毕或者中途返回 null

#### 参数

- event {object}

  上报事件对象，从 beforeSend 中获得，参考文档：[https://docs.sentry.io/platforms/javascript/configuration/options/#before-send](https://docs.sentry.io/platforms/javascript/configuration/options/#before-send)

#### 参数

- hints {object}

  额外的数据，从 beforeSend 中获得，参考文档：[https://docs.sentry.io/platforms/javascript/configuration/filtering/#using-hints](hhttps://docs.sentry.io/platforms/javascript/configuration/filtering/#using-hints)

e.g.

```javascript
Sentry.init({
  // ..
  beforeSend(event, hint) {
    const middleware1 = (e, h) => e;
    const middleware2 = (e, h) => e;
    const middleware3 = (e, h) => e;
    const pipeline = createPipeline().use(middleware1, middleware2, middleware3).run(event, hint);
  },
});
```



### pipeline.asMiddleware()

将自身pipeline变成一个中间件， 用于嵌套在其他pipeline里面, 编写自定义中间件时非常有用。

e.g. 

```javascript
const child = createPipeline().use(/** any middlewares */)
const mainPipeline = createPipeline().use(child.asMiddeware())
```

## 中间件

### jqAjax()

针对 mvc 项目的中间件，捕获 UnhandledRejection 类型事件，判断是否符合 mvc 项目中的 jquery 发起的 ajax 请求异常，如果符合则拦截上报（mvc 项目中已经统一手动上报 jqAjax 异常，所以无需额外上报一个 UnhandledRejection 事件）

### environment(option)

根据event.environment过滤

> 使用上面的cdn方式加载的话，会默认给event设定了environment值是`pc`或者`mobile`

#### 参数

- option

  可选参数

- option.blackList {Array<string>} 

  可选，黑名单列表，environment值如果在列表范围里面则过滤上报。

- option.whiteList {Array<string>}

  可选，白名单列表，environment值不在列表范围内的都过滤上报。

e.g.

```javascript
import {createPipeline, middlewares} from '@cmall/sentry-utils'; 
// ..
Sentry.init({
  // ..
  beforeSend(event, hint) {
    return createPipeline().use(middlewares.environment({
      blackList: ['pc'], // 过滤pc环境异常上报
    }))
  }
})
```


### instagram()

过滤基于instagram的webview上报的异常

### thirdPartBuriedPoint(option?)

过滤第三方埋点上报的异常

#### 参数

- option 可选

- option.url 可选，默认true

是否过滤第三方外部url加载的js上报的异常

- option.native 可选， 默认true

是否过滤第三方埋点的填入的代码上报的异常

---
_Source: https://npm.io/package/@cmall/sentry-utils · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._