InfoGrab DocsInfoGrab Docs

로깅 개발 가이드라인

요약

GitLab 로그는 관리자와 GitLab 팀원 모두가 현장에서 문제를 진단하는 데 중요한 역할을 합니다. 현재 Rails.logger 호출은 모두 production.log에 저장되는데, 이 파일에는 Rails의 로그와 개발자가 코드베이스에 삽입한 다른 호출이 혼재되어 있습니다.

GitLab 로그는 관리자와 GitLab 팀원 모두가 현장에서 문제를 진단하는 데 중요한 역할을 합니다.

Rails.logger를 사용하지 마세요#

현재 Rails.logger 호출은 모두 production.log에 저장되는데, 이 파일에는 Rails의 로그와 개발자가 코드베이스에 삽입한 다른 호출이 혼재되어 있습니다. 예를 들면 다음과 같습니다:

Started GET "/gitlabhq/yaml_db/tree/master" for 168.111.56.1 at 2015-02-12 19:34:53 +0200
Processing by Projects::TreeController#show as HTML
  Parameters: {"project_id"=>"gitlabhq/yaml_db", "id"=>"master"}

  ...

  Namespaces"."created_at" DESC, "namespaces"."id" DESC LIMIT 1 [["id", 26]]
  CACHE (0.0ms) SELECT  "members".* FROM "members"  WHERE "members"."source_type" = 'Project' AND "members"."type" IN ('ProjectMember') AND "members"."source_id" = $1 AND "members"."source_type" = $2 AND "members"."user_id" = 1  ORDER BY "members"."created_at" DESC, "members"."id" DESC LIMIT 1  [["source_id", 18], ["source_type", "Project"]]
  CACHE (0.0ms) SELECT  "members".* FROM "members"  WHERE "members"."source_type" = 'Project' AND "members".
  (1.4ms) SELECT COUNT(*) FROM "merge_requests"  WHERE "merge_requests"."target_project_id" = $1 AND ("merge_requests"."state" IN ('opened','reopened')) [["target_project_id", 18]]
  Rendered layouts/nav/_project.html.haml (28.0ms)
  Rendered layouts/_collapse_button.html.haml (0.2ms)
  Rendered layouts/_flash.html.haml (0.1ms)
  Rendered layouts/_page.html.haml (32.9ms)
Completed 200 OK in 166ms (Views: 117.4ms | ActiveRecord: 27.2ms)

이러한 로그에는 여러 가지 문제가 있습니다:

  • 타임스탬프나 기타 컨텍스트 정보(예: 프로젝트 ID 또는 사용자)가 없는 경우가 많습니다.

  • 여러 줄에 걸쳐 있어 Elasticsearch에서 찾기 어려울 수 있습니다.

  • 공통 구조가 없어 Logstash나 Fluentd와 같은 로그 포워더가 파싱하기 어렵습니다. 이로 인해 검색도 어렵습니다.

현재 GitLab.com에서 production.log의 메시지는 방대한 볼륨과 노이즈로 인해 Elasticsearch에서 인덱싱되지 않습니다. 메시지들은 Google Stackdriver에 저장되지만, 거기서 로그를 검색하는 것도 여전히 어렵습니다. 자세한 내용은 GitLab.com 로깅 문서를 참고하세요.

직접 표준 출력 메서드를 사용하지 마세요#

애플리케이션 코드에서 $stdout.puts, $stderr.puts, $stdout.print, $stderr.print, 또는 STDOUT/STDERR에 대한 동등한 호출 사용을 피하세요. 이러한 방법은 구조화된 로깅을 우회합니다:

  • 출력이 파싱 가능한 JSON이 아닌 비구조화된 일반 텍스트입니다.

  • 로그 레벨이 없어 메시지를 필터링하거나 라우팅할 수 없습니다.

  • 컨텍스트 메타데이터(correlation ID, 사용자, 프로젝트 등)가 없습니다.

  • 출력이 고객이 진단을 위해 접근할 수 있는 로그 파일에 기록되지 않습니다 (예: Omnibus 설치의 /var/log/gitlab/).

커뮤니티 Rails/Output cop은 단독 puts와 print를 검출합니다. 커스텀 Gitlab/DirectStdio cop은 $stdout.puts, $stdout.print, 그리고 $stderr, STDOUT, STDERR에 대한 동등한 호출을 검출합니다.

Rake 태스크나 CLI 출력의 경우, 표준 출력에 직접 쓰는 대신 SystemCheck::Helpers 또는 Gitlab::TaskHelpers에 있는 기존 래퍼 메서드를 사용하세요. 애플리케이션 로깅에는 구조화된 JSON 로거를 사용하세요.

구조화된 (JSON) 로깅 사용#

구조화된 로깅은 이러한 문제를 해결합니다. API 요청에서 가져온 예시를 살펴보세요:

{"time":"2018-10-29T12:49:42.123Z","severity":"INFO","duration":709.08,"db":14.59,"view":694.49,"status":200,"method":"GET","path":"/api/v4/projects","params":[{"key":"action","value":"git-upload-pack"},{"key":"changes","value":"_any"},{"key":"key_id","value":"secret"},{"key":"secret_token","value":"[FILTERED]"}],"host":"localhost","ip":"::1","ua":"Ruby","route":"/api/:version/projects","user_id":1,"username":"root","queue_duration":100.31,"gitaly_calls":30}

한 줄에 사용자가 무슨 일이 발생했는지 이해하는 데 필요한 모든 정보가 포함되어 있습니다: 타임스탬프, HTTP 메서드와 경로, 사용자 ID 등.

JSON 로깅 사용 방법#

프로젝트 임포터에서 발생하는 이벤트를 로깅하고 싶다고 가정해 보세요. 임포터가 진행되면서 생성된 이슈, 머지 리퀘스트 등을 로깅하려고 합니다. 다음 단계를 따르세요:

  • GitLab 로그 목록을 살펴보고 로그 메시지가 기존 로그 파일 중 하나에 속하는지 확인하세요.

  • 적합한 위치가 없다면 새 파일명 생성을 고려하되, 타당한지 메인테이너에게 확인하세요. 로그 파일은 사람들이 한 곳에서 관련 로그를 검색하기 쉽게 만들어야 합니다. 예를 들어, geo.log에는 GitLab Geo에 관련된 모든 로그가 포함되어 있습니다. 새 파일을 만들려면 다음을 수행하세요:

파일명을 선택하세요(예: importer_json.log).

  • Gitlab::JsonLogger의 새 서브클래스를 만드세요:
module Gitlab
  module Import
    class Logger < ::Gitlab::JsonLogger
      def self.file_name_noext
        'importer'
      end
    end
   end
end

