Cloud Logging の Node.js 向け設定

Node.js アプリケーションでは、一般的な BunyanWinston のロギング ライブラリのプラグインが維持されます。

Winston は汎用のライブラリで、さまざまなログ フォーマッタとトランスポートを実装します。

Bunyan は構造化 JSON ログに特化しています。ログの書式設定は、Bunyan コマンドラインにパイプをつなぐことで実行できます。

Node.js 用 Logging クライアント ライブラリを直接使用することも、好みのロギング ライブラリと独自の統合を作成することもできます。

Bunyan と Winston のライブラリを Compute Engine VM インスタンスで使用するために、Logging エージェントをインストールする必要はありません。

準備

  1. Google Cloud アカウントにログインします。Google Cloud を初めて使用する場合は、アカウントを作成して、実際のシナリオでの Google プロダクトのパフォーマンスを評価してください。新規のお客様には、ワークロードの実行、テスト、デプロイができる無料クレジット $300 分を差し上げます。
  2. Google Cloud Console の [プロジェクト セレクタ] ページで、Google Cloud プロジェクトを選択または作成します。

    プロジェクト セレクタに移動

  3. Cloud プロジェクトに対して課金が有効になっていることを確認します。プロジェクトに対して課金が有効になっていることを確認する方法を学習する

  4. Cloud Logging API を有効にします。

    API を有効にする

  5. Node.js 開発用の環境を準備します。

    Node.js 設定ガイドに移動

Bunyan を使用する場合

Cloud Logging には、Bunyan 向けの Node.js 用 Logging ライブラリのプラグインが用意されています。この Bunyan 向けの Logging プラグインによって、Logging を使用する際により簡単で高レベルのレイヤが提供されます。

プラグインのインストール

  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%');

プラグインの構成

Bunyan プラグインの動作をカスタマイズするには、Cloud Logging API の Node.js 用 Cloud クライアント ライブラリによってサポートされる構成オプションと同じオプションを使用します。これらのオプションは、プラグインのコンストラクタに渡される options オブジェクトで渡すことができます。

Bunyan と Express を使用する

Node.js Express アプリケーションで Logging を使用して Bunyan をセットアップし、使用できます。

// 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();

Winston を使用する場合

Cloud Logging には、Winston 向けの Node.js 用 Logging ライブラリのプラグインが用意されています。この Winston 向けの Logging プラグインによって、Logging を使用する際により簡単で高レベルのレイヤが提供されます。

プラグインのインストール

  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 Stackdriver 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 Stackdriver Logging
        loggingWinston,
      ],
    });
    
    // Writes some log entries
    logger.error('warp nacelles offline');
    logger.info('shields at 99%');

プラグインの構成

Winston プラグインの動作をカスタマイズするには、Cloud Logging API の Node.js 用 Cloud クライアント ライブラリによってサポートされる構成オプションと同じオプションを使用します。これらのオプションは、プラグインのコンストラクタに渡される options オブジェクトで渡すことができます。

インストールの詳細については、Node.js 用 Cloud Logging ライブラリのドキュメントをご覧ください。公開バグトラッカーを使用して問題を報告することもできます。

Cloud クライアント ライブラリを直接使用する

Cloud Logging の Node.js 用 Cloud クライアント ライブラリを直接使用する方法については、Cloud Logging クライアント ライブラリをご覧ください。

Google Cloud での実行

Node.js 用 Cloud Logging ライブラリを使用するには、Google Cloud での IAM ログ書き込みロールが必要です。ほとんどの Google Cloud 環境では、このロールがデフォルトで付与されています。

App Engine

App Engine では、デフォルトでログ書き込み役割が付与されます。

Node.js 用 Cloud Logging ライブラリは、明示的に認証情報を提示しなくても使用できます。

App Engine のアプリケーションでは、Cloud Logging が自動的に有効になります。特別な設定は必要ありません。

Google Kubernetes Engine

Google Kubernetes Engine では、クラスタの作成時に logging.write アクセス スコープを追加する必要があります。

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

Compute Engine

Compute Engine VM インスタンスを使用する場合は、各インスタンスに cloud-platform アクセス スコープを追加します。Google Cloud Console から新しいインスタンスを作成する場合は、[インスタンスの作成] パネルの [ID と API へのアクセス] のセクションで作成します。Compute Engine のデフォルト サービス アカウントまたは別のサービス アカウントを使用し、[ID と API へのアクセス] セクションの [すべての Cloud API に完全アクセス権を許可] を選択します。どのサービス アカウントを選択する場合でも、Cloud Console の [IAM と管理] でログ書き込みロールが付与されていることを確認してください。

Cloud Functions

Cloud Functions では、デフォルトでログ書き込み役割が付与されます。

Node.js 用 Cloud Logging ライブラリは、明示的に認証情報を提示しなくても使用できます。

Cloud Functions は、自動的に Cloud Logging を使用するように構成されています。

ローカルやその他の場所での実行

自分のワークステーション、データセンターのコンピュータ、別のクラウド プロバイダの VM インスタンスでライブラリを実行するなど、Google Cloud の外部で Node.js 用 Cloud Logging ライブラリを使用するには、Google Cloud プロジェクト ID と適切なサービス アカウント認証情報を Node.js 用 Cloud Logging ライブラリに直接提供する必要があります。

サービス アカウントの認証情報は手動で作成して取得できます。[ロール] フィールドを指定する場合は、ログ書き込み役割を使用します。Identity and Access Management のロールの詳細については、アクセス制御ガイドをご覧ください。

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',
});

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',
});

ログの表示

デプロイ後、ログ エクスプローラでログを表示できます。

ログ エクスプローラに移動

ログ エクスプローラでは 1 つ以上のリソースを指定する必要がありますが、リソースの選択が明確でない場合があります。その場合は、次のヒントを参考にしてください。

  • アプリケーションを App Engine にデプロイしている場合や、App Engine 固有のライブラリを使用している場合は、リソースを GAE アプリケーションに設定します。

  • アプリケーションを Compute Engine にデプロイしている場合は、リソースを GCE VM インスタンスに設定します。

  • アプリケーションを Google Kubernetes Engine にデプロイしている場合は、クラスタのロギング構成に応じてログエントリのリソースタイプが異なります。レガシー Google Cloud のオペレーション スイートと Google Cloud のオペレーション スイート Kubernetes Monitoring ソリューションの詳細、およびこれらのオプションがリソースタイプに与える影響については、Google Cloud のオペレーション スイート Kubernetes Monitoring への移行をご覧ください。

  • アプリケーションが Cloud Logging API を直接使用している場合、リソースは API と構成に依存します。たとえば、アプリケーションでリソースを指定することも、デフォルトのリソースを使用することもできます。

  • ログ エクスプローラにログが表示されない場合に、すべてのログエントリを表示するには、高度なクエリモードに切り替えて空のクエリを使用します。

    1. 高度なクエリモードに切り替えるには、ログ エクスプローラの上部にあるメニュー(▾)をクリックし、[高度なフィルタに変換] を選択します。
    2. フィルタ ボックスに表示されているコンテンツをクリアします。
    3. [フィルタを送信] をクリックします。

    個々のエントリを調べてリソースを特定します。

詳細については、ログの表示高度なログクエリをご覧ください。