设置 Node.js 版 Cloud Logging

对于 Node.js 应用，系统会为常用的 Winston 和 Bunyan 日志记录库维护插件。Winston 是一个通用库， 实现各种日志格式化程序和传输服务 Bunyan 专门用于结构化 JSON 日志，支持通过管道传输到 Bunyan 命令行来设置日志格式。

您还可以将 Logging 客户端库用于 直接使用 Node.js，或 创建您自己的与首选日志记录库的集成。 例如，您可以使用 Pino 日志框架示例。

使用 Compute Engine 虚拟机 (VM) 实例上的 Winston 或 Bunyan。

准备工作

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  3. Make sure that billing is enabled for your Google Cloud project.

  4. Enable the Cloud Logging API.

    Enable the API

    5.

  5. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  6. Make sure that billing is enabled for your Google Cloud project.

  7. Enable the Cloud Logging API.

    Enable the API

    8.
  8. 准备您的 Node.js 开发环境。

    转到 Node.js 设置指南

配置日志记录

本部分介绍了如何安装和配置 Winston 和 Bunyan 日志记录库的插件。对于 Bunyan，提供了有关如何将 Bunyan 与 Node.js Express 应用搭配使用的信息。

您可以使用其他库或框架。例如，您可以使用 Pino 日志框架。如需查看使用 OpenTelemetry 收集指标和跟踪记录数据以及使用 Pino 日志框架收集日志数据的示例代码，请参阅使用 Node.js 生成跟踪记录和指标。如果您使用 Pino，则必须实现 Pino 之间的映射， 以及 Cloud Logging 使用的严重级别。如需查看示例代码，请参阅 映射 Pino 日志级别。

安装并配置 Winston 插件

Cloud Logging 为 Winston Node.js Logging 库提供了一个插件。适用于 Winston 的 Logging 插件提供了一个更简单的更高层级，用于处理 Logging。

如需安装和配置 Winston 插件，请执行以下操作：

  1. 如需安装 Logging，请执行以下操作： Winston 插件，请使用 npm：

    npm install --save @google-cloud/logging-winston winston

  2. 导入插件并将其添加到 Winston 配置：

    const winston = require('winston');

// Imports the Google Cloud client library for Winston
const {LoggingWinston} = require('@google-cloud/logging-winston');

const loggingWinston = new LoggingWinston();

// Create a Winston logger that streams to Cloud Logging
// Logs will be written to: "projects/YOUR_PROJECT_ID/logs/winston_log"
const logger = winston.createLogger({
  level: 'info',
  transports: [
    new winston.transports.Console(),
    // Add Cloud Logging
    loggingWinston,
  ],
});

// Writes some log entries
logger.error('warp nacelles offline');
logger.info('shields at 99%');

  3. 配置插件。

    您可以使用 Node.js 版 Cloud Logging API Cloud 客户端库支持的相同配置选项来自定义 Winston 插件的行为。这些选项可以在传递到插件的 options 对象中传递， 构造函数。

安装并配置 Bunyan 插件

Cloud Logging 为 Bunyan Node.js Logging 库提供了一个插件。适用于 Bunyan 的 Logging 插件提供了一个更简单的更高层级，用于处理 Logging。

如需安装和配置 Bunyan 插件，请执行以下操作：

  1. 如需安装 Logging，请执行以下操作： Bunyan 插件，请使用 npm：

    npm install --save bunyan @google-cloud/logging-bunyan

  2. 导入插件并将其添加到 Bunyan 配置：

    const bunyan = require('bunyan');

// Imports the Google Cloud client library for Bunyan
const {LoggingBunyan} = require('@google-cloud/logging-bunyan');

// Creates a Bunyan Cloud Logging client
const loggingBunyan = new LoggingBunyan();

// Create a Bunyan logger that streams to Cloud Logging
// Logs will be written to: "projects/YOUR_PROJECT_ID/logs/bunyan_log"
const logger = bunyan.createLogger({
  // The JSON payload of the log as it appears in Cloud Logging
  // will contain "name": "my-service"
  name: 'my-service',
  streams: [
    // Log to the console at 'info' and above
    {stream: process.stdout, level: 'info'},
    // And log to Cloud Logging, logging at 'info' and above
    loggingBunyan.stream('info'),
  ],
});

// Writes some log entries
logger.error('warp nacelles offline');
logger.info('shields at 99%');

  3. 配置您的插件。

    您可以使用 Node.js 版 Cloud Logging API Cloud 客户端库支持的相同配置选项来自定义 Bunyan 插件的行为。这些选项可以在传递到插件的 options 对象中传递， 构造函数。

使用 Bunyan 和 Express

您可以在 Node.js Express 应用中设置和使用 Bunyan 与 Logging。

// Imports the Google Cloud client library for Bunyan.
const lb = require('@google-cloud/logging-bunyan');

// Import express module and create an http server.
const express = require('express');

async function startServer() {
  const {logger, mw} = await lb.express.middleware({
    logName: 'samples_express',
  });
  const app = express();

  // Install the logging middleware. This ensures that a Bunyan-style `log`
  // function is available on the `request` object. This should be the very
  // first middleware you attach to your app.
  app.use(mw);

  // Setup an http route and a route handler.
  app.get('/', (req, res) => {
    // `req.log` can be used as a bunyan style log method. All logs generated
    // using `req.log` use the current request context. That is, all logs
    // corresponding to a specific request will be bundled in the Stackdriver
    // UI.
    req.log.info('this is an info log message');
    res.send('hello world');
  });

  const port = process.env.PORT || 8080;

  // `logger` can be used as a global logger, one not correlated to any specific
  // request.
  logger.info({port}, 'bonjour');

  // Start listening on the http server.
  const server = app.listen(port, () => {
    console.log(`http server listening on port ${port}`);
  });

  app.get('/shutdown', (req, res) => {
    res.sendStatus(200);
    server.close();
  });
}