기본적으로 Gitlab::JsonLogger는 로그 항목에 애플리케이션 컨텍스트 메타데이터를 포함합니다. 로거가 애플리케이션 요청 외부(예: rake 태스크)에서 호출되거나, 애플리케이션 컨텍스트를 구축하는 데 관여하는 저수준 코드(예: 데이터베이스 연결 코드)에 의해 호출될 것으로 예상되는 경우, 다음과 같이 로거 클래스에서 클래스 메서드 exclude_context!를 호출해야 합니다:

module Gitlab
  module Database
    module LoadBalancing
      class Logger < ::Gitlab::JsonLogger
        exclude_context!

        def self.file_name_noext
          'database_load_balancing'
        end
      end
    end
  end
end
  • 로깅하려는 클래스에서 로거를 인스턴스 변수로 초기화할 수 있습니다:
attr_accessor :logger

def initialize
  @logger = ::Import::Framework::Logger.build
end

로거를 메모이제이션하는 것이 유용합니다. 로그를 남길 때마다 새 로거를 생성하면 파일을 여는 불필요한 오버헤드가 발생하기 때문입니다.

  • 이제 코드에 로그 메시지를 삽입하세요. 로그를 추가할 때 모든 컨텍스트를 키-값 쌍으로 포함하세요:
# BAD
logger.info("Unable to create project #{project.id}")

# GOOD
logger.info(message: "Unable to create project", project_id: project.id)
  • 로그 메시지의 공통 기본 구조를 만들어야 합니다. 예를 들어, 모든 메시지에 current_user_id와 project_id를 포함하면 특정 기간 동안 사용자별 활동을 더 쉽게 검색할 수 있습니다.

JSON 로깅의 암묵적 스키마#

Elasticsearch와 같은 도구를 사용하여 구조화된 로그를 인덱싱할 때, 각 로그 필드의 타입에 대한 스키마가 존재합니다(해당 스키마가 암묵적/추론된 경우에도). 필드 값의 타입을 일관되게 유지하는 것이 중요합니다. 그렇지 않으면 해당 필드에서 검색/필터링이 중단되거나, 심지어 전체 로그 이벤트가 삭제될 수 있습니다. 이 섹션의 많은 내용이 Elasticsearch에 특화된 방식으로 설명되어 있지만, 개념은 구조화된 로그를 인덱싱하는 데 사용하는 여러 시스템에도 적용됩니다. GitLab.com은 로그 데이터 인덱싱에 Elasticsearch를 사용합니다.

필드 타입이 명시적으로 매핑되지 않으면, Elasticsearch는 처음 발견된 필드 값 인스턴스에서 타입을 추론합니다. 이후에 다른 타입의 필드 값 인스턴스가 발생하면 인덱싱에 실패하거나, 일부 경우(스칼라/객체 충돌)에는 전체 로그 라인이 삭제됩니다.

GitLab.com의 로깅 Elasticsearch는 ignore_malformed를 설정하여, 단순한 매핑 충돌(예: 숫자/문자열)이 있어도 문서가 인덱싱될 수 있도록 합니다. 다만 영향을 받은 필드에 대한 인덱싱은 중단됩니다.

예시:

# GOOD
logger.info(message: "Import error", error_code: 1, error: "I/O failure")

# BAD
logger.info(message: "Import error", error: 1)
logger.info(message: "Import error", error: "I/O failure")

# WORST
logger.info(message: "Import error", error: "I/O failure")
logger.info(message: "Import error", error: { message: "I/O failure" })

목록 요소는 같은 타입이어야 합니다:

# GOOD
logger.info(a_list: ["foo", "1", "true"])

# BAD
logger.info(a_list: ["foo", 1, true])

참고 자료:

class 속성 포함하기#

구조화된 로그에는 항상 class 속성을 포함해야 코드의 특정 위치에서 기록된 모든 항목을 찾을 수 있습니다. class 속성을 자동으로 추가하려면 Gitlab::Loggable 모듈을 include하고 build_structured_payload 메서드를 사용하세요.

class MyClass
  include ::Gitlab::Loggable

  def my_method
    logger.info(build_structured_payload(message: 'log message', project_id: project_id))
  end

  private

  def logger
    @logger ||= Gitlab::AppJsonLogger.build
  end
end

소요 시간 로깅#

타임존과 마찬가지로, 로깅에 올바른 시간 단위를 선택하면 불필요한 오버헤드를 줄일 수 있습니다. 초, 밀리초 또는 다른 단위 중에서 선택해야 할 때는 float 형태의 초 (마이크로초 정밀도, 즉 Gitlab::InstrumentationHelper::DURATION_PRECISION)를 선호하세요.

로그에서 타이밍을 추적하기 쉽게 하려면, 로그 키에 _s 접미사를 붙이고 이름에 duration을 포함하세요(예: view_duration_s).

다중 목적지 로깅#

GitLab은 구조화된 로그에서 JSON 로그로 전환했습니다. 그러나 다중 목적지 로깅을 통해 여러 형식으로 로그를 기록할 수 있습니다.

다중 목적지 로깅 사용 방법#

MultiDestinationLogger를 상속하는 새 로거 클래스를 만들고 LOGGERS 상수에 로거 배열을 추가하세요. 로거는 Gitlab::Logger를 상속하는 클래스여야 합니다. 예를 들어, 다음 예시의 사용자 정의 로거는 Gitlab::Logger와 Gitlab::JsonLogger를 상속할 수 있습니다.

primary_logger로 로거 중 하나를 지정해야 합니다. primary_logger는 이 다중 목적지 로거에 대한 정보가 애플리케이션에 표시될 때 사용됩니다 (예: Gitlab::Logger.read_latest 메서드 사용 시).

다음 예시는 정의된 LOGGERS 중 하나를 primary_logger로 설정합니다.

module Gitlab
  class FancyMultiLogger < Gitlab::MultiDestinationLogger
    LOGGERS = [UnstructuredLogger, StructuredLogger].freeze

    def self.loggers
      LOGGERS
    end

    def primary_logger
      UnstructuredLogger
    end
  end
end

이제 이 멀티 로거에서 일반 로깅 메서드를 호출할 수 있습니다. 예를 들면:

FancyMultiLogger.info(message: "Information")

이 메시지는 FancyMultiLogger.loggers에 등록된 각 로거에 의해 기록됩니다.

로깅을 위한 문자열 또는 해시 전달#

MultiDestinationLogger에 문자열이나 해시를 전달하면, 설정된 LOGGERS의 종류에 따라 로그 라인이 다르게 포맷될 수 있습니다.

예를 들어, 이전 예시의 로거를 부분적으로 정의해 보겠습니다:

