# @bonniernews/gcp-push-metrics 中文文档

规范地址：https://npmcn.com/package/%40bonniernews/gcp-push-metrics/

版本：4\.4\.0
npm 元数据更新时间：2026-09-28T09:14:42.375Z
中文译文更新时间：2026-11-08T11:02:38.939Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40bonniernews/gcp-push-metrics
原文对照：https://npmcn.com/package/%40bonniernews/gcp-push-metrics/?lang=original
项目主页：https://github.com/BonnierNews/gcp-push-metrics#readme
源码仓库：https://github.com/BonnierNews/gcp-push-metrics

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

- 包体积（解压后）：40.2 kB，14 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：未声明
- Node.js 要求：\>=18\.18
- 运行依赖：1 个
- 首次发布：2021-10-04T12:47:55.796Z
- 最新版本发布：2026-09-28T09:14:41.899Z
- 近 30 天下载量：7437（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：33（近 12 个月 3 个）

## 中文简介

将定制度量衡推向谷歌云监测.

## 安装

```sh
npm install @bonniernews/gcp-push-metrics
```

也可以使用：`pnpm add @bonniernews/gcp-push-metrics`、`yarn add @bonniernews/gcp-push-metrics`、`bun add @bonniernews/gcp-push-metrics`

## README

# GCP 推量仪

