# @datadog/sketches-js 中文文档

规范地址：https://npmcn.com/package/%40datadog/sketches-js/

版本：2\.1\.1
npm 元数据更新时间：2024-04-23T08:27:53.059Z
中文译文更新时间：2026-11-11T13:24:26.019Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40datadog/sketches-js
原文对照：https://npmcn.com/package/%40datadog/sketches-js/?lang=original
源码仓库：https://github.com/DataDog/sketches-js

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：110 kB，44 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2020-12-07T20:09:11.586Z
- 最新版本发布：2024-04-23T08:27:52.864Z
- 近 30 天下载量：5940271（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：10（近 12 个月 0 个）

## 中文简介

TypeScript 执行 DDSketch, 分布式四分法草图算法

## 安装

```sh
npm install @datadog/sketches-js
```

也可以使用：`pnpm add @datadog/sketches-js`、`yarn add @datadog/sketches-js`、`bun add @datadog/sketches-js`

## README

# 草图 -js

![Continuous Integration](https://github.com/DataDog/sketches-js/workflows/Continuous%20Integration/badge.svg) [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)

此回波包含分布式四分法草图算法的 TypeScript 执行 [DDSketch 软件](http://www.vldb.org/pvldb/vol12/p2195-masson.pdf). DDSketch是可合并的,指分布式系统的多幅草图可以在一个中心节点进行组合.

## 安装

包裹在下面 [@ datadog/ skets-js (英语)](https://www.npmjs.com/package/@datadog/sketches-js) 并且可以通过国家防范机制或Yarn安装:

```sh
# NPM
npm install @datadog/sketches-js

# Yarn
yarn add @datadog/sketches-js
```

当使用Protobuf序列化时 [原生生物库](https://www.npmjs.com/package/protobufjs) 模块也必须手动安装:

```sh
# NPM
npm install protobufjs

# Yarn
yarn add protobufjs
```

## 使用量

### 初始化草图

要初始化带有默认参数的草图 :

```js
import { DDSketch } from '@datadog/sketches-js'; // or const { DDSketch } = require('@datadog/sketches-js');
const sketch = new DDSketch();
```

#### 修改 `relativeAccuracy`

如果你想对草图结果的精确度 进行更多的颗粒控制 `relativeAccuracy` 参数初始化草图时.

其他直方图使用 _等级错误_ 保证(即收回直方图中的p99, 将给予您p98.9和p99.1), DDSketch 使用 a _相对错误_ 保证(如果p99的实际值为100,则a/ `relativeAccuracy` (单位:千美元).

这种属性使得DDSketch对于数据的长尾分布特别有用,比如测量延迟.

```js
import { DDSketch } from '@datadog/sketches-js';

const sketch = new DDSketch({
  relativeAccuracy: 0.01, // `relativeAccuracy` must be between 0 and 1
});
```

### 将数值添加到草图中

要在草图上添加一个数字,请拨 `sketch.accept(value)`支持正负数字.

```js
const measurementOne = 1607374726;
const measurementTwo = 0;
const measurementThree = -3.1415;

sketch.accept(measurementOne);
sketch.accept(measurementTwo);
sketch.accept(measurementThree);
```

### 从草图中获取测量数据

要从草图中获取测量数据,请使用 `sketch.getValueAtQuantile(quantile)`。任何在0至1 (包括) 之间的数字都可以作为定量.

此外,还有共同的汇总统计数据,例如: `sketch.min`, (中文(简体) ), `sketch.max`, (中文(简体) ), `sketch.sum`,以及 `sketch.count`数字 :

```js
const measurementOne = 1607374726;
const measurementTwo = 0;
const measurementThree = -3.1415;

sketch.accept(measurementOne);
sketch.accept(measurementTwo);
sketch.accept(measurementThree);

sketch.getValueAtQuantile(0)     // -3.1415
sketch.getValueAtQuantile(0.5)   // 0
sketch.getValueAtQuantile(0.99)  // 1607374726
sketch.getValueAtQuantile(1)     // 1607374726

sketch.min                       // -3.1415
sketch.max                       // 1607374726
sketch.count                     // 3
sketch.sum                       // 1607374722.86
```

### 合并多幅草图

独立草图可以合并,但必须采用相同的草图 `relativeAccuracy`,从而能够以分布式方式收集和传递测量结果,并合并其结果,同时保留 `relativeAccuracy` 保证.

```js
import { DDSketch } from '@datadog/sketches-js';

const sketch1 = new DDSketch();
const sketch2 = new DDSketch();

[1,2,3,4,5].forEach(value => sketch1.accept(value));
[6,7,8,9,10].forEach(value => sketch2.accept(value));

// `sketch2` is merged into `sketch1`, without modifying `sketch2`
sketch1.merge(sketch2);

sketch1.getValueAtQuantile(1) // 10
```

## 参考资料

-   [DDSketch:带有相对错误保证的可快速和可完全计量的量子板](http://www.vldb.org/pvldb/vol12/p2195-masson.pdf). Charles Masson, Jee E. Rim and Homin K. Lee. 2019 (英语).
-   Java 执行 : [https://github.com/DataDog/sketches-java (英语)](https://github.com/DataDog/sketches-java)
-   执行 : [https://github.com/ DataDog/ sketches-go 页面存档备份,存于互联网档案馆](https://github.com/DataDog/sketches-go)
-   Python 执行 : [https://github.com/ DataDog/ sketches-py 互联网档案馆的存檔,存档日期2013-12-22](https://github.com/DataDog/sketches-py)

## 常见问题

### @datadog/sketches-js 是什么？

TypeScript 执行 DDSketch, 分布式四分法草图算法

### 如何安装 @datadog/sketches-js？

在项目目录运行 npm install @datadog/sketches-js，或使用 pnpm add / yarn add / bun add。

### @datadog/sketches-js 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @datadog/sketches-js 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @datadog/sketches-js 可以商用吗？

@datadog/sketches-js 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @datadog/sketches-js 的下载量有多少？

根据 npm 官方下载统计，@datadog/sketches-js 在 2026/10/12 – 2026/11/10 这 30 天内被下载 5,940,271 次，日均约 198,009 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @datadog/sketches-js 还在维护吗？

最新版本 2\.1\.1 发布于 2024/04/23（2 年前）；至今共发布 10 个版本，其中过去 12 个月发布了 0 个；首次发布于 2020/12/08。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。