ログエントリのストリーミングとライブ テーリング

このドキュメントでは、ストリーミングとライブ テーリングを使用してログエントリをリアルタイムで表示する方法について説明します。ログのストリーミングを使用すると、ログエントリをリアルタイムで表示できます。これは、ログ エクスプローラで使用できます。 ライブ テーリングによってログエントリをリアルタイムで表示できます。これは、gcloud CLI コマンド gcloud alpha logging tail または Cloud Logging API メソッド entries.tail として使用できます。

ログ エクスプローラ、gcloud logging read、または API メソッド entries.list を使用してログを表示、分析すると、Cloud Logging が保存したログエントリが表示されます。ログエントリをストリーミングまたはライブ テーリングする場合、アプリケーションが Cloud Logging API にログエントリを書き込むと、ログエントリが表示されます。

ログ エクスプローラでログをストリームする

ログ エクスプローラでは、ログのストリーミングを使用してログデータをリアルタイムで表示できます。ログのストリーミングを使用する場合は、クエリに一致するログのみをストリーミングするようにクエリを追加できます。ログをストリーミングする手順は次のとおりです。

  1. Google Cloud コンソールで、[ログ エクスプローラ] ページに移動します。

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

    検索バーを使用してこのページを検索する場合は、小見出しが [Logging] の結果を選択します。

  2. [Query] フィールドにクエリを入力し、[Stream logs] をクリックします。

    Logging がログデータを書き込むと、[クエリ結果] ペインにクエリに一致するログのみが表示されます。クエリを指定しない場合、Logging には最近保存されたログエントリが表示されます。ログは、ログパネルでスクロールバーを選択するまでストリーミングされ続けます。ストリーミングが停止すると、[ストリーミングを再開] ボタンが表示されます。

    クエリの詳細については、ログ エクスプローラでクエリを作成するをご覧ください。

Google Cloud CLI でライブ テーリングを使用する

ライブ テーリングを使用すると、Google Cloud CLI または Cloud Logging API を使用して、Cloud Logging によって書き込まれたログエントリをリアルタイムで表示できます。

フィールド レベルのアクセス制御を使用したログバケットではライブ テーリングはサポートされていませんが、ログ エクスプローラでこれらのバケットのログをストリーミングできます。

ライブ テーリングのための API メソッドについては、entries.tail メソッドをご覧ください。

gcloud alpha logging tail のインストール

gcloud alpha logging tail を使用するには、Python 3 と grpcio Python パッケージをインストールしている必要があります。

Python をインストールする手順については、Python のページをご覧ください。grpcio パッケージのインストールに必要な Python パッケージ マネージャー pip をインストールする手順については、Python パッケージ インストーラのページをご覧ください。

次の手順に沿って gcloud alpha logging tail をインストールします。

  1. Google Cloud CLI がインストールされていることを確認します。Google Cloud CLI をインストールする手順については、Google Cloud CLI のインストールをご覧ください。

  2. gcloud CLI のバージョン 302.0.0 以降を使用していることを確認します。

    gcloud version
    

    gcloud CLI の更新手順については、gcloud components update をご覧ください。

  3. gcloud CLI アルファ版コンポーネントをインストールします。

    gcloud components install alpha
    
  4. MacOS、Linux、Cloud Shell のユーザーの場合:

    1. gRPC クライアント ライブラリをインストールします。

       sudo pip3 install grpcio
      
    2. 環境変数 CLOUDSDK_PYTHON_SITEPACKAGES を任意の値に設定します。

       export CLOUDSDK_PYTHON_SITEPACKAGES=1
      
  5. Google Cloud プロジェクト ID を設定して認証するには、次のコマンドを使用します。

    gcloud config set project PROJECT_ID
    gcloud auth login
    

    プロジェクト ID を取得するには、プロジェクトの作成と管理をご覧ください。

  6. 次のコマンドを実行して、gcloud alpha logging tail がインストールされていることを確認します。

    gcloud alpha logging tail
    

    コマンドによって、次のメッセージが表示されます。

    Initializing tail session.

    これで、Logging がログを書き込むと、Google Cloud プロジェクトのログエントリが表示されるようになりました。

    ライブテーリング セッション中のログエントリ。

ライブ テーリングの使用について詳しくは、gcloud alpha logging tail リファレンス ガイドをご覧ください。

バッファリングと順序付け

Logging は時系列順以外のログエントリを受信できることから、ライブ テーリングにはログエントリについて、書き込み時に表示する場合と昇順で表示する場合との間でトレードオフのバランスを取ることができるよう、バッファ時間の設定も用意されています。バッファ時間は 060 秒の間で設定できます。

バッファ時間の次の特性に留意してください。

  • デフォルトのバッファ時間は 2 秒です。

  • Logging によって、バッファ時間枠内のログエントリのログバケットへの書き込みが遅延されます。

  • ログエントリがバッファ時間枠の範囲外に書き込まれると、Logging は受信時にログエントリを返します。

バッファ時間を構成すると、ログを書き込み時に表示する場合と、エントリを順不同で表示する場合との間でトレードオフを行うことになります。