startServer();

如需了解安装详情，请参阅 Node.js 版 Cloud Logging 库的文档。您还可以使用问题跟踪器来报告问题。

使用 Cloud Logging 客户端库写入日志

如需了解如何使用 Cloud Logging 客户端库， 请参阅 Cloud Logging 客户端库。

在 Google Cloud 上运行

如需让应用使用 Node.js 版 Cloud Logging 库写入日志，底层资源的服务账号必须具有 Logs Writer (roles/logging.logWriter) IAM 角色。大多数 Google Cloud 环境都会自动将默认服务账号配置为具有此角色。

App Engine

系统会自动为 App Engine 启用 Cloud Logging，并且应用的默认服务账号默认拥有 IAM 权限以写入日志条目。

如需从应用写入日志条目，我们建议您使用 Bunyan 或 Winston，如本页所述。

如需了解详情，请参阅写入和查看日志。

Google Kubernetes Engine (GKE)

GKE 会自动向默认服务账号授予 Logs Writer (roles/logging.logWriter) IAM 角色。如果您使用 适用于 GKE 的工作负载身份联合 此默认服务账号，以允许工作负载 Google Cloud API，则无需额外配置。 不过，如果您将适用于 GKE 的工作负载身份联合与自定义 IAM 服务账号搭配使用，请确保自定义服务账号具有 Logs Writer (roles/logging.logWriter) 角色。

如果需要，您还可以在创建集群时使用以下命令添加 logging.write 访问权限范围：

gcloud container clusters create example-cluster-name \
    --scopes https://www.googleapis.com/auth/logging.write

Compute Engine

使用 Compute Engine 虚拟机实例时，请为每个实例添加 cloud-platform 访问权限范围。通过 Google Cloud 控制台，您可以在身份和 API 访问权限部分执行此操作 点击创建实例面板。请使用 Compute Engine 默认服务账号或您选用的其他服务账号，并在身份和 API 访问权限部分勾选允许所有 Cloud APIs 的全面访问权限。无论您选择哪个服务账号，都请确保已在 Google Cloud 控制台的 IAM 和管理部分向该服务账号授予 Logs Writer 角色。

Cloud Run 函数

Cloud Run 函数可授予 Logs Writer 角色 默认情况。

无需明确提供凭据即可使用 Node.js 版 Cloud Logging 库。

Cloud Run 函数已配置为自动使用 Cloud Logging。

在本地和其他位置运行

如需在 Google Cloud 外部使用 Node.js 版 Cloud Logging 库， 包括在您自己的工作站、数据中心的 或其他云服务提供商的虚拟机实例上，则必须 提供您的 Google Cloud 项目 ID 和相应的 服务账号 登录到 Node.js 版 Cloud Logging 库。

对于现有服务账号，请执行以下操作：

  1. 向服务账号授予 Logs Writer (roles/logging.logWriter) IAM 角色。如需详细了解 IAM 请参阅访问权限控制。

  2. 设置应用默认凭据。

如果您没有服务账号，请创建一个。有关 此过程，请参阅创建服务账号。

如需了解有关可用于身份验证的方法的一般信息，请参阅 术语：服务账号。

使用 Winston：

// Imports the Google Cloud client library for Winston
const {LoggingWinston} = require('@google-cloud/logging-winston');

// Creates a client
const loggingWinston = new LoggingWinston({
  projectId: 'your-project-id',
  keyFilename: '/path/to/key.json',
});

使用 Bunyan：

// Imports the Google Cloud client library for Bunyan
const {LoggingBunyan} = require('@google-cloud/logging-bunyan');

// Creates a client
const loggingBunyan = new LoggingBunyan({
  projectId: 'your-project-id',
  keyFilename: '/path/to/key.json',
});

查看日志

在 Google Cloud 控制台中，转到 Logs Explorer 页面。

前往 Logs Explorer

如果您使用搜索栏查找此页面，请选择子标题为 Logging 的结果。

在日志浏览器中，您必须指定一个或多个资源，但资源的选择并不那么显而易见。以下是帮助您上手的一些提示：

  • 如果您将把应用部署到 App Engine 或者您使用的是 App Engine 专用的库，请将资源设置为 GAE 应用。

  • 如果您将在 Compute Engine 上部署应用，请将资源设置为 GCE 虚拟机实例。

  • 如果您要在 Google Kubernetes Engine 上部署应用，则集群的日志记录配置将确定日志条目的资源类型。有关 关于旧版 Google Cloud 可观测性与 Google Cloud 可观测性 Kubernetes Monitoring 解决方案，以及这些选项将如何影响 资源类型，请参阅 迁移到 Google Cloud Observability Kubernetes Monitoring。

  • 如果您的应用直接使用 Cloud Logging API，则资源取决于该 API 和您的配置。例如，在您的应用中，您可以指定资源或使用默认资源。

  • 如果您在日志浏览器中没有看到任何日志，若要查看所有日志条目，请切换到高级查询模式并使用空查询。

    1. 如需切换到高级查询模式，请点击日志浏览器顶部的菜单 (▾)，然后选择转换为高级过滤条件。
    2. 清除过滤条件框中显示的内容。
    3. 点击提交过滤条件。

    您可以检查各个条目以找出您的资源。

如需了解详情，请参阅使用日志浏览器。