# @google-cloud/pino-logging-gcp-config 中文文档

规范地址：https://npmcn.com/package/%40google-cloud/pino-logging-gcp-config/

版本：1\.3\.6
npm 元数据更新时间：2026-09-02T10:52:09.025Z
中文译文更新时间：2026-11-16T19:41:06.695Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40google-cloud/pino-logging-gcp-config
原文对照：https://npmcn.com/package/%40google-cloud/pino-logging-gcp-config/?lang=original
项目主页：https://github.com/GoogleCloudPlatform/cloud-solutions#readme
源码仓库：https://github.com/GoogleCloudPlatform/cloud-solutions

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

- 包体积（解压后）：456 kB，18 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20\.20\.2
- 运行依赖：2 个
- 首次发布：2024-08-06T11:54:23.197Z
- 最新版本发布：2026-09-02T10:52:08.824Z
- 近 30 天下载量：1823332（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：14（近 12 个月 4 个）

## 中文简介

创建基本 Pino LoggerConfig 支持 Google Cloud 结构化日志的模块

## 安装

```sh
npm install @google-cloud/pino-logging-gcp-config
```

也可以使用：`pnpm add @google-cloud/pino-logging-gcp-config`、`yarn add @google-cloud/pino-logging-gcp-config`、`bun add @google-cloud/pino-logging-gcp-config`

## README

# Pino Google 节点云日志配置