バッファ時間 トレードオフ
0 最新のログエントリが返されるものの、順不動になっている可能性が高くなります。
60 返されたエントリが表示されるまでに 60 秒間の遅延が発生。ただし、ほとんどのログは昇順で返されます。

上限と割り当て

次の表に、ライブ テーリングの上限と割り当てを示します。

上限と割り当て
1 分あたりに返されるエントリ数 60,000 件
フィルタと一致するエントリが 60,000 件を超える場合、Logging はレスポンス内のエントリ数を返します。
Google Cloud プロジェクトあたりのオープンなライブ テーリング セッション数 10

クライアントの制限事項

大量のエントリを高速に書き込む Google Cloud プロジェクトでは、クライアントが、作成中のエントリを書き込まれてすぐには使用できなくなることがあります。この場合、Logging は最新のエントリを優先して、送信されるエントリの合計数を制限します。Logging は、テール セッションの最後に、クライアントの制限により表示されなかったエントリの数を返します。

クライアント ライブラリでライブ テーリングを使用する

ライブ テーリングを使用することで、Cloud Logging によってログエントリが書き込まれると、リアルタイムでログエントリを表示できます。ライブ テーリングのための API メソッドについては、entries.tail メソッドをご覧ください。

フィールド レベルのアクセス制御を使用したログバケットではライブ テーリングはサポートされていませんが、ログ エクスプローラでこれらのバケットのログをストリーミングできます。

この例では、特定のロガーのライブ テーリング ログエントリについて説明します。

Go

Logging 用のクライアント ライブラリをインストールして使用する方法については、Logging クライアント ライブラリをご覧ください。

Logging への認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。

import (
	"context"
	"fmt"
	"io"

	logging "cloud.google.com/go/logging/apiv2"
	"cloud.google.com/go/logging/apiv2/loggingpb"
)

// tailLogs creates a channel to stream log entries that were recently ingested for a project
func tailLogs(projectID string) error {
	// projectID := "your_project_id"

	ctx := context.Background()
	client, err := logging.NewClient(ctx)
	if err != nil {
		return fmt.Errorf("NewClient error: %w", err)
	}
	defer client.Close()

	stream, err := client.TailLogEntries(ctx)
	if err != nil {
		return fmt.Errorf("TailLogEntries error: %w", err)
	}
	defer stream.CloseSend()

	req := &loggingpb.TailLogEntriesRequest{
		ResourceNames: []string{
			"projects/" + projectID,
		},
	}
	if err := stream.Send(req); err != nil {
		return fmt.Errorf("stream.Send error: %w", err)
	}

	// read and print two or more streamed log entries
	for counter := 0; counter < 2; {
		resp, err := stream.Recv()
		if err == io.EOF {
			break
		}
		if err != nil {
			return fmt.Errorf("stream.Recv error: %w", err)
		}
		fmt.Printf("received:\n%v\n", resp)
		if resp.Entries != nil {
			counter += len(resp.Entries)
		}
	}
	return nil
}

Java

Logging 用のクライアント ライブラリをインストールして使用する方法については、Logging クライアント ライブラリをご覧ください。

Logging への認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。

import com.google.cloud.logging.LogEntry;
import com.google.cloud.logging.LogEntryServerStream;
import com.google.cloud.logging.Logging;
import com.google.cloud.logging.Logging.TailOption;
import com.google.cloud.logging.LoggingOptions;

public class TailLogEntries {

  public static void main(String[] args) throws Exception {
    // TODO(developer): Optionally provide the logname as an argument.
    String logName = args.length > 0 ? args[0] : "";

    LoggingOptions options = LoggingOptions.getDefaultInstance();
    try (Logging logging = options.getService()) {

      // Optionally compose a filter to tail log entries only from specific log
      LogEntryServerStream stream;

      if (logName != "") {
        stream =
            logging.tailLogEntries(
                TailOption.filter(
                    "logName=projects/" + options.getProjectId() + "/logs/" + logName));
      } else {
        stream = logging.tailLogEntries();
      }
      System.out.println("start streaming..");
      for (LogEntry log : stream) {
        System.out.println(log);
        // cancel infinite streaming after receiving first entry
        stream.cancel();
      }
    }
  }
}

Node.js

Logging 用のクライアント ライブラリをインストールして使用する方法については、Logging クライアント ライブラリをご覧ください。

Logging への認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。

const {Logging} = require('@google-cloud/logging');
const logging = new Logging();

/**
 * TODO(developer): Replace logName with the name of your log.
 */
const log = logging.log(logName);
console.log('running tail log entries test');

const stream = log
  .tailEntries({
    filter: 'timestamp > "2021-01-01T23:00:00Z"',
  })
  .on('error', console.error)
  .on('data', resp => {
    console.log(resp.entries);
    console.log(resp.suppressionInfo);
    // If you anticipate many results, you can end a stream early to prevent
    // unnecessary processing and API requests.
    stream.end();
  })
  .on('end', () => {
    console.log('log entry stream has ended');
  });

// Note: to get all project logs, invoke logging.tailEntries