# @figma/hot-shots 中文文档

规范地址：https://npmcn.com/package/%40figma/hot-shots/

版本：9\.0\.0-figma\.1
npm 元数据更新时间：2026-09-10T19:34:03.571Z
中文译文更新时间：2026-11-14T17:31:44.686Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40figma/hot-shots
原文对照：https://npmcn.com/package/%40figma/hot-shots/?lang=original
项目主页：https://github.com/brightcove/hot-shots#readme
源码仓库：https://github.com/brightcove/hot-shots

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

- 包体积（解压后）：87.5 kB，12 个文件
- TypeScript 类型：包内自带
- Node.js 要求：\>=6\.0\.0
- 运行依赖：0 个
- 首次发布：2022-03-15T16:42:37.751Z
- 最新版本发布：2022-03-15T17:13:22.959Z
- 近 30 天下载量：26666（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：2（近 12 个月 0 个）

## 中文简介

StatsD、DogStatsD和Telegraf的节点客户端

## 安装

```sh
npm install @figma/hot-shots
```

也可以使用：`pnpm add @figma/hot-shots`、`yarn add @figma/hot-shots`、`bun add @figma/hot-shots`

## README

# 热镜头

一个Node.js客户端 [爱思](http://etsy.com/)是因为 [数据D](https://github.com/etsy/statsd) 服务器,数据犬 [狗纹章D](http://docs.datadoghq.com/guides/dogstatsd/) 服务器,以及 [豪华DB](http://influxdb.com/) [远程格拉夫](https://github.com/influxdb/telegraf) StatsD 服务器 .

这个项目原本是叉子的 [节点统计d](https://github.com/sivy/node-statsd)本项目 包括最近节点统计的所有变化和许多其他变化,包括:

-   类型脚本
-   远程绘图支持
-   事件
-   儿童客户
-   tcp 协议支持
-   uds( Unix 域名套接字) 协议支持
-   原始流协议支持
-   模拟模式
-   时空
-   实时
-   更多,包括许多错误修正

hot-shots支持节点8.x和更高.

[![Build Status](https://secure.travis-ci.org/brightcove/hot-shots.png?branch=master)](http://travis-ci.org/brightcove/hot-shots)

## 从节点状态移动

你只需要做一件事: 改变节点状态 成为热弹.

你可以检查详细 [更改日志](https://github.com/brightcove/hot-shots/blob/master/CHANGES.md) 自上次发布节点后 发生了什么变化.

## 使用量

所有初始化参数都是可选的.

参数(指定为一个物体传入发热口:

-   `host`: 如果不设定, 发送数据给构建器的主机将尝试 从那里取来 `DD_AGENT_HOST` 环境变量, `default: 'undefined'` 数据 [UDP/数据套接字](https://nodejs.org/api/dgram.html#dgram_socket_send_msg_offset_length_port_address_callback) 结果 `127.0.0.1` 或者说 `::1` 正在使用中.
-   `port`: 发送数据端口如果不设定, 构建者试图从 `DD_DOGSTATSD_PORT` 环境变量, `default: 8125`
-   `prefix`: 每个 stat 名称的前缀 `default: ''`。如果需要,则必须明确说明注释前缀分隔符(例如:. `my_prefix.`) (中文(简体) ).
-   `suffix`: 每个统计名称后缀用什么 `default: ''`。如果需要,则必须明确说明注释后缀分隔符(例如:. `.my_suffix`) (中文(简体) ).
-   `tagPrefix`: 有字符的前缀标签列表 `default: '#'`注释与 `telegraf` 选项.
-   `tagSeparator`: 带有字符的单独标签 `default: ','`注释与 `telegraf` 选项.
-   `globalize`: 在全球公开这个 StatsD 实例 . `default: false`
-   `cacheDns`: caches dns 检索到 _东道主_ 页:1 _缓存DnsTtl_,仅使用 当协议是 `udp`, (中文(简体) ), `default: false`
-   `cacheDnsTtl`: 以毫秒计的 dns 检查时间到时间 _缓存Dns_ 已启用. `default: 60000`
-   `mock`: 创建模拟 StatsD 实例,不发送数据到 并允许从模拟缓冲器读取数据。 请注意: 模拟缓冲器会不断增长,所以只能用于测试或定期清除. `default: false`
-   `globalTags`:每个度量中会添加的标记。 可以是对象也可以是标记列表. 这个 _数据犬_ `dd.internal.entity_id` 标签附于 `globalTags` 从 `DD_ENTITY_ID` 如果设置了后者,则环境变量. `default: {}`
-   `maxBufferSize`:如果大于0,则会缓冲出公尺,并仅在字符串长度大于大小时发送. `default: 0`
-   `bufferFlushInterval`:如果使用缓冲,此时是毫秒总冲出任何缓冲度量衡的时间. `default: 1000`
-   `telegraf`: 使用 Telegraf 的 StatsD 线条协议, 与其他协议略有不同 `default: false`
-   `sampleRate`:只向 StatsD 发送所有 StatsD 方法的数据样本. 可以在方法层面被推翻. `default: 1`
-   `errorHandler`: 具有一个参数的函数。 要求它处理各种错误. `default: none`,将错误扔出/ 拖放到控制台
-   `useDefaultRoute`:在Linux系统中使用默认接口. 在容器中运行时有用
-   `protocol`: 使用 `tcp` tCP 协议选项,或 `uds` 用于Unix域套接字协议或 `stream` 为生溪. 默认为 `udp` 否则.
-   `path`: 仅在协议时使用 `uds`默认为 `/var/run/datadog/dsd.socket`。 。 。 .
-   `stream`: 引用流实例. 仅当协议是 `stream`。 。 。 .
-   `tcpGracefulErrorHandling`: 仅在协议时使用 `tcp`。布尔表示是否优雅地处理套接字错误。 默认为真.
-   `tcpGracefulRestartRateLimit`: 仅在协议时使用 `tcp`重新创建套接字之间的时间。 默认为 `1000`。 。 。 .
-   `udsGracefulErrorHandling`: 仅在协议时使用 `uds`。布尔表示是否优雅地处理套接字错误。 默认为真.
-   `udsGracefulRestartRateLimit`: 仅在协议时使用 `uds`重新创建套接字之间的时间。 默认为 `1000`。 。 。 .
-   `closingFlushInterval`:关闭前,StatsD会检查飞行中的信息. 每次检查之间的时间( ms) 。 默认为 `50`。 。 。 .

### StatsD 方法

所有 StatsD 方法,但 `event`, (中文(简体) ), `close`,以及 `check` 拥有相同的API:

-   `name`: stat 名称 `required`
-   `value`: 数据值 `required except in increment/decrement where it defaults to 1/-1 respectively`
-   `sampleRate`: 只向 StatsD 发送数据样本 `default: 1`
-   `tags`: 添加到度量衡中的标记. 可以是对象 `{ tag: "value"}` 或一系列标记. `default: []`
-   `callback`: 当计量符发送或缓冲后, 执行的回调

如果指定数组为 `name` 该数组中的每个项目都将随指定的值一起发送.

#### `close`

相近方法有以下API: 相近法 相近法 相近法 相近法 相近法 相近法 相近法 相近法 相近法 相近法 相近法 相近法 相近法 相近法 相近法 相近法 相近法 相近法 相近法 相近法 相近法 相近法 相近法 相近法 相近法 相近法 相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相

-   `callback`: 关闭后执行的回调完成 。 一旦这通电话被调用,所有给STASD的电话都会失败.

#### `event`

该事件方法有以下API:

-   `title`页:1 `required`
-   `text`: 事件简介 `default is title`
-   `options`: 事件选项
    -   `date_happened` 为事件指定时间戳 `default is now`
    -   `hostname` 为事件指定主机名 .
    -   `aggregation_key` 为事件指定一个集合密钥, 将其与其他一些密钥分组 .
    -   `priority` 可以是“正常”或“低” `default: normal`
    -   `source_type_name` 为事件指定源类型 .
    -   `alert_type` 可以是“错误”、“警告”、“信息”或“成功” `default: info`
-   `tags`: 添加到度量衡中的标记. 可以是对象 `{ tag: "value"}` 或一系列标记. `default: []`
-   `callback`: 度量衡发送后执行的回调 .

#### `check`

检查方法有如下API:

-   `name`: 检查名称 `required`
-   `status`: 检查状态 `required`
-   `options`: 检查的选项
    -   `date_happened` 为支票指定时间戳 `default is now`
    -   `hostname` 给支票指定主机名 .
    -   `message` 给支票发个信息.
-   `tags`: 添加到度量衡中的标记. 可以是对象 `{ tag: "value"}` 或一系列标记. `default: []`
-   `callback`: 度量衡发送后执行的回调 .

```javascript
  var StatsD = require('hot-shots'),
      client = new StatsD({
          port: 8020,
          globalTags: { env: process.env.NODE_ENV },
          errorHandler: errorHandler,
      });

  // Increment: Increments a stat by a value (default is 1)
  client.increment('my_counter');

  // Decrement: Decrements a stat by a value (default is -1)
  client.decrement('my_counter');

  // Histogram: send data for histogram stat (DataDog and Telegraf only)
  client.histogram('my_histogram', 42);

  // Distribution: Tracks the statistical distribution of a set of values across your infrastructure.
  // (DataDog v6)
  client.distribution('my_distribution', 42);

  // Gauge: Gauge a stat by a specified amount
  client.gauge('my_gauge', 123.45);

  // Set: Counts unique occurrences of a stat (alias of unique)
  client.set('my_unique', 'foobar');
  client.unique('my_unique', 'foobarbaz');

  // Event: sends the titled event (DataDog only)
  client.event('my_title', 'description');

  // Check: sends a service check (DataDog only)
  client.check('service.up', client.CHECKS.OK, { hostname: 'host-1' }, ['foo', 'bar'])

  // Incrementing multiple items
  client.increment(['these', 'are', 'different', 'stats']);

  // Incrementing with tags
  client.increment('my_counter', ['foo', 'bar']);

  // Sampling, this will sample 25% of the time the StatsD Daemon will compensate for sampling
  client.increment('my_counter', 1, 0.25);

  // Tags, this will add user-defined tags to the data
  // (DataDog and Telegraf only)
  client.histogram('my_histogram', 42, ['foo', 'bar']);

  // Using the callback.  This is the same format for the callback
  // with all non-close calls
  client.set(['foo', 'bar'], 42, function(error, bytes){
    //this only gets called once after all messages have been sent
    if(error){
      console.error('Oh noes! There was an error:', error);
    } else {
      console.log('Successfully sent', bytes, 'bytes');
    }
    });

  // Timing: sends a timing command with the specified milliseconds
  client.timing('response_time', 42);

  // Timing: also accepts a Date object of which the difference is calculated
  client.timing('response_time', new Date());

  // Timer: Returns a function that you call to record how long the first
  // parameter takes to execute (in milliseconds) and then sends that value
  // using 'client.timing'.
  // The parameters after the first one (in this case 'fn')
  // match those in 'client.timing'.
  var fn = function(a, b) { return a + b };
  client.timer(fn, 'fn_execution_time')(2, 2);

  // Async timer: Similar to timer above, but you instead pass in a function
  // that returns a Promise.  And then it returns a Promise that will record the timing.
  var fn = function () { return new Promise(function (resolve, reject) { setTimeout(resolve, n); }); };
  var instrumented = statsd.asyncTimer(fn, 'fn_execution_time');
  instrumented().then(function() {
    console.log('Code run and metric sent');
  });

  // Async timer: Similar to asyncTimer above, but it instead emits a distribution.
  var fn = function () { return new Promise(function (resolve, reject) { setTimeout(resolve, n); }); };
  var instrumented = statsd.asyncDistTimer(fn, 'fn_execution_time');
  instrumented().then(function() {
    console.log('Code run and metric sent');
  });

  // Sampling, tags and callback are optional and could be used in any combination (DataDog and Telegraf only)
  client.histogram('my_histogram', 42, 0.25); // 25% Sample Rate
  client.histogram('my_histogram', 42, { tag: 'value'}); // User-defined tag
  client.histogram('my_histogram', 42, ['tag:value']); // Tags as an array
  client.histogram('my_histogram', 42, next); // Callback
  client.histogram('my_histogram', 42, 0.25, ['tag']);
  client.histogram('my_histogram', 42, 0.25, next);
  client.histogram('my_histogram', 42, { tag: 'value'}, next);
  client.histogram('my_histogram', 42, 0.25, { tag: 'value'}, next);

  // Use a child client to add more context to the client.
  // Clients can be nested.
  var childClient = client.childClient({
    prefix: 'additionalPrefix.',
    suffix: '.additionalSuffix',
    globalTags: { globalTag1: 'forAllMetricsFromChildClient'}
  });
  childClient.increment('my_counter_with_more_tags');

  // Close statsd.  This will ensure all stats are sent and stop statsd
  // from doing anything more.
  client.close(function(err) {
    console.log('The close did not work quite right: ', err);
  });
```

## DogStatsD 和 Telegraf 函数

上述的一些功能是DogStatsD或Telegraf所特有的. 他们不会做任何事情 如果你正在使用常规的 统计客户端.

-   全球标签参数- DogStatsD 或 Telegraf
-   标记参数 - DogStatsD或Telegraf.
-   远程graf 参数 - 远程graf
-   协议参数中的 uds 选项- DogStatsD
-   直方图方法- DogStatsD 或 Telegraf
-   事件方法 - DogStatsD
-   检查方法 - DogStatsD

## 错误

和往常一样,回调会有一个错误作为其第一个参数. 您可以在信件和关闭回调中都出现错误 .

如果未给定可选的回调, 则在有些中出现错误 大小写和一个控制台.log消息被其它用户使用。 只会出错 如果缺少回调,或者如果某些潜在的配置问题有待解决,则明确投出.

如果您希望确保所有错误被捕获, 请指定 `errorHandler` 在你的根头 客户端。 这将捕捉到套接字设置和发送信件时的错误, 关闭插座。 如果您指定了错误汉德勒和回调,则回调优先.

```javascript
// Using errorHandler
var client = new StatsD({
  errorHandler: function (error) {
    console.log("Socket errors caught here: ", error);
  }
})
```

### 压缩错误

如果你遇到这样的错误 `Error sending hot-shots message: Error: congestion` 错误代码 `1`, (中文(简体) ), 可能是因为您正在向单个代理/ 服务器发送大量的度量衡 . 只有在使用 UDS 协议并意味着软件包正在被丢弃时才会出现这个错误. 看看这个 [数据犬文件](https://docs.datadoghq.com/developers/dogstatsd/high_throughput/?#over-uds-unix-domain-socket) 给一些调整连接的提示.

## 解锁域套接字支持

协议中的“ 哑弹” 选项是支持 [数据犬的Unix域袜](https://docs.datadoghq.com/developers/dogstatsd/unix_socket/)它有以下限制:

-   它只在"Node-gyp"工作的地方工作. 如果你不知道这是什么,这个 也许对你有好处。 如果你对图书馆有问题 你之前的"节日",你在这里也会有问题.
-   它对视窗不起作用

以上将会导致使用 unix-dgram 的基础库, 不正确安装。 鉴于图书馆被列为 可选的依赖性,以及密码库如何使用,此安装 失败不会造成任何问题。 这只意味着你不能使用 哑弹的特色.

## 提交更改

谢谢你考虑对这个项目做任何更新! 这里有你们要采取的步骤:

1.  运行“ npm 安装 ”
2.  在叉子中添加您的更改以及任何需要的新测试
3.  运行“ npm 测试”
4.  以任何需要的文档更新 README.md
5.  如果您做了任何 API 修改, 请更新类型. d. ts
6.  推动您的更改并创建 PR

当你做了这一切,我们很高兴 尝试得到这个合并马上.

## 软件包版本和安全

版本将尝试遵循语义化的版本,主要版本中仅会出现重大变化.

npm的出版可能 一个人, [检讨](https://github.com/bdeitte),它具有两个要素认证功能,可用于出版。 出版只包含一个额外的库unix-dgram.

## 名称

为什么这个项目被命名为"热拍"? 因为:

1.  无法在 npm 上找到另一个统计名
2.  这是一部愚蠢的电影的名字
3.  没有好理由

## 许可证

hot-shots 根据麻省理工学院的许可.

## 常见问题

### @figma/hot-shots 是什么？

StatsD、DogStatsD和Telegraf的节点客户端

### 如何安装 @figma/hot-shots？

在项目目录运行 npm install @figma/hot-shots，或使用 pnpm add / yarn add / bun add。

### @figma/hot-shots 支持 TypeScript 吗？

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

### @figma/hot-shots 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=6\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @figma/hot-shots 可以商用吗？

@figma/hot-shots 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @figma/hot-shots 的下载量有多少？

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

### @figma/hot-shots 还在维护吗？

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