로그 항목 스트리밍 및 실시간 테일링

이 문서에서는 스트리밍 및 실시간 테일링을 통해 로그 항목을 실시간으로 확인하는 방법을 설명합니다. 스트리밍 로그를 사용하면 로그 항목을 실시간으로 볼 수 있으며, 로그 탐색기에서 제공됩니다. 실시간 테일링을 사용하면 로그 항목을 실시간으로 볼 수 있으며, 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을 선택한 후 로그 탐색기를 선택합니다.
로그 탐색기로 이동
쿼리 텍스트 상자에서 쿼리를 입력한 후 스트림 로그를 클릭합니다.

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 설치를 참조하세요.
버전 302.0.0 이상의 gcloud CLI를 사용하고 있는지 확인합니다.
```
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초 지연되지만 대부분의 로그는 오름차순으로 반환됩니다.

한도 및 할당량

다음 표에는 실시간 테일링의 한도 및 할당량이 나와 있습니다.

한도 및 할당량	값
분당 반환된 항목	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"
	loggingpb "google.golang.org/genproto/googleapis/logging/v2"
)

// 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

로그 항목 스트리밍 및 실시간 테일링

로그 탐색기의 스트림 로그

Google Cloud CLI에서 실시간 테일링 사용

gcloud alpha logging tail 설치

버퍼링 및 순서 지정

한도 및 할당량

클라이언트 제한사항

클라이언트 라이브러리에 실시간 테일링 사용

Go

Java

Node.js

`gcloud alpha logging tail` 설치