[![Build Status](https://travis-ci.org/BonnierNews/gcp-push-metrics.svg?branch=master)](https://travis-ci.org/BonnierNews/gcp-push-metrics)

这个软件包帮助您汇总并推进自定义的度量衡到从Node.js应用程序的Google Cloud Monitor上,例如使用Google Cloud Run运行.

使用这个包,您可以收集三种类型的度量衡:计数器,计分器和摘要. 数值在内存中汇总,每60秒推到 [云监测 API](https://cloud.google.com/monitoring/custom-metrics/creating-metrics)。 。 。 .

它的API深受优秀的启发 [舞会客户](https://github.com/siimon/prom-client/) 但内心的运转却大相径庭 正如最初为将使用Prometheus进行计量的应用程序迁移到Cloud Monitor(云监测)的情景所撰写的那样,在整个文件中,将会出现与舞会客户的一些比较.

## 安装

```sh
npm install @bonniernews/gcp-push-metrics
```

## 使用量

先看一看基本用案,再造出一个"倒计时"并递增.

```js
import {pushClient, cloudRunResourceProvider} from "@bonniernews/gcp-push-metrics";

const client = pushClient({ resourceProvider: cloudRunResourceProvider });

const counter = client.counter({ name: "num_requests" });
counter.inc();
```

在上述例子中,我们导入软件包并创建客户端。 为了创造一个客户 我们需要提供 [资源提供者](https://npmcn.com/package/%40bonniernews/gcp-push-metrics/#readme-resource-providers)。可以创建自定义的资源提供者,但这里我们使用由软件包提供的软件包.

然后我们开始创建一个名为"num requests"的计数器,并进行增量. 60秒后,客户端将尝试将单个时间序列推向"云监测API".

> 注:每一次 `pushClient` 它将创建一个新的实例,从而建立一个设置的Timeout循环,推动客户端收集的度量衡。 在大多数情况下,您只应该在您的应用程序中创建一个单一的客户端,并将其曝光为单通.

### 本地残疾

当本地运行应用程序时, 例如在开发环境中运行时, 您可能想要禁用向 Cloud Monitor API 推进的参数 。 这可以通过通过 `disabled: true` 致客户端:

```js
const client = pushClient({
  resourceProvider: cloudRunResourceProvider,
  disabled: process.env.NODE_ENV === "development"
});
```

## 柜台

计数器作为通用度量衡类型实施,报告的数值将持续增加。 让我们举个例子:

```js
const counter = client.counter({ name: "num_requests" });

setTimeout(() => {
    counter.inc();
    counter.inc();
}, 61 * 1000);

setTimeout(() => {
    counter.inc();
}, 121 * 1000);
```

60秒后,客户端将用"Custom.googleapis.com/num request"的公制来推动一个时间序列. 值会是 **0 个**。 。 。 .

120秒后,客户端将再次推动一个时间序列,这次是用值 **2个**。 。 。 .

180秒后,客户端将用 **3个** 作为价值.

240秒后,客户端将再次用 **3个** 作为价值.

## 高地语

高地是时间度量的点,既可以增加,也可以降低. 示例

```js
const gauge = client.gauge({ name: "requests_in_progress" });

setTimeout(() => {
    gauge.inc();
    gauge.inc();
}, 61 * 1000);

setTimeout(() => {
    gauge.dec();
}, 121 * 1000);
```

60秒后,客户端将用"custom.googleapis.com/requests in progress"的公尺来推动一个时间序列. 值会是 **0 个**。 。 。 .

120秒后,客户端将再次推动一个时间序列,这次是用值 **2个**。 。 。 .

180秒后,客户端将用 **1个** 作为价值.

240秒后,客户端将再次用 **1个** 作为价值.

## 摘要

汇总和计算观测值的百分位数。 观测到的值在每个间隔(60秒)之间被重置. 与计数器和计数器的汇总度量标准相反,只有在间隔期间至少有一次观测时才会发送. 示例

```js
const summary = client.summary({
    name: "response_time",
    percentiles: [0.5, 0.9]
});

setTimeout(() => {
    summary.observe(10);
    summary.observe(20);
    summary.observe(30);
}, 61 * 1000);
```

60秒后,客户会 **不发送任何时间序列** 由于没有观测结果.

120秒后客户端将推出两个时间序列. 两者都有"Custom.googleapis.com/response time"的公制类型,但它们的标签不同. 一个会被贴上标签 `percentile: 50` 和一个 `percentile: 90`第一个将拥有 **20国** 价值,后者将拥有 **30个** 作为价值.

180秒后,客户会再次出现 **不发送任何时间序列** 因为过去的时间间隔中没有观测结果.

> 说明: `prom-client` 也推动观测数量和所有观测的总和. 这个图书馆没有.

### 默认百分比

如果您在创建摘要时未指定百分位数, 则默认为 `[0.5, 0.9, 0.99]`。请注意,这与 `prom-client` 默认为 `[0.01, 0.05, 0.5, 0.9, 0.95, 0.99, 0.999]`。 。 。 .

### 计时器

由于摘要通常用于衡量执行时间或响应时间,摘要对象为观测持续时间提供了一种方便方法:

```js
const summary = client.summary({
    name: "response_time",
});

const end = summary.startTimer();

// Do something time consuming

end();
```

## 标签

所有改变度量衡值(counter.inc,summary.observe等)的方法都支持可选标签对象,可以包含一个或多个标签和值. 让我们举个例子:

```js
const counter = client.counter({ name: "num_requests" });

setTimeout(() => {
    counter.inc({ response_code: "2xx" });
    counter.inc({ response_code: "2xx" });
    counter.inc({ response_code: "3xx" });
}, 61 * 1000);
```

60秒后,客户端将用"Custom.googleapis.com/num requests"和"Custom.googleapis.com/num requests"来推出一个单个时间序列 **0 个** 作为价值.

一旦120秒通过客户端将推出3个时间序列. 三者都会有"Custom.googleapis.com/num requests"的"Custom.gogleapis.com/num requests"等类型,但标签不同. 绝对不会有标签 还有一个会 `{ response_code: "2xx" }` 作为标签和 **2个** 作为价值。 最后一个会 `{ response_code: "3xx" }` 作为标签和 **1个** 作为价值.

### 计数器和计数器的默认标签

正如我们在上述例子中所看到的那样,客户将推动时间序列,用于没有标签的已创建的计数器以及带有标签的递增计数器。 换言之,默认:

-   仅打算与标签一起使用的计数器(和计数器)仍然被作为时间序列来推而无标签.
-   当调用标签时 `inc` 时间序列只会被推后 `inc` 至少被调用过一次.

在创建计数器和计数器时,可以通过指定标签来改变这种行为. 为了禁用发送这些公制类型的无标签版本,我们可以用空标签对象创建它们,像这样:

```js
const counter = client.counter({ labels: {} });
```

我们还可以在前面指定已知的标签组合,像这样:

```js
const counter = client.counter({
    labels: {
        response_code: ["2xx", "3xx", "4xx", "5xx"]
    }
});
```

让我们来看看具体的例子:

```js
const counter = client.counter({
    labels: {
        response_code: ["2xx", "3xx", "4xx", "5xx"],
        source: ["internal", "cdn"]
    }
});

setTimeout(() => {
    counter.inc({ response_code: "2xx", source: "internal" });
    counter.inc({ response_code: "2xx", source: "internal" });
}, 61 * 1000);

setTimeout(() => {
    counter.inc();
    counter.inc({ response_code: "2xx", source: "unknown" });
}, 121 * 1000);
```

60秒后,客户端将总共推动 **十个** 时间序列,全部使用 **0 个** 作为价值。 每个时间序列都会被标注在我们创建计数器时指定的标签之一的组合中,例如: `{ response_code: "3xx", source: "cdn" }`,注意客户端不会发送没有标签的时间序列.

120后 客户会再次推 **十个** 时间序列。 贴上标签的那个 `{ response_code: "2xx", source: "internal" }` 现在有 **2个** 作为价值.

180秒后,客户会推 **十二个** 时间序列。 有十会同前. 另外两个是之前看不见的标签组合,意思是其中之一 `{ response_code: "2xx", source: "unknown" }` 作为标签和没有标签的标签.

## 资源提供者

在将衡量标准推向云监测时,必须指定 [资源类型](https://cloud.google.com/monitoring/api/resources)。本软件包在创建客户端时允许您指定“资源提供者”。 资源提供者是一个函数,它必须返回一个承诺,以解析具有两个属性的对象, `default` 财务报告和审定财务报表 `exit`。这些属性反过来必须包含有效的资源对象。 这个 `exit` 当客户端试图在 `SIGTERM` 发送到应用程序时 `default` 一个将用于所有其他请求.

最低限度的资源提供者可能看起来是这样:

```js
function globalResourceProvider() {
  return {
    exit: {
      type: "global",
      labels: {
        project_id: "myproject",
      },
    },
    default: {
      type: "global",
      labels: {
        project_id: "myproject",
      },
    },
  };
}
```

请注意,上述例子只有在从单一来源(即一舱)收集出度量衡时才会有效. 在更现实的情景中,资源应该包含一些能识别独特应用程序实例的内容,以确保被推倒的时间序列不会相冲突.

### 云运行资源提供者

装有预建资源供应商的软件包船 用于Cloud Run上的应用, `cloudRunResourceProvider`。该资源提供者将使用 [一般节点](https://cloud.google.com/monitoring/api/resources#tag_generic_node) 资源类型。 它以下列方式映射资源标签:

-   `project_id` - 从.. [容器实例元数据服务器](https://cloud.google.com/run/docs/reference/container-contract#metadata-server) `/computeMetadata/v1/project/project-id` 终点.
-   `location` - 取来并解析 [容器实例元数据服务器](https://cloud.google.com/run/docs/reference/container-contract#metadata-server) `/computeMetadata/v1/instance/region` 终点.
-   `namespace` - 从.. `K_SERVICE` 环境变量.
-   `node_id` - 从.. [容器实例元数据服务器](https://cloud.google.com/run/docs/reference/container-contract#metadata-server) `/computeMetadata/v1/instance/id` 终点 在那个 `exit` 资源 `-exit` 现附于 `node-id`。 。 。 .

## 最多200个时间序列

Cloud Monitoring API目前支持在单一API呼叫中最多200个时间序列. 这意味着目前这个软件包只能用200或更少的时间序列工作. 今后,我们可以实施功能,将更多的时间序列分成多个请求.

## 开发/包装

由于软件包是使用ES6模块建造的,我们还需要运送一个CommonJS dist. 这是以下列形式进行的: `index.cjs` 使用 `npm run dist`。该命令应总是在 `npm publish`。 。 。 .

## 信贷

计算百分位数的功能被复制并修改自 [节点统计-升](https://github.com/brycebaril/node-stats-lite)。 。 。 .

## 常见问题

### @bonniernews/gcp-push-metrics 是什么？

将定制度量衡推向谷歌云监测\.

### 如何安装 @bonniernews/gcp-push-metrics？

在项目目录运行 npm install @bonniernews/gcp-push-metrics，或使用 pnpm add / yarn add / bun add。

### @bonniernews/gcp-push-metrics 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/bonniernews\_\_gcp-push-metrics 是否存在。

### @bonniernews/gcp-push-metrics 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @bonniernews/gcp-push-metrics 需要什么版本的 Node\.js？

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

### @bonniernews/gcp-push-metrics 可以商用吗？

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

### @bonniernews/gcp-push-metrics 的下载量有多少？

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

### @bonniernews/gcp-push-metrics 还在维护吗？

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