CI/CD job 로그

CI/CD job 로그 (CI/CD job logs)

job 로그는 CI/CD job의 전체 실행 이력을 보여주는 화면이에요. 파이프라인이 어떤 순서로 어떤 명령을 실행했는지, 어디서 실패했는지를 하나하나 추적해서 디버깅할 수 있습니다.

출처: 문서

본문

job 로그 보기 (View job logs)

job 로그를 보는 방법은 이렇습니다.

job 로그를 보려는 프로젝트를 선택합니다.
왼쪽 사이드바에서 CI/CD > Pipelines를 선택합니다.
확인하려는 파이프라인을 선택합니다.
파이프라인 보기의 job 목록에서 job을 선택하면 job 로그 페이지가 열립니다.

job과 로그 출력에 대한 자세한 정보를 보려면 job 로그 페이지를 스크롤하면 돼요.

전체 화면 모드로 job 로그 보기 (View job logs in full screen mode)

Show full screen을 클릭하면 job 로그 내용을 전체 화면 모드로 볼 수 있어요. 전체 화면 모드를 쓰려면 웹 브라우저가 이를 지원해야 합니다. 브라우저가 전체 화면 모드를 지원하지 않으면 해당 옵션이 표시되지 않아요.

job 로그 섹션 펼치기·접기 (Expand and collapse job log sections)

bash 셸의 다중 줄 명령 출력은 FF_SCRIPT_SECTIONS라는 기능 플래그와 함께 GitLab 16.5에서 도입됐어요. 기본적으로 비활성화되어 있습니다.

[!제목] 이 기능의 가용성은 기능 플래그가 제어합니다. 자세한 내용은 변경 내역(history)을 참고하세요.

FF_SCRIPT_SECTIONS가 활성화되면 다중 줄 스크립트 명령이 job 로그에서 접을 수 있는 섹션으로 나타나요. 단일 줄 명령은 $ 접두사와 함께 바로 출력됩니다. 지속 시간은 표시되지 않습니다. powershell과 pwsh 셸에서는 FF_SCRIPT_SECTIONS가 접을 수 있는 섹션을 만들지 않아요. 명령이 색상 출력으로만 표시됩니다.

사용자 지정 접을 수 있는 섹션 만들기 (Create custom collapsible sections)

GitLab이 접을 수 있는 섹션을 구분할 때 쓰는 특수 코드를 직접 출력해서 job 로그에 접을 수 있는 섹션을 만들 수 있어요.

