Node.js용 Cloud Logging 설정

Node.js 애플리케이션의 경우 널리 사용되는 Winston 및 Bunyan 로깅 라이브러리에 대한 플러그인이 유지됩니다. Winston은 다양한 로그 포맷 및 전송을 구현하는 범용 라이브러리입니다. 구조화된 JSON 로그에 특화된 Bunyan은 Bunyan 명령줄에 파이핑하여 로그 형식 지정을 지원합니다.

Node.js용 Logging 클라이언트 라이브러리를 직접 사용하거나 원하는 로깅 라이브러리와 자체 통합을 만들 수도 있습니다. 예를 들어 Pino 로그 프레임워크 예시를 사용할 수 있습니다.

Compute Engine 가상 머신(VM) 인스턴스에서 Winston 또는 Bunyan을 사용하기 위해 Logging 에이전트를 설치할 필요가 없습니다.

시작하기 전에

  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의 경우 Node.js Express 애플리케이션과 함께 Bunyan을 사용하는 방법에 대한 정보가 제공됩니다.

다른 라이브러리나 프레임워크를 사용할 수 있습니다. 예를 들어 Pino 로그 프레임워크를 사용할 수 있습니다. OpenTelemetry를 사용하여 측정항목 및 trace 데이터 수집하고 Pino 로그 프레임워크로 로그를 수집하는 샘플 코드는 Node.js로 trace 및 측정항목 생성을 참조하세요. 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 애플리케이션에서 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();

설치에 대한 자세한 내용은 Node.js용 Cloud Logging 라이브러리 문서를 참조하세요. 또한 Issue Tracker를 통해 문제를 보고할 수도 있습니다.

Cloud Logging 클라이언트 라이브러리로 로그 작성

Node.js용 Cloud Logging 클라이언트 라이브러리를 직접 사용하는 방법에 대한 자세한 내용은 Cloud Logging 클라이언트 라이브러리를 참조하세요.

Google Cloud에서 실행

애플리케이션에서 Node.js용 Cloud Logging 라이브러리를 사용하여 로그를 작성하려면 기본 리소스의 서비스 계정에 로그 작성자(roles/logging.logWriter) IAM 역할이 있어야 합니다. 대부분의 Google Cloud 환경에서는 이 역할을 갖도록 기본 서비스 계정을 자동으로 구성합니다.

App Engine

Cloud Logging은 App Engine에 자동으로 사용 설정되며 앱의 기본 서비스 계정에는 기본적으로 로그 항목을 쓸 수 있는 IAM 권한이 있습니다.

앱에서 로그 항목을 작성하려면 이 페이지에 설명된 대로 Bunyan 또는 Winston을 사용하는 것이 좋습니다.

자세한 내용은 로그 작성 및 보기를 참조하세요.

Google Kubernetes Engine(GKE)

GKE에서는 기본 서비스 계정에 로그 작성자(roles/logging.logWriter) IAM 역할을 자동으로 부여합니다. 이 기본 서비스 계정과 함께 GKE용 워크로드 아이덴티티 제휴를 사용하여 워크로드가 특정 Google Cloud API에 액세스할 수 있도록 하면 추가 구성이 필요하지 않습니다. 그러나 커스텀 IAM 서비스 계정과 함께 GKE용 워크로드 아이덴티티 제휴를 사용하는 경우 커스텀 서비스 계정에 로그 작성자 역할(roles/logging.logWriter)이 있어야 합니다.

필요한 경우 클러스터를 만들 때 다음 명령어를 사용하여 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 콘솔을 통해 새 인스턴스를 만들 때 인스턴스 만들기 패널의 ID 및 API 액세스 섹션에서 이 작업을 수행할 수 있습니다. 선택한 Compute Engine 기본 서비스 계정 또는 다른 서비스 계정을 사용하고 ID 및 API 액세스 섹션에서 모든 Cloud API에 대한 전체 액세스 허용을 선택하세요. 선택한 서비스 계정에 관계없이 Google Cloud 콘솔의 IAM 및 관리자 섹션에서 로그 작성자 역할이 부여되었는지 확인합니다.

Cloud Run Functions

Cloud Run Functions는 기본적으로 로그 작성자 역할을 부여합니다.

명시적으로 사용자 인증 정보를 제공하지 않아도 Node.js용 Cloud Logging 라이브러리를 사용할 수 있습니다.

Cloud Run Functions는 Cloud Logging을 자동으로 사용하도록 구성되어 있습니다.

로컬 및 기타 위치에서 실행

자체 워크스테이션, 데이터 센터의 컴퓨터 또는 다른 클라우드 제공업체의 VM 인스턴스에서 라이브러리를 실행하는 경우와 같이 Google Cloud 외부에서 Node.js용 Cloud Logging 라이브러리를 사용하려면 Node.js용 Cloud Logging 라이브러리에 직접 Google Cloud 프로젝트 ID와 해당 서비스 계정 사용자 인증 정보를 제공해야 합니다.

기존 서비스 계정의 경우 다음을 수행합니다.

  1. 서비스 계정에 로그 작성자(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 콘솔에서 로그 탐색기 페이지로 이동합니다.

로그 탐색기로 이동

검색창을 사용하여 이 페이지를 찾은 경우 부제목이 Logging인 결과를 선택합니다.

로그 탐색기에서 리소스를 하나 이상 지정해야 하지만 어떤 리소스를 선택해야 할지 애매할 수 있습니다. 다음은 시작하는 데 도움이 되는 몇 가지 유용한 팁입니다.

  • 애플리케이션을 App Engine에 배포하거나 App Engine 관련 라이브러리를 사용하는 경우 리소스를 GAE 애플리케이션으로 설정합니다.

  • 애플리케이션을 Compute Engine에 배포하는 경우 리소스를 GCE VM 인스턴스로 설정합니다.

  • 애플리케이션을 Google Kubernetes Engine에 배포하는 경우 클러스터의 로깅 구성에 따라 로그 항목의 리소스 유형이 결정됩니다. 기존 Google Cloud Observability 및 Google Cloud Observability Kubernetes Monitoring 솔루션에 대한 자세한 내용과 이러한 옵션이 리소스 유형에 미치는 영향을 알아보려면 Google Cloud Observability Kubernetes Monitoring으로 마이그레이션을 참조하세요.

  • 애플리케이션에서 Cloud Logging API를 직접 사용하는 경우 API와 구성에 따라 리소스가 달라집니다. 예를 들어 애플리케이션에서 리소스를 지정하거나 기본 리소스를 사용할 수 있습니다.

  • 로그 탐색기에 어떤 로그도 표시되지 않는 경우 모든 로그 항목을 보려면 고급 쿼리 모드로 전환하여 비어 있는 쿼리를 사용합니다.

    1. 고급 쿼리 모드로 전환하려면 로그 탐색기 상단의 메뉴(▾)를 클릭한 다음 고급 필터로 전환을 선택합니다.
    2. 필터 상자에 포함된 내용을 지웁니다.
    3. 필터 제출을 클릭합니다.

    개별 항목을 검사하여 리소스를 파악할 수 있습니다.

자세한 내용은 로그 탐색기 사용을 참조하세요.