此库包含生成 Pino 配置的代码, 用于输出 [JSON 用于谷歌云日志的结构日志](https://cloud.google.com/logging/docs/structured-logging)。 。 。 .

用于获取日志的 Google Cloud 服务 stdout( 如 Cloud Run, Cloud Run 函数和 Google Kubernetes 引擎) ,以便记录格式正确 [谷歌云记录](https://cloud.google.com/logging/docs)。然后允许 按日志级别过滤,将结构化数据纳入日志的能力,以及 报告有堆栈痕迹的错误 [谷歌云出错报告](https://cloud.google.com/error-reporting/docs)

## 特征

-   将 Pino 日志级别转换为 Google 云日志级别 .
-   用途 `message` 改为 `msg` 为消息密钥.
-   在 a 中添加毫秒角时间戳 [由 Google 云日志识别的格式](https://cloud.google.com/logging/docs/agent/logging/configuration#timestamp-processing), (中文(简体) ), 例如: `"timestamp":{"seconds":1445470140,"nanos":123000000}`。 。 。 .
-   添加顺序 [插入图像](https://cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry#FIELDS.insert_id) 以确保有相同时间戳的日志信息被正确命令.
-   包含错误对象的日志有: [堆栈属性( t)](https://cloud.google.com/error-reporting/docs/formatting-error-messages#log-error) 设置,使错误被传送到 Google Cloud 错误报告.
-   包括a [服务内容](https://cloud.google.com/error-reporting/reference/rest/v1beta1/ServiceContext) google Cloud 错误报告日志中的对象.
-   映射 OpenTelection 属性 `span_id`, (中文(简体) ), `trace_id`, (中文(简体) ), `trace_flags` 页:1 等值单位 [谷歌云日志字段](https://cloud.google.com/logging/docs/structured-logging#structured_logging_special_fields)。 。 。 .
-   用户定义 `formatters.log` 总是在GCP格式化之前按原样执行.

## 示例用途

### 1: 安装所需依赖关系

```bash
npm install --save pino @google-cloud/pino-logging-gcp-config
```

### 2: 导入模块

使用 Typescription / ES 模块 :

```typescript
import as pino from 'pino';
import {createGcpLoggingPinoConfig} from '@google-cloud/pino-logging-gcp-config';
```

使用 Javascript / commonJS :

```javascript
const pino = require('pino');
const {createGcpLoggingPinoConfig} = require('@google-cloud/pino-logging-gcp-config');
```

### 3: 初始化 Pino Logger 与 GCP 日志配置

这个 [服务内容](https://cloud.google.com/error-reporting/reference/rest/v1beta1/ServiceContext) (使用时间: [云出错报告](https://cloud.google.com/error-reporting/docs/formatting-error-messages)(中文(简体) ) 可以手动指定, 以及任何 Pino 日志选项, 如 默认日志级别 :

```javascript
const logger = pino.pino(
  createGcpLoggingPinoConfig(
    {
      serviceContext: {
        service: 'my-service',
        version: '1.2.3',
      },
    },
    {
      // set Pino log level to 'debug'
      level: 'debug',
    }
  )
);
```

或使用默认值,服务名称由GCP自动检测 环境:

```javascript
const logger = pino.pino(createGcpLoggingPinoConfig());
```

### 4: 正常使用 Pino 记录信件并堆放痕迹

```javascript
// Simple log message:
logger.info('hello world');

// Logging an exception:
const err = new Error('some exception');
logger.error(err, 'Caught an exception: %s', err);

// Logging with some additional properties, which can be used as searchable
// values in Cloud Logging:
logger.debug(
  {
    someProperties: 'some value',
  },
  'logging with extra properties'
);
```

## 示例输出

每个日志消息将作为JSON文本的一行输出. 以下产出 已重新调整为多行,以明确.

```json
  {
    "severity": "INFO",
    "level": 30,
    "timestamp": {
      "seconds": 1730802506,
      "nanos": 375000000
    },
    "pid": 601658,
    "hostname": "myHostName",
    "logging.googleapis.com/insertId": "..........40FL7.zwt0uNYGdcmFiUn_",
    "serviceContext": {
      "service": "my-service",
      "version": "1.2.3"
    },
    "message": "hello world"
  }
  {
    "severity": "ERROR",
    "level": 50,
    "timestamp": {
      "seconds": 1730802506,
      "nanos": 377000000
    },
    "pid": 601658,
    "hostname": "myHostName",
    "err": {
      "type": "Error",
      "message": "some exception",
      "stack": "Error: some exception\n    at Object.<anonymous> (/some/dir/pino-logging-gcp-config/build/src/example.js:14:13)\n    at Module._compile (node:internal/modules/cjs/loader:1434:14)\n    at Module._extensions..js (node:internal/modules/cjs/loader:1518:10)\n    at Module.load (node:internal/modules/cjs/loader:1249:32)\n    at Module._load (node:internal/modules/cjs/loader:1065:12)\n    at Function.executeUserEntryPoint [as runMain] (node:internal/modules/run_main:158:12)\n    at node:internal/main/run_main_module:30:49"
    },
    "logging.googleapis.com/insertId": "..........80FL7.zwt0uNYGdcmFiUn_",
    "serviceContext": {
      "service": "my-service",
      "version": "1.2.3"
    },
    "stack_trace": "Error: some exception\n    at Object.<anonymous> (/some/dir/pino-logging-gcp-config/build/src/example.js:14:13)\n    at Module._compile (node:internal/modules/cjs/loader:1434:14)\n    at Module._extensions..js (node:internal/modules/cjs/loader:1518:10)\n    at Module.load (node:internal/modules/cjs/loader:1249:32)\n    at Module._load (node:internal/modules/cjs/loader:1065:12)\n    at Function.executeUserEntryPoint [as runMain] (node:internal/modules/run_main:158:12)\n    at node:internal/main/run_main_module:30:49",
    "message": "Caught an exception: Error: some exception"
  }
  {
    "severity": "DEBUG",
    "level": 20,
    "timestamp": {
      "seconds": 1730802506,
      "nanos": 378000000
    },
    "pid": 601658,
    "hostname": "myHostName",
    "someProperties": "some value",
    "logging.googleapis.com/insertId": "..........C0FL7.zwt0uNYGdcmFiUn_",
    "serviceContext": {
      "service": "my-service",
      "version": "1.2.3"
    },
    "message": "logging with extra properties"
  }
```

这个输出将像这个截图一样出现在 Cloud Looking (第二个和 第三个日志信件已经扩展, 以显示堆栈跟踪和附加 日志属性)

![Screenshot from Cloud Logging](https://npmcn.com/package/%40google-cloud/pino-logging-gcp-config/images/logging-screenshot.png)

带有堆栈追踪的错误也会在 Cloud Error Reporting 中出现, 与 在服务Context中指定的服务名称和版本.

![Screenshot from Cloud Error Reporting](https://npmcn.com/package/%40google-cloud/pino-logging-gcp-config/images/error-reporting-screenshot.png)

## 常见问题

### @google-cloud/pino-logging-gcp-config 是什么？

创建基本 Pino LoggerConfig 支持 Google Cloud 结构化日志的模块

### 如何安装 @google-cloud/pino-logging-gcp-config？

在项目目录运行 npm install @google-cloud/pino-logging-gcp-config，或使用 pnpm add / yarn add / bun add。

### @google-cloud/pino-logging-gcp-config 支持 TypeScript 吗？

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

### @google-cloud/pino-logging-gcp-config 支持 ESM 还是 CommonJS？

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

### @google-cloud/pino-logging-gcp-config 需要什么版本的 Node\.js？

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

### @google-cloud/pino-logging-gcp-config 可以商用吗？

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

### @google-cloud/pino-logging-gcp-config 的下载量有多少？

根据 npm 官方下载统计，@google-cloud/pino-logging-gcp-config 在 2026/10/17 – 2026/11/15 这 30 天内被下载 1,823,332 次，日均约 60,778 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @google-cloud/pino-logging-gcp-config 还在维护吗？

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