섹션 시작 마커: \e[0Ksection_start:UNIX_TIMESTAMP:SECTION_NAME\r\e[0K + TEXT_OF_SECTION_HEADER
섹션 끝 마커: \e[0Ksection_end:UNIX_TIMESTAMP:SECTION_NAME\r\e[0K

이 코드들을 CI 구성의 script 섹션에 추가해야 해요. printf를 쓰는 예시입니다.

job1:
  script:
    - printf '\e[0Ksection_start:%d:%s\r\e[0K%s\n' "$(date +%s)" 'my_first_section' 'Header of the 1st collapsible section'
    - echo 'this line should be hidden when collapsed'
    - printf '\e[0Ksection_end:%d:%s\r\e[0K\n' "$(date +%s)" 'my_first_section'

위 예시에서:

date +%s: Unix 타임스탬프(예: 1560896352)를 만드는 명령.
my_first_section: 섹션에 주어진 이름. 이름은 문자, 숫자, _, ., - 문자로만 구성할 수 있어요.
\r\e[0K: 섹션 마커가 렌더링된(색상) job 로그에 표시되지 않게 하는 이스케이프 시퀀스. job 로그 오른쪽 위의 Show complete raw( )를 선택해 접근하는 원본 raw job 로그에서는 표시됩니다.
- \r: 캐리지 리턴(커서를 줄의 시작으로 되돌림).
- \e[0K: 커서 위치부터 줄 끝까지 지우는 ANSI 이스케이프 코드. (\e[K만으로는 동작하지 않고 0이 꼭 포함되어야 해요.)

raw job 로그 샘플:

\e[0Ksection_start:1560896352:my_first_section\r\e[0KHeader of the 1st collapsible section
this line should be hidden when collapsed
\e[0Ksection_end:1560896353:my_first_section\r\e[0K

job 콘솔 로그 샘플:

스크립트로 섹션 표시 개선하기 (Improve section display with a script)

job 출력에서 섹션 마커를 만드는 printf 문을 제거하려면 job 내용을 스크립트 파일로 옮기고 job에서 호출하면 돼요.

섹션 헤더를 처리할 스크립트를 만듭니다. 예를 들면 이렇습니다.

# Function for starting the section
section_start () {
  local section_title="${1}"
  local section_description="${2:-$section_title}"

  printf '\e[0Ksection_start:%d:%s[collapsed=true]\r\e[0K%s\n' "$(date +%s)" "$section_title" "$section_description"
}

# Function for ending the section
section_end () {
  local section_title="${1}"

  printf '\e[0Ksection_end:%d:%s\r\e[0K\n' "$(date +%s)" "$section_title"
}

# Create sections
section_start "my_first_section" "Header of the 1st collapsible section"

echo "this line should be hidden when collapsed"

section_end "my_first_section"

# Repeat as required

스크립트를 .gitlab-ci.yml 파일에 추가합니다.

job:
  script:
    - source script.sh

섹션을 기본으로 접어 두기 (Collapse sections by default)

섹션을 기본으로 접어 두려면 섹션 이름 뒤, \r 앞에 [collapsed=true]를 섹션 시작 마커에 추가하면 돼요.

[collapsed=true]가 있는 섹션 시작 마커: \e[0Ksection_start:UNIX_TIMESTAMP:SECTION_NAME[collapsed=true]\r\e[0K + TEXT_OF_SECTION_HEADER
섹션 끝 마커(변경 없음): \e[0Ksection_end:UNIX_TIMESTAMP:SECTION_NAME\r\e[0K

갱신한 섹션 시작 텍스트를 CI 구성에 추가합니다. printf를 쓰는 예시입니다.

job1:
  script:
    - printf '\e[0Ksection_start:%d:%s[collapsed=true]\r\e[0K%s\n' "$(date +%s)" 'my_first_section' 'Header of the 1st collapsible section'
    - echo 'this line should be hidden automatically after loading the job log'
    - printf '\e[0Ksection_end:%d:%s\r\e[0K\n' "$(date +%s)" 'my_first_section'

job 로그 삭제 (Delete job logs)

job 로그를 삭제하면 job 전체를 삭제(erase)하게 돼요. 자세한 내용은 job 로그 삭제 문서를 참고하세요.

타임스탬프 (Timestamps)

GitLab 17.1에서 parse_ci_job_timestamps라는 기능 플래그와 함께 도입. 기본적으로 비활성화.
기능 플래그 parse_ci_job_timestamps는 GitLab 17.2에서 제거.
GitLab 18.9에서 일반 공개.

기본적으로 job 로그의 각 줄에는 ISO 8601 형식의 타임스탬프가 포함돼요. 타임스탬프로 성능 문제를 트러블슈팅하거나 병목을 찾거나 특정 빌드 단계가 얼마나 걸리는지 측정할 수 있습니다. 타임스탬프가 활성화되면 job 로그는 저장 공간을 약 10% 더 사용해요.

타임스탬프가 있는 job 로그 예시는 이렇습니다.

job 로그에서 타임스탬프 제어하기 (Control timestamps in job logs)

사전 요구사항은 이렇습니다.

GitLab Runner 18.7 이상.

job 로그에 타임스탬프가 표시될지 여부는 FF_TIMESTAMPS CI/CD 변수로 제어할 수 있어요.

false로 설정하면 타임스탬프 비활성화.
true로 설정하면 타임스탬프를 명시적으로 활성화.

예를 들면 이렇습니다.

variables:
  FF_TIMESTAMPS: false  # Disables timestamps

job:
  script:
    - echo "This job's log behavior depends on FF_TIMESTAMPS value"

자세한 내용은 .gitlab-ci.yml 파일에서 CI/CD 변수 정의 문서를 참고하세요.

트러블슈팅 (Troubleshooting)

job 로그 업데이트가 느려요 (Job log slow to update)

실행 중인 job의 로그 페이지를 방문하면 로그가 업데이트되기까지 최대 60초까지 지연될 수 있어요. 기본 새로고침 시간은 60초지만, UI에서 로그를 한 번 본 뒤에는 로그 업데이트가 3초마다 이뤄져야 합니다.

GitLab 18.0 이상에서 `This job does not have a trace` 오류 (Error: `This job does not have a trace` in GitLab 18.0 or later)

GitLab Self-Managed 인스턴스를 18.0 이상으로 업그레이드한 뒤 This job does not have a trace 오류가 보일 수 있어요. 이는 다음 두 가지가 모두 해당하는 인스턴스에서 업그레이드 마이그레이션이 실패했을 때 발생할 수 있습니다.

오브젝트 스토리지가 활성화되어 있고.
제거된 기능 플래그 ci_enable_live_trace로 증분 로깅이 이전에 활성화되어 있는 경우. 이 기능 플래그는 GitLab Environment Toolkit이나 Helm Chart 배포에서 기본으로 활성화되지만, 수동으로 활성화할 수도 있어요.

영향을 받는 job의 로그를 보려면 증분 로깅을 다시 활성화하세요.

더 알아보기

job 로그는 파이프라인 실행의 '디버깅 기록'이에요. FF_SCRIPT_SECTIONS로 다중 줄 명령을 접을 수 있는 섹션으로 묶고, 직접 section_start/section_end 마커로 사용자 지정 섹션을 만들어 로그를 깔끔하게 유지할 수 있습니다. 타임스탬프는 각 줄마다 시간을 확인해 빌드 단계별 병목을 찾는 데 유용해요. 로그가 느리게 갱신되거나 'no trace' 오류가 나면 러너·인스턴스 설정을 점검해 보세요.