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

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

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

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

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

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

検索バーを使用してこのページを検索する場合は、小見出しが [Logging] である結果を選択します。
[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 をインストールします。

Google Cloud CLI がインストールされていることを確認します。Google Cloud CLI をインストールする手順については、Google Cloud CLI のインストールをご覧ください。
gcloud CLI のバージョン 302.0.0 以降を使用していることを確認します。
```
gcloud version
```
gcloud CLI の更新手順については、gcloud components update をご覧ください。
gcloud CLI アルファ版コンポーネントをインストールします。
```
gcloud components install alpha
```
MacOS、Linux、Cloud Shell のユーザーの場合:
1. gRPC クライアントライブラリをインストールします。
```
 sudo pip3 install grpcio
```
2. 環境変数 CLOUDSDK_PYTHON_SITEPACKAGES に任意の値を設定します。
```
 export CLOUDSDK_PYTHON_SITEPACKAGES=1
```
  注: デフォルトでは、Google Cloud CLI は、ローカルシステムにインストールされている Python ライブラリを無視します。Google Cloud CLI で grpcio ライブラリを使用できるようにするには、サイトパッケージを有効にする必要があります。サイトパッケージを有効にするには、環境変数 CLOUDSDK_PYTHON_SITEPACKAGES を 1 に設定します。サイトパッケージを有効にすると、gcloud CLI は google-cloud-sdk/lib ディレクトリの外部で追加のライブラリを使用できます。
Google Cloud プロジェクト ID を設定して認証するには、次のコマンドを使用します。
```
gcloud config set project PROJECT_ID
gcloud auth login
```
プロジェクト ID を取得するには、プロジェクトの作成と管理をご覧ください。
次のコマンドを実行して、gcloud alpha logging tail がインストールされていることを確認します。
```
gcloud alpha logging tail
```
コマンドによって、次のメッセージが表示されます。

Initializing tail session.

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

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

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

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

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

デフォルトのバッファ時間は 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 クライアントライブラリをご覧ください。

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 クライアントライブラリをご覧ください。

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

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

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

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

gcloud alpha logging tail のインストール

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

上限と割り当て

クライアントの制限事項

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

Go

Java

Node.js

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

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

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

`gcloud alpha logging tail` のインストール

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