module Gitlab
  # Similar to AppTextLogger
  class UnstructuredLogger < Gitlab::Logger
    ...
  end

  # Similar to AppJsonLogger
  class StructuredLogger < Gitlab::JsonLogger
    ...
  end
end

다음은 두 로거가 메시지를 처리하는 방법의 예시입니다.

  • 문자열을 전달하는 경우
FancyMultiLogger.info("Information")

# UnstructuredLogger
I, [2020-01-13T18:48:49.201Z #5647]  INFO -- : Information

# StructuredLogger
{:severity=>"INFO", :time=>"2020-01-13T11:02:41.559Z", :correlation_id=>"b1701f7ecc4be4bcd4c2d123b214e65a", :message=>"Information"}
  • 해시를 전달하는 경우
FancyMultiLogger.info({:message=>"This is my message", :project_id=>123})

# UnstructuredLogger
I, [2020-01-13T19:01:17.091Z #11056]  INFO -- : {"message"=>"Message", "project_id"=>"123"}

# StructuredLogger
{:severity=>"INFO", :time=>"2020-01-13T11:06:09.851Z", :correlation_id=>"d7e0886f096db9a8526a4f89da0e45f6", :message=>"This is my message", :project_id=>123}

로깅 컨텍스트 메타데이터 (Rails 또는 Grape 요청을 통해)#

Gitlab::ApplicationContext는 요청 라이프사이클에 메타데이터를 저장하며, 이후 웹 요청이나 Sidekiq 로그에 추가될 수 있습니다.

API, Rails, Sidekiq 로그에는 이 컨텍스트 정보와 함께 meta.로 시작하는 필드가 포함됩니다.

진입점은 다음에서 확인할 수 있습니다:

속성 추가하기#

새 속성을 추가할 때, 위 진입점의 컨텍스트 내에서 노출되는지 확인하고 다음을 수행하세요:

  • with_context (또는 push) 메서드에 해시로 전달하세요 (메서드나 변수가 즉시 평가되면 안 되는 경우 Proc을 전달하세요).

  • Gitlab::ApplicationContext가 새 값을 수락하도록 변경하세요.

  • Labkit::Context에서 새 속성이 허용되는지 확인하세요.

Kibana에서 시각화를 만드는 방법에 대한 추가 지식은 HOWTO: Use Sidekiq metadata logs를 참고하세요.

컨텍스트 필드는 현재 웹 요청을 통해 트리거된 Sidekiq job에 대해서만 로깅됩니다. 자세한 내용은 후속 작업을 참고하세요.

로깅 컨텍스트 메타데이터 (워커를 통해)#

ApplicationWorker#log_extra_metadata_on_done 메서드를 사용하여 워커에 추가 메타데이터를 첨부할 수 있습니다. 이 메서드를 사용하면 완료된 job 페이로드와 함께 나중에 Kibana에 로깅되는 메타데이터가 추가됩니다.

class MyExampleWorker
  include ApplicationWorker

  def perform(*args)
    # Worker performs work
    # ...

    # The contents of value will appear in Kibana under `json.extra.my_example_worker.my_key`
    log_extra_metadata_on_done(:my_key, value)
  end
end

ExpireArtifactsWorker가 실행될 때마다 삭제된 아티팩트의 수를 로깅하는 이 예시를 참고하세요.

예외 처리#

예외를 캐치하고 추적하려는 경우가 종종 있습니다.

수동 예외 로깅은 허용되지 않습니다. 그 이유는 다음과 같습니다:

  • 수동으로 로깅된 예외는 기밀 데이터를 유출할 수 있습니다.

  • 수동으로 로깅된 예외는 종종 백트레이스를 정리해야 하므로 보일러플레이트가 줄어듭니다.

  • 수동으로 로깅된 예외는 Sentry에도 추적되어야 하는 경우가 많습니다.

  • 수동으로 로깅된 예외는 correlation_id를 사용하지 않아, 예외가 발생한 요청, 사용자, 컨텍스트와 연결하기 어렵습니다.

  • 수동으로 로깅된 예외는 여러 파일에 분산되는 경우가 많아 모든 로깅 파일을 스크래핑하는 부담이 증가합니다.

중복을 피하고 일관된 동작을 유지하기 위해 Gitlab::ErrorTracking은 예외를 추적하는 헬퍼 메서드를 제공합니다:

  • Gitlab::ErrorTracking.track_and_raise_exception: 이 메서드는 로깅하고, Sentry에 예외를 전송하며(구성된 경우), 예외를 다시 발생시킵니다.

  • Gitlab::ErrorTracking.track_exception: 이 메서드는 로깅하고 Sentry에 예외를 전송만 합니다(구성된 경우).

  • Gitlab::ErrorTracking.log_exception: 이 메서드는 예외를 로깅만 하고, Sentry에 예외를 전송하지 않습니다.

  • Gitlab::ErrorTracking.track_and_raise_for_dev_exception: 이 메서드는 로깅하고, Sentry에 예외를 전송하며(구성된 경우), 개발 및 테스트 환경에서 예외를 다시 발생시킵니다.

아래 예시와 같이 Gitlab::ErrorTracking.track_and_raise_exception과 Gitlab::ErrorTracking.track_exception만 사용하는 것이 권장됩니다.

추적된 각 예외에 더 많은 컨텍스트를 제공하기 위해 추가 파라미터를 추가하는 것을 고려하세요.

예시#

class MyService < ::BaseService
  def execute
    project.perform_expensive_operation

    success
  rescue => e
    Gitlab::ErrorTracking.track_exception(e, project_id: project.id)

    error('Exception occurred')
  end
end

class MyService < ::BaseService
  def execute
    project.perform_expensive_operation

    success
  rescue => e
    Gitlab::ErrorTracking.track_and_raise_exception(e, project_id: project.id)
  end
end

기본 로깅 위치#

GitLab Self-Managed 및 GitLab.com에서 GitLab은 두 가지 방식으로 배포됩니다:

Omnibus GitLab 로그 처리#

Omnibus GitLab은 /var/log/gitlab 내의 컴포넌트별 디렉터리에 로그를 저장합니다:

# ls -al /var/log/gitlab
total 200
drwxr-xr-x 27 root              root        4096 Apr 29 20:28 .
drwxrwxr-x 19 root              syslog      4096 Aug  5 04:08 ..
drwx------  2 gitlab-prometheus root        4096 Aug  6 04:08 alertmanager
drwx------  2 root              root        4096 Aug  6 04:08 crond
drwx------  2 git               root        4096 Aug  6 04:08 gitaly
drwx------  2 git               root        4096 Aug  6 04:08 gitlab-exporter
drwx------  2 git               root        4096 Aug  6 04:08 gitlab-kas
drwx------  2 git               root       45056 Aug  6 13:18 gitlab-rails
drwx------  2 git               root        4096 Aug  5 04:18 gitlab-shell
drwx------  2 git               root        4096 May 24  2023 gitlab-sshd
drwx------  2 git               root        4096 Aug  6 04:08 gitlab-workhorse
drwxr-xr-x  2 root              root       12288 Aug  1 00:20 lets-encrypt
drwx------  2 root              root        4096 Aug  6 04:08 logrotate
drwx------  2 git               root        4096 Aug  6 04:08 mailroom
drwxr-x---  2 root              gitlab-www 12288 Aug  6 00:18 nginx
drwx------  2 gitlab-prometheus root        4096 Aug  6 04:08 node-exporter
drwx------  2 gitlab-psql       root        4096 Aug  6 15:00 pgbouncer
drwx------  2 gitlab-psql       root        4096 Aug  6 04:08 postgres-exporter
drwx------  2 gitlab-psql       root        4096 Aug  6 04:08 postgresql
drwx------  2 gitlab-prometheus root        4096 Aug  6 04:08 prometheus
drwx------  2 git               root        4096 Aug  6 04:08 puma
drwxr-xr-x  2 root              root       32768 Aug  1 21:32 reconfigure
drwx------  2 gitlab-redis      root        4096 Aug  6 04:08 redis
drwx------  2 gitlab-redis      root        4096 Aug  6 04:08 redis-exporter
drwx------  2 registry          root        4096 Aug  6 04:08 registry
drwx------  2 gitlab-redis      root        4096 May  6 06:30 sentinel
drwx------  2 git               root        4096 Aug  6 13:05 sidekiq

위 예시에서 다음 컴포넌트들이 아래 디렉터리에 로그를 저장하는 것을 확인할 수 있습니다:

컴포넌트 로그 디렉터리
GitLab Rails /var/log/gitlab/gitlab-rails
Gitaly /var/log/gitlab/gitaly
Sidekiq /var/log/gitlab/sidekiq
GitLab Workhorse /var/log/gitlab/gitlab-workhorse

GitLab Rails 디렉터리가 아마도 위의 Ruby 코드에서 사용되는 로그 파일을 찾을 위치일 것입니다.

logrotate는 모든 *.log 파일을 감시하는 데 사용됩니다.

Cloud Native GitLab 로그 처리#

Cloud Native GitLab Pod는 추가 하위 디렉터리를 만들지 않고 GitLab 로그를 직접 /var/log/gitlab에 씁니다. 예를 들어, webservice Pod는 하나의 컨테이너에서 gitlab-workhorse를 실행하고 다른 컨테이너에서 puma를 실행합니다. 후자의 로그 파일 디렉터리는 다음과 같습니다:

git@gitlab-webservice-default-bbd9647d9-fpwg5:/$ ls -al /var/log/gitlab
total 181420
drwxr-xr-x 2 git  git       4096 Aug  2 22:58 .
drwxr-xr-x 4 root root      4096 Aug  2 22:57 ..
-rw-r--r-- 1 git  git          0 Aug  2 18:22 .gitkeep
-rw-r--r-- 1 git  git   46524128 Aug  6 20:18 api_json.log
-rw-r--r-- 1 git  git      19009 Aug  2 22:58 application_json.log
-rw-r--r-- 1 git  git        157 Aug  2 22:57 auth_json.log
-rw-r--r-- 1 git  git       1116 Aug  2 22:58 database_load_balancing.log
-rw-r--r-- 1 git  git         67 Aug  2 22:57 grpc.log
-rw-r--r-- 1 git  git          0 Aug  2 22:57 production.log
-rw-r--r-- 1 git  git  138436632 Aug  6 20:18 production_json.log
-rw-r--r-- 1 git  git         48 Aug  2 22:58 puma.stderr.log
-rw-r--r-- 1 git  git        266 Aug  2 22:58 puma.stdout.log
-rw-r--r-- 1 git  git         67 Aug  2 22:57 service_measurement.log
-rw-r--r-- 1 git  git         67 Aug  2 22:57 sidekiq_client.log
-rw-r--r-- 1 git  git     733809 Aug  6 20:18 web_exporter.log

gitlab-logger는 /var/log/gitlab의 모든 파일을 tail하는 데 사용됩니다. 각 로그 라인은 필요에 따라 JSON으로 변환되어 stdout으로 전송되므로 kubectl logs를 통해 확인할 수 있습니다.

새 로그 파일 추가 시 추가 단계#

  • 로그 보존 설정을 고려하세요. 기본적으로 Omnibus는 /var/log/gitlab/gitlab-rails/*.log의 모든 로그를 매시간 교체하고 최대 30개의 압축 파일을 유지합니다. GitLab.com에서는 해당 설정이 압축 파일 6개에 불과합니다. 이 설정은 대부분의 사용자에게 충분하지만, Omnibus GitLab에서 조정이 필요할 수 있습니다.

  • GitLab.com에서 GitLab Rails가 생성하는 모든 새 JSON 로그 파일은 GitLab Rails 쿠버네티스 Pod에서 Elasticsearch로 자동 전송됩니다(Kibana에서 사용 가능). Gitaly 노드에서도 파일을 전달해야 하는 경우 프로덕션 트래커에 이슈를 제출하거나 gitlab_fluentd 프로젝트에 머지 리퀘스트를 제출하세요. 이 예시를 참고하세요.

  • GitLab CE/EE 문서와 GitLab.com 런북을 반드시 업데이트하세요.

Kibana에서 새 로그 파일 찾기 (GitLab.com 전용)#

GitLab.com에서 GitLab Rails가 생성하는 모든 새 JSON 로그 파일은 GitLab Rails 쿠버네티스 Pod에서 Elasticsearch로 자동 전송됩니다(Kibana에서 사용 가능). Kibana의 json.subcomponent 필드를 사용하면 다양한 종류의 로그 파일로 필터링할 수 있습니다. 예를 들어, production_json.log에서 전달된 항목의 json.subcomponent는 production_json이 됩니다.

Web/API Pod의 로그 파일은 Sidekiq Pod의 로그 파일과 다른 인덱스로 이동된다는 점도 알아두세요. 로그를 기록하는 위치에 따라 다른 인덱스 패턴에서 로그를 찾게 됩니다.

로깅 가시성 제어#

로그가 증가하면 미처리 메시지의 백로그가 늘어날 수 있습니다. 새 로그 메시지를 추가할 때 전체 로깅 볼륨이 10% 이상 증가하지 않도록 하세요.

지원 중단 알림#

지원 중단 알림의 예상 볼륨이 큰 경우:

  • 개발 환경에서만 로깅하세요.

  • 필요한 경우 테스트 환경에서도 로깅하세요.

로깅 개발 가이드라인

GitLab v19.1
원문 보기
요약

GitLab 로그는 관리자와 GitLab 팀원 모두가 현장에서 문제를 진단하는 데 중요한 역할을 합니다. 현재 Rails.logger 호출은 모두 production.log에 저장되는데, 이 파일에는 Rails의 로그와 개발자가 코드베이스에 삽입한 다른 호출이 혼재되어 있습니다.

GitLab 로그는 관리자와 GitLab 팀원 모두가 현장에서 문제를 진단하는 데 중요한 역할을 합니다.

Rails.logger를 사용하지 마세요#

현재 Rails.logger 호출은 모두 production.log에 저장되는데, 이 파일에는 Rails의 로그와 개발자가 코드베이스에 삽입한 다른 호출이 혼재되어 있습니다. 예를 들면 다음과 같습니다:

Started GET "/gitlabhq/yaml_db/tree/master" for 168.111.56.1 at 2015-02-12 19:34:53 +0200
Processing by Projects::TreeController#show as HTML
  Parameters: {"project_id"=>"gitlabhq/yaml_db", "id"=>"master"}

  ...

  Namespaces"."created_at" DESC, "namespaces"."id" DESC LIMIT 1 [["id", 26]]
  CACHE (0.0ms) SELECT  "members".* FROM "members"  WHERE "members"."source_type" = 'Project' AND "members"."type" IN ('ProjectMember') AND "members"."source_id" = $1 AND "members"."source_type" = $2 AND "members"."user_id" = 1  ORDER BY "members"."created_at" DESC, "members"."id" DESC LIMIT 1  [["source_id", 18], ["source_type", "Project"]]
  CACHE (0.0ms) SELECT  "members".* FROM "members"  WHERE "members"."source_type" = 'Project' AND "members".
  (1.4ms) SELECT COUNT(*) FROM "merge_requests"  WHERE "merge_requests"."target_project_id" = $1 AND ("merge_requests"."state" IN ('opened','reopened')) [["target_project_id", 18]]
  Rendered layouts/nav/_project.html.haml (28.0ms)
  Rendered layouts/_collapse_button.html.haml (0.2ms)
  Rendered layouts/_flash.html.haml (0.1ms)
  Rendered layouts/_page.html.haml (32.9ms)
Completed 200 OK in 166ms (Views: 117.4ms | ActiveRecord: 27.2ms)

이러한 로그에는 여러 가지 문제가 있습니다:

  • 타임스탬프나 기타 컨텍스트 정보(예: 프로젝트 ID 또는 사용자)가 없는 경우가 많습니다.

  • 여러 줄에 걸쳐 있어 Elasticsearch에서 찾기 어려울 수 있습니다.

  • 공통 구조가 없어 Logstash나 Fluentd와 같은 로그 포워더가 파싱하기 어렵습니다. 이로 인해 검색도 어렵습니다.

현재 GitLab.com에서 production.log의 메시지는 방대한 볼륨과 노이즈로 인해 Elasticsearch에서 인덱싱되지 않습니다. 메시지들은 Google Stackdriver에 저장되지만, 거기서 로그를 검색하는 것도 여전히 어렵습니다. 자세한 내용은 GitLab.com 로깅 문서를 참고하세요.

직접 표준 출력 메서드를 사용하지 마세요#

애플리케이션 코드에서 $stdout.puts, $stderr.puts, $stdout.print, $stderr.print, 또는 STDOUT/STDERR에 대한 동등한 호출 사용을 피하세요. 이러한 방법은 구조화된 로깅을 우회합니다:

  • 출력이 파싱 가능한 JSON이 아닌 비구조화된 일반 텍스트입니다.

  • 로그 레벨이 없어 메시지를 필터링하거나 라우팅할 수 없습니다.

  • 컨텍스트 메타데이터(correlation ID, 사용자, 프로젝트 등)가 없습니다.

  • 출력이 고객이 진단을 위해 접근할 수 있는 로그 파일에 기록되지 않습니다 (예: Omnibus 설치의 /var/log/gitlab/).

커뮤니티 Rails/Output cop은 단독 puts와 print를 검출합니다. 커스텀 Gitlab/DirectStdio cop은 $stdout.puts, $stdout.print, 그리고 $stderr, STDOUT, STDERR에 대한 동등한 호출을 검출합니다.

Rake 태스크나 CLI 출력의 경우, 표준 출력에 직접 쓰는 대신 SystemCheck::Helpers 또는 Gitlab::TaskHelpers에 있는 기존 래퍼 메서드를 사용하세요. 애플리케이션 로깅에는 구조화된 JSON 로거를 사용하세요.

구조화된 (JSON) 로깅 사용#

구조화된 로깅은 이러한 문제를 해결합니다. API 요청에서 가져온 예시를 살펴보세요:

{"time":"2018-10-29T12:49:42.123Z","severity":"INFO","duration":709.08,"db":14.59,"view":694.49,"status":200,"method":"GET","path":"/api/v4/projects","params":[{"key":"action","value":"git-upload-pack"},{"key":"changes","value":"_any"},{"key":"key_id","value":"secret"},{"key":"secret_token","value":"[FILTERED]"}],"host":"localhost","ip":"::1","ua":"Ruby","route":"/api/:version/projects","user_id":1,"username":"root","queue_duration":100.31,"gitaly_calls":30}

한 줄에 사용자가 무슨 일이 발생했는지 이해하는 데 필요한 모든 정보가 포함되어 있습니다: 타임스탬프, HTTP 메서드와 경로, 사용자 ID 등.

JSON 로깅 사용 방법#

프로젝트 임포터에서 발생하는 이벤트를 로깅하고 싶다고 가정해 보세요. 임포터가 진행되면서 생성된 이슈, 머지 리퀘스트 등을 로깅하려고 합니다. 다음 단계를 따르세요:

  • GitLab 로그 목록을 살펴보고 로그 메시지가 기존 로그 파일 중 하나에 속하는지 확인하세요.

  • 적합한 위치가 없다면 새 파일명 생성을 고려하되, 타당한지 메인테이너에게 확인하세요. 로그 파일은 사람들이 한 곳에서 관련 로그를 검색하기 쉽게 만들어야 합니다. 예를 들어, geo.log에는 GitLab Geo에 관련된 모든 로그가 포함되어 있습니다. 새 파일을 만들려면 다음을 수행하세요:

파일명을 선택하세요(예: importer_json.log).

  • Gitlab::JsonLogger의 새 서브클래스를 만드세요:
module Gitlab
  module Import
    class Logger < ::Gitlab::JsonLogger
      def self.file_name_noext
        'importer'
      end
    end
   end
end

기본적으로 Gitlab::JsonLogger는 로그 항목에 애플리케이션 컨텍스트 메타데이터를 포함합니다. 로거가 애플리케이션 요청 외부(예: rake 태스크)에서 호출되거나, 애플리케이션 컨텍스트를 구축하는 데 관여하는 저수준 코드(예: 데이터베이스 연결 코드)에 의해 호출될 것으로 예상되는 경우, 다음과 같이 로거 클래스에서 클래스 메서드 exclude_context!를 호출해야 합니다:

module Gitlab
  module Database
    module LoadBalancing
      class Logger < ::Gitlab::JsonLogger
        exclude_context!

        def self.file_name_noext
          'database_load_balancing'
        end
      end
    end
  end
end
  • 로깅하려는 클래스에서 로거를 인스턴스 변수로 초기화할 수 있습니다:
attr_accessor :logger

def initialize
  @logger = ::Import::Framework::Logger.build
end

로거를 메모이제이션하는 것이 유용합니다. 로그를 남길 때마다 새 로거를 생성하면 파일을 여는 불필요한 오버헤드가 발생하기 때문입니다.

  • 이제 코드에 로그 메시지를 삽입하세요. 로그를 추가할 때 모든 컨텍스트를 키-값 쌍으로 포함하세요:
# BAD
logger.info("Unable to create project #{project.id}")

# GOOD
logger.info(message: "Unable to create project", project_id: project.id)
  • 로그 메시지의 공통 기본 구조를 만들어야 합니다. 예를 들어, 모든 메시지에 current_user_id와 project_id를 포함하면 특정 기간 동안 사용자별 활동을 더 쉽게 검색할 수 있습니다.

JSON 로깅의 암묵적 스키마#

Elasticsearch와 같은 도구를 사용하여 구조화된 로그를 인덱싱할 때, 각 로그 필드의 타입에 대한 스키마가 존재합니다(해당 스키마가 암묵적/추론된 경우에도). 필드 값의 타입을 일관되게 유지하는 것이 중요합니다. 그렇지 않으면 해당 필드에서 검색/필터링이 중단되거나, 심지어 전체 로그 이벤트가 삭제될 수 있습니다. 이 섹션의 많은 내용이 Elasticsearch에 특화된 방식으로 설명되어 있지만, 개념은 구조화된 로그를 인덱싱하는 데 사용하는 여러 시스템에도 적용됩니다. GitLab.com은 로그 데이터 인덱싱에 Elasticsearch를 사용합니다.

필드 타입이 명시적으로 매핑되지 않으면, Elasticsearch는 처음 발견된 필드 값 인스턴스에서 타입을 추론합니다. 이후에 다른 타입의 필드 값 인스턴스가 발생하면 인덱싱에 실패하거나, 일부 경우(스칼라/객체 충돌)에는 전체 로그 라인이 삭제됩니다.

GitLab.com의 로깅 Elasticsearch는 ignore_malformed를 설정하여, 단순한 매핑 충돌(예: 숫자/문자열)이 있어도 문서가 인덱싱될 수 있도록 합니다. 다만 영향을 받은 필드에 대한 인덱싱은 중단됩니다.

예시:

# GOOD
logger.info(message: "Import error", error_code: 1, error: "I/O failure")

# BAD
logger.info(message: "Import error", error: 1)
logger.info(message: "Import error", error: "I/O failure")

# WORST
logger.info(message: "Import error", error: "I/O failure")
logger.info(message: "Import error", error: { message: "I/O failure" })

목록 요소는 같은 타입이어야 합니다:

# GOOD
logger.info(a_list: ["foo", "1", "true"])

# BAD
logger.info(a_list: ["foo", 1, true])

참고 자료:

class 속성 포함하기#

구조화된 로그에는 항상 class 속성을 포함해야 코드의 특정 위치에서 기록된 모든 항목을 찾을 수 있습니다. class 속성을 자동으로 추가하려면 Gitlab::Loggable 모듈을 include하고 build_structured_payload 메서드를 사용하세요.

class MyClass
  include ::Gitlab::Loggable

  def my_method
    logger.info(build_structured_payload(message: 'log message', project_id: project_id))
  end

  private

  def logger
    @logger ||= Gitlab::AppJsonLogger.build
  end
end

소요 시간 로깅#

타임존과 마찬가지로, 로깅에 올바른 시간 단위를 선택하면 불필요한 오버헤드를 줄일 수 있습니다. 초, 밀리초 또는 다른 단위 중에서 선택해야 할 때는 float 형태의 초 (마이크로초 정밀도, 즉 Gitlab::InstrumentationHelper::DURATION_PRECISION)를 선호하세요.

로그에서 타이밍을 추적하기 쉽게 하려면, 로그 키에 _s 접미사를 붙이고 이름에 duration을 포함하세요(예: view_duration_s).

다중 목적지 로깅#

GitLab은 구조화된 로그에서 JSON 로그로 전환했습니다. 그러나 다중 목적지 로깅을 통해 여러 형식으로 로그를 기록할 수 있습니다.

다중 목적지 로깅 사용 방법#

MultiDestinationLogger를 상속하는 새 로거 클래스를 만들고 LOGGERS 상수에 로거 배열을 추가하세요. 로거는 Gitlab::Logger를 상속하는 클래스여야 합니다. 예를 들어, 다음 예시의 사용자 정의 로거는 Gitlab::Logger와 Gitlab::JsonLogger를 상속할 수 있습니다.

primary_logger로 로거 중 하나를 지정해야 합니다. primary_logger는 이 다중 목적지 로거에 대한 정보가 애플리케이션에 표시될 때 사용됩니다 (예: Gitlab::Logger.read_latest 메서드 사용 시).

다음 예시는 정의된 LOGGERS 중 하나를 primary_logger로 설정합니다.

module Gitlab
  class FancyMultiLogger < Gitlab::MultiDestinationLogger
    LOGGERS = [UnstructuredLogger, StructuredLogger].freeze

    def self.loggers
      LOGGERS
    end

    def primary_logger
      UnstructuredLogger
    end
  end
end

이제 이 멀티 로거에서 일반 로깅 메서드를 호출할 수 있습니다. 예를 들면:

FancyMultiLogger.info(message: "Information")

이 메시지는 FancyMultiLogger.loggers에 등록된 각 로거에 의해 기록됩니다.

로깅을 위한 문자열 또는 해시 전달#

MultiDestinationLogger에 문자열이나 해시를 전달하면, 설정된 LOGGERS의 종류에 따라 로그 라인이 다르게 포맷될 수 있습니다.

예를 들어, 이전 예시의 로거를 부분적으로 정의해 보겠습니다:

module Gitlab
  # Similar to AppTextLogger
  class UnstructuredLogger < Gitlab::Logger
    ...
  end

  # Similar to AppJsonLogger
  class StructuredLogger < Gitlab::JsonLogger
    ...
  end
end

다음은 두 로거가 메시지를 처리하는 방법의 예시입니다.

  • 문자열을 전달하는 경우
FancyMultiLogger.info("Information")

# UnstructuredLogger
I, [2020-01-13T18:48:49.201Z #5647]  INFO -- : Information

# StructuredLogger
{:severity=>"INFO", :time=>"2020-01-13T11:02:41.559Z", :correlation_id=>"b1701f7ecc4be4bcd4c2d123b214e65a", :message=>"Information"}
  • 해시를 전달하는 경우
FancyMultiLogger.info({:message=>"This is my message", :project_id=>123})

# UnstructuredLogger
I, [2020-01-13T19:01:17.091Z #11056]  INFO -- : {"message"=>"Message", "project_id"=>"123"}

# StructuredLogger
{:severity=>"INFO", :time=>"2020-01-13T11:06:09.851Z", :correlation_id=>"d7e0886f096db9a8526a4f89da0e45f6", :message=>"This is my message", :project_id=>123}

로깅 컨텍스트 메타데이터 (Rails 또는 Grape 요청을 통해)#

Gitlab::ApplicationContext는 요청 라이프사이클에 메타데이터를 저장하며, 이후 웹 요청이나 Sidekiq 로그에 추가될 수 있습니다.

API, Rails, Sidekiq 로그에는 이 컨텍스트 정보와 함께 meta.로 시작하는 필드가 포함됩니다.

진입점은 다음에서 확인할 수 있습니다:

속성 추가하기#

새 속성을 추가할 때, 위 진입점의 컨텍스트 내에서 노출되는지 확인하고 다음을 수행하세요:

  • with_context (또는 push) 메서드에 해시로 전달하세요 (메서드나 변수가 즉시 평가되면 안 되는 경우 Proc을 전달하세요).

  • Gitlab::ApplicationContext가 새 값을 수락하도록 변경하세요.

  • Labkit::Context에서 새 속성이 허용되는지 확인하세요.

Kibana에서 시각화를 만드는 방법에 대한 추가 지식은 HOWTO: Use Sidekiq metadata logs를 참고하세요.

컨텍스트 필드는 현재 웹 요청을 통해 트리거된 Sidekiq job에 대해서만 로깅됩니다. 자세한 내용은 후속 작업을 참고하세요.

로깅 컨텍스트 메타데이터 (워커를 통해)#

ApplicationWorker#log_extra_metadata_on_done 메서드를 사용하여 워커에 추가 메타데이터를 첨부할 수 있습니다. 이 메서드를 사용하면 완료된 job 페이로드와 함께 나중에 Kibana에 로깅되는 메타데이터가 추가됩니다.

class MyExampleWorker
  include ApplicationWorker

  def perform(*args)
    # Worker performs work
    # ...

    # The contents of value will appear in Kibana under `json.extra.my_example_worker.my_key`
    log_extra_metadata_on_done(:my_key, value)
  end
end

ExpireArtifactsWorker가 실행될 때마다 삭제된 아티팩트의 수를 로깅하는 이 예시를 참고하세요.

예외 처리#

예외를 캐치하고 추적하려는 경우가 종종 있습니다.

수동 예외 로깅은 허용되지 않습니다. 그 이유는 다음과 같습니다:

  • 수동으로 로깅된 예외는 기밀 데이터를 유출할 수 있습니다.

  • 수동으로 로깅된 예외는 종종 백트레이스를 정리해야 하므로 보일러플레이트가 줄어듭니다.

  • 수동으로 로깅된 예외는 Sentry에도 추적되어야 하는 경우가 많습니다.

  • 수동으로 로깅된 예외는 correlation_id를 사용하지 않아, 예외가 발생한 요청, 사용자, 컨텍스트와 연결하기 어렵습니다.

  • 수동으로 로깅된 예외는 여러 파일에 분산되는 경우가 많아 모든 로깅 파일을 스크래핑하는 부담이 증가합니다.

중복을 피하고 일관된 동작을 유지하기 위해 Gitlab::ErrorTracking은 예외를 추적하는 헬퍼 메서드를 제공합니다:

  • Gitlab::ErrorTracking.track_and_raise_exception: 이 메서드는 로깅하고, Sentry에 예외를 전송하며(구성된 경우), 예외를 다시 발생시킵니다.

  • Gitlab::ErrorTracking.track_exception: 이 메서드는 로깅하고 Sentry에 예외를 전송만 합니다(구성된 경우).

  • Gitlab::ErrorTracking.log_exception: 이 메서드는 예외를 로깅만 하고, Sentry에 예외를 전송하지 않습니다.

  • Gitlab::ErrorTracking.track_and_raise_for_dev_exception: 이 메서드는 로깅하고, Sentry에 예외를 전송하며(구성된 경우), 개발 및 테스트 환경에서 예외를 다시 발생시킵니다.

아래 예시와 같이 Gitlab::ErrorTracking.track_and_raise_exception과 Gitlab::ErrorTracking.track_exception만 사용하는 것이 권장됩니다.

추적된 각 예외에 더 많은 컨텍스트를 제공하기 위해 추가 파라미터를 추가하는 것을 고려하세요.

예시#

class MyService < ::BaseService
  def execute
    project.perform_expensive_operation

    success
  rescue => e
    Gitlab::ErrorTracking.track_exception(e, project_id: project.id)

    error('Exception occurred')
  end
end

class MyService < ::BaseService
  def execute
    project.perform_expensive_operation

    success
  rescue => e
    Gitlab::ErrorTracking.track_and_raise_exception(e, project_id: project.id)
  end
end

기본 로깅 위치#

GitLab Self-Managed 및 GitLab.com에서 GitLab은 두 가지 방식으로 배포됩니다:

Omnibus GitLab 로그 처리#

Omnibus GitLab은 /var/log/gitlab 내의 컴포넌트별 디렉터리에 로그를 저장합니다:

# ls -al /var/log/gitlab
total 200
drwxr-xr-x 27 root              root        4096 Apr 29 20:28 .
drwxrwxr-x 19 root              syslog      4096 Aug  5 04:08 ..
drwx------  2 gitlab-prometheus root        4096 Aug  6 04:08 alertmanager
drwx------  2 root              root        4096 Aug  6 04:08 crond
drwx------  2 git               root        4096 Aug  6 04:08 gitaly
drwx------  2 git               root        4096 Aug  6 04:08 gitlab-exporter
drwx------  2 git               root        4096 Aug  6 04:08 gitlab-kas
drwx------  2 git               root       45056 Aug  6 13:18 gitlab-rails
drwx------  2 git               root        4096 Aug  5 04:18 gitlab-shell
drwx------  2 git               root        4096 May 24  2023 gitlab-sshd
drwx------  2 git               root        4096 Aug  6 04:08 gitlab-workhorse
drwxr-xr-x  2 root              root       12288 Aug  1 00:20 lets-encrypt
drwx------  2 root              root        4096 Aug  6 04:08 logrotate
drwx------  2 git               root        4096 Aug  6 04:08 mailroom
drwxr-x---  2 root              gitlab-www 12288 Aug  6 00:18 nginx
drwx------  2 gitlab-prometheus root        4096 Aug  6 04:08 node-exporter
drwx------  2 gitlab-psql       root        4096 Aug  6 15:00 pgbouncer
drwx------  2 gitlab-psql       root        4096 Aug  6 04:08 postgres-exporter
drwx------  2 gitlab-psql       root        4096 Aug  6 04:08 postgresql
drwx------  2 gitlab-prometheus root        4096 Aug  6 04:08 prometheus
drwx------  2 git               root        4096 Aug  6 04:08 puma
drwxr-xr-x  2 root              root       32768 Aug  1 21:32 reconfigure
drwx------  2 gitlab-redis      root        4096 Aug  6 04:08 redis
drwx------  2 gitlab-redis      root        4096 Aug  6 04:08 redis-exporter
drwx------  2 registry          root        4096 Aug  6 04:08 registry
drwx------  2 gitlab-redis      root        4096 May  6 06:30 sentinel
drwx------  2 git               root        4096 Aug  6 13:05 sidekiq

위 예시에서 다음 컴포넌트들이 아래 디렉터리에 로그를 저장하는 것을 확인할 수 있습니다:

컴포넌트 로그 디렉터리
GitLab Rails /var/log/gitlab/gitlab-rails
Gitaly /var/log/gitlab/gitaly
Sidekiq /var/log/gitlab/sidekiq
GitLab Workhorse /var/log/gitlab/gitlab-workhorse

GitLab Rails 디렉터리가 아마도 위의 Ruby 코드에서 사용되는 로그 파일을 찾을 위치일 것입니다.

logrotate는 모든 *.log 파일을 감시하는 데 사용됩니다.

Cloud Native GitLab 로그 처리#

Cloud Native GitLab Pod는 추가 하위 디렉터리를 만들지 않고 GitLab 로그를 직접 /var/log/gitlab에 씁니다. 예를 들어, webservice Pod는 하나의 컨테이너에서 gitlab-workhorse를 실행하고 다른 컨테이너에서 puma를 실행합니다. 후자의 로그 파일 디렉터리는 다음과 같습니다:

git@gitlab-webservice-default-bbd9647d9-fpwg5:/$ ls -al /var/log/gitlab
total 181420
drwxr-xr-x 2 git  git       4096 Aug  2 22:58 .
drwxr-xr-x 4 root root      4096 Aug  2 22:57 ..
-rw-r--r-- 1 git  git          0 Aug  2 18:22 .gitkeep
-rw-r--r-- 1 git  git   46524128 Aug  6 20:18 api_json.log
-rw-r--r-- 1 git  git      19009 Aug  2 22:58 application_json.log
-rw-r--r-- 1 git  git        157 Aug  2 22:57 auth_json.log
-rw-r--r-- 1 git  git       1116 Aug  2 22:58 database_load_balancing.log
-rw-r--r-- 1 git  git         67 Aug  2 22:57 grpc.log
-rw-r--r-- 1 git  git          0 Aug  2 22:57 production.log
-rw-r--r-- 1 git  git  138436632 Aug  6 20:18 production_json.log
-rw-r--r-- 1 git  git         48 Aug  2 22:58 puma.stderr.log
-rw-r--r-- 1 git  git        266 Aug  2 22:58 puma.stdout.log
-rw-r--r-- 1 git  git         67 Aug  2 22:57 service_measurement.log
-rw-r--r-- 1 git  git         67 Aug  2 22:57 sidekiq_client.log
-rw-r--r-- 1 git  git     733809 Aug  6 20:18 web_exporter.log

gitlab-logger는 /var/log/gitlab의 모든 파일을 tail하는 데 사용됩니다. 각 로그 라인은 필요에 따라 JSON으로 변환되어 stdout으로 전송되므로 kubectl logs를 통해 확인할 수 있습니다.

새 로그 파일 추가 시 추가 단계#

  • 로그 보존 설정을 고려하세요. 기본적으로 Omnibus는 /var/log/gitlab/gitlab-rails/*.log의 모든 로그를 매시간 교체하고 최대 30개의 압축 파일을 유지합니다. GitLab.com에서는 해당 설정이 압축 파일 6개에 불과합니다. 이 설정은 대부분의 사용자에게 충분하지만, Omnibus GitLab에서 조정이 필요할 수 있습니다.

  • GitLab.com에서 GitLab Rails가 생성하는 모든 새 JSON 로그 파일은 GitLab Rails 쿠버네티스 Pod에서 Elasticsearch로 자동 전송됩니다(Kibana에서 사용 가능). Gitaly 노드에서도 파일을 전달해야 하는 경우 프로덕션 트래커에 이슈를 제출하거나 gitlab_fluentd 프로젝트에 머지 리퀘스트를 제출하세요. 이 예시를 참고하세요.

  • GitLab CE/EE 문서와 GitLab.com 런북을 반드시 업데이트하세요.

Kibana에서 새 로그 파일 찾기 (GitLab.com 전용)#

GitLab.com에서 GitLab Rails가 생성하는 모든 새 JSON 로그 파일은 GitLab Rails 쿠버네티스 Pod에서 Elasticsearch로 자동 전송됩니다(Kibana에서 사용 가능). Kibana의 json.subcomponent 필드를 사용하면 다양한 종류의 로그 파일로 필터링할 수 있습니다. 예를 들어, production_json.log에서 전달된 항목의 json.subcomponent는 production_json이 됩니다.

Web/API Pod의 로그 파일은 Sidekiq Pod의 로그 파일과 다른 인덱스로 이동된다는 점도 알아두세요. 로그를 기록하는 위치에 따라 다른 인덱스 패턴에서 로그를 찾게 됩니다.

로깅 가시성 제어#

로그가 증가하면 미처리 메시지의 백로그가 늘어날 수 있습니다. 새 로그 메시지를 추가할 때 전체 로깅 볼륨이 10% 이상 증가하지 않도록 하세요.

지원 중단 알림#

지원 중단 알림의 예상 볼륨이 큰 경우:

  • 개발 환경에서만 로깅하세요.

  • 필요한 경우 테스트 환경에서도 로깅하세요.