Observability용 CI/CD 파이프라인 텔레메트리 표시
GitLab v19.6Offering: GitLab.com
요약
활성화하면 GitLab Observability가 CI/CD 파이프라인을 자동으로 계측하여, 코드 변경 없이도 파이프라인 성능·job 지속 시간·실행 흐름에 대한 가시성을 제공합니다. 자동 파이프라인 계측을 활성화하려면 프로젝트 또는 그룹에 GITLAB_OBSERVABILITY_EXPORT CI/CD 변수를 추가합니다:
활성화하면 GitLab Observability가 CI/CD 파이프라인을 자동으로 계측하여, 코드 변경 없이도 파이프라인 성능·job 지속 시간·실행 흐름에 대한 가시성을 제공합니다.
- 파이프라인을 지연시키는 job을 파악할 수 있는 가시성을 제공합니다.
- 파이프라인 성능이 시간에 따라 어떻게 변화하는지 보여줍니다.
- 배포 프로세스의 병목 구간을 나타냅니다.
파이프라인 계측 활성화#
자동 파이프라인 계측을 활성화하려면 프로젝트 또는 그룹에 GITLAB_OBSERVABILITY_EXPORT CI/CD 변수를 추가합니다:
- 상단 바에서 Search or go to를 선택하고 프로젝트 또는 그룹을 찾습니다.
- 왼쪽 사이드바에서 Settings > CI/CD를 선택합니다.
- Variables를 펼칩니다.
- Add variable을 선택합니다.
- 다음과 같이 변수를 구성합니다:
- Key:
GITLAB_OBSERVABILITY_EXPORT - Value:
traces,metrics,logs중 하나 이상(여러 개를 지정할 때는 쉼표로 구분) - Type: Variable
- Environment scope: All(또는 특정 환경)
- Key:
- Add variable을 선택합니다.
내보낸 데이터 인증#
기본적으로 GitLab Observability의 OpenTelemetry Protocol(OTLP) 엔드포인트는 인증 없이 텔레메트리를 수신합니다. 호출자가 bearer 토큰을 전송하도록 요구하여, 유효한 토큰을 가진 클라이언트만 인스턴스로 파이프라인 텔레메트리를 전송할 수 있도록 제한할 수 있습니다.
인증에는 두 가지 측면이 있습니다.
- GitLab Observability에서는 토큰을 생성·관리하고, 인스턴스별로 강제 적용 여부를 켜거나 끕니다.
- GitLab에서는 해당 토큰을 CI/CD 변수에 저장하여, 파이프라인 익스포터가 텔레메트리와 함께 토큰을 전송하도록 합니다.
GITLAB_OBSERVABILITY_TOKEN CI/CD 변수가 설정되어 있으면, GitLab은 내보내는 텔레메트리에
해당 값을 Authorization: Bearer <token> 헤더로 전송합니다. 변수가 설정되어 있지 않으면
GitLab은 Authorization 헤더 없이 데이터를 내보냅니다.
강제 적용은 GitLab Observability API를 통해서만 사용할 수 있습니다. 다음 예시에서는 curl
을 사용하며 SIGNOZ-API-KEY 헤더로 인증합니다. API 키를 받는 방법은
Observability API 액세스를 참고합니다. Editor 권한 또는 관리자 액세스
권한이 있는 사용자만 토큰을 관리하거나 강제 적용을 변경할 수 있습니다. 예시의 <api_key>와
<instance_url>은 실제 값으로 바꿉니다.
GitLab Observability에서 토큰 생성#
수집 토큰(ingest token)은 otel-ingest 서비스 계정의 API 키입니다. API로 생성합니다:
curl --request POST \
--header "SIGNOZ-API-KEY: <api_key>" \
--header "Content-Type: application/json" \
--data '{"name": "ci-cd-export"}' \
--url "<instance_url>/api/v1/ingest_auth/tokens"
응답에는 token 필드에 토큰 값이 담겨 있습니다. 이 값은 토큰을 생성할 때만 반환되므로 즉시
복사해 둡니다.
UI에서도 Observe > API Keys에서 토큰을 생성할 수 있습니다.
만료 기간이 없는 토큰(기본값)을 사용하는 것이 좋습니다. GitLab Observability는 토큰이 만료되기 전에 알려주지 않으며, 만료된 토큰은 더 이상 허용되지 않아 텔레메트리 수집이 조용히 중단됩니다. 토큰을 교체할 때는 만료 대신 순환(rotation)을 사용합니다. 토큰 순환을 참고합니다.
당분간은 강제 적용을 비활성화 상태로 둡니다. 엔드포인트가 인증되지 않은 텔레메트리를 거부하기 시작하지 않도록, 강제 적용을 활성화하기 전에 파이프라인에 토큰을 먼저 배포합니다.
GitLab에 토큰 설정#
계측된 파이프라인을 실행하는 프로젝트 또는 그룹에 토큰을 추가합니다:
- 상단 바에서 Search or go to를 선택하고 프로젝트 또는 그룹을 찾습니다.
- 왼쪽 사이드바에서 Settings > CI/CD를 선택합니다.
- Variables를 펼칩니다.
- Add variable을 선택합니다.
- 다음과 같이 변수를 구성합니다:
- Key:
GITLAB_OBSERVABILITY_TOKEN - Value: GitLab Observability에서 생성한 토큰
- Type: Variable
- Flags: job 로그에 토큰이 노출되지 않도록 Mask variable을 선택합니다.
- Key:
- Add variable을 선택합니다.
강제 적용 활성화#
GitLab에 토큰을 설정하고 인스턴스로 텔레메트리를 전송하는 다른 모든 클라이언트가 이를 적용한 후, API로 강제 적용을 켭니다:
curl --request PUT \
--header "SIGNOZ-API-KEY: <api_key>" \
--header "Content-Type: application/json" \
--data '{"enabled": true}' \
--url "<instance_url>/api/v1/ingest_auth/state"
강제 적용을 다시 끄려면 같은 엔드포인트로 {"enabled": false}를 전송합니다. 현재 상태를
확인하려면 해당 엔드포인트에 GET 요청을 보냅니다.
이 변경 사항은 컬렉터를 재시작하지 않아도 즉시 적용됩니다. 강제 적용이 켜지면 OTLP 엔드포인트는 유효한 토큰이 없는 텔레메트리를 모두 거부합니다.
이 파이프라인 익스포트를 포함해, 인스턴스로 텔레메트리를 전송하는 모든 클라이언트가 유효한 토큰을 보유한 후에만 강제 적용을 활성화합니다. 클라이언트가 토큰을 적용하기 전에 강제 적용을 활성화하면 해당 클라이언트의 텔레메트리가 거부됩니다.
토큰 순환#
인스턴스는 동시에 두 개 이상의 유효한 토큰을 허용하므로, 텔레메트리 손실 없이 토큰을 교체하려면 토큰을 순환시킵니다:
-
GitLab Observability에서 토큰 생성에 설명된 대로 새 토큰을 생성합니다.
-
GITLAB_OBSERVABILITY_TOKEN변수(및 다른 모든 클라이언트)를 새 토큰 값으로 업데이트합니다. 이전 토큰과 새 토큰이 모두 존재하는 동안에는 둘 다 유효하므로 텔레메트리 내보내기에 공백이 생기지 않습니다. -
이전 토큰을 폐기합니다. 토큰 목록을 조회해 ID를 확인한 후 삭제합니다:
curl --request GET \ --header "SIGNOZ-API-KEY: <api_key>" \ --url "<instance_url>/api/v1/ingest_auth/tokens" curl --request DELETE \ --header "SIGNOZ-API-KEY: <api_key>" \ --url "<instance_url>/api/v1/ingest_auth/tokens/<token_id>"
강제 적용이 켜져 있는 동안에는 마지막으로 남은 유효한 토큰을 폐기할 수 없습니다. 폐기하면 모든 텔레메트리가 거부되기 때문입니다. 먼저 대체 토큰을 생성하거나 강제 적용을 비활성화합니다.
계측 유형#
GITLAB_OBSERVABILITY_EXPORT 변수는 다음 값을 허용합니다:
traces: 파이프라인 실행 흐름, job 의존성, 타이밍을 보여주는 분산 트레이스를 내보냅니다metrics: 파이프라인 지속 시간, job 성공률, 리소스 사용량에 대한 메트릭을 내보냅니다logs: 파이프라인 실행에서 구조화된 로그를 내보냅니다
쉼표로 구분하여 여러 유형을 동시에 활성화할 수 있습니다:
traces,metrics,logs
내보내는 데이터#
GitLab은 각 신호 유형을 OpenTelemetry Protocol(OTLP) 데이터로 내보냅니다.
모든 속성은 기존 GitLab 네임스페이스(pipeline.*, job.*, gitlab.*)와, 대응하는 항목이
있는 경우 동등한 OpenTelemetry CI/CD semantic convention
네임스페이스(cicd.*, vcs.*) 양쪽에서 함께 방출됩니다.
트레이스#
히스토리
- GitLab 19.6에서 job 요청 태그 속성이 추가되었습니다.
각 파이프라인은 파이프라인 span 하나와, 파이프라인 내 각 job 또는 bridge에 대한 job span 하나를 포함하는 단일 리소스 span으로 내보내집니다.
리소스는 다음 속성을 포함합니다:
| 속성 | Description |
|---|---|
service.name |
설정된 서비스 이름. 설정하지 않은 경우 프로젝트 이름입니다. |
service.version |
GitLab 버전입니다(예: 19.6.0). |
deployment.environment |
설정된 환경. 설정하지 않은 경우 production 입니다. |
vcs.provider.name |
고정 값 gitlab 입니다. |
vcs.repository.name |
프로젝트 이름입니다. |
gitlab.vcs.repository.id |
프로젝트 ID입니다. |
vcs.repository.url.full |
프로젝트의 웹 URL입니다. |
vcs.owner.name |
프로젝트를 소유한 네임스페이스입니다. |
파이프라인 span은 다음 속성을 포함합니다:
| 속성 | Description |
|---|---|
pipeline.id |
파이프라인의 ID입니다. |
pipeline.iid |
파이프라인의 프로젝트 범위 내부 ID입니다(확인 가능한 경우). |
pipeline.name |
파이프라인의 이름입니다. |
pipeline.ref |
파이프라인이 실행된 브랜치 또는 태그입니다. |
pipeline.sha |
파이프라인이 실행된 커밋 SHA입니다. |
pipeline.status |
파이프라인 상태입니다(예: success, failed). |
pipeline.detailed_status |
UI에 표시되는 상세 상태 텍스트입니다. |
pipeline.duration |
파이프라인 지속 시간(초)입니다. |
pipeline.queued_duration |
파이프라인이 대기열에 머문 시간(초)입니다. |
pipeline.protected_ref |
파이프라인이 보호된 브랜치 또는 태그에서 실행되었는지 여부입니다. |
pipeline.url |
파이프라인의 URL입니다. |
pipeline.tag |
파이프라인이 태그에서 실행되었는지 여부입니다(정보가 있는 경우). |
pipeline.before_sha |
파이프라인 실행 전의 커밋 SHA입니다(확인 가능한 경우). |
pipeline.stages |
파이프라인 Stage 이름의 배열입니다(확인 가능한 경우). |
pipeline.user.id |
파이프라인을 트리거한 사용자의 ID입니다(확인 가능한 경우). |
pipeline.user.username |
파이프라인을 트리거한 사용자의 사용자 이름입니다(확인 가능한 경우). |
pipeline.commit.id |
파이프라인과 연결된 커밋의 SHA입니다(확인 가능한 경우). |
pipeline.commit.message |
파이프라인과 연결된 커밋의 메시지입니다(확인 가능한 경우). |
pipeline.merge_request.id |
파이프라인이 연결된 머지 리퀘스트의 ID입니다(파이프라인이 머지 리퀘스트용으로 실행된 경우). |
pipeline.merge_request.iid |
파이프라인이 연결된 머지 리퀘스트의 내부 ID입니다(파이프라인이 머지 리퀘스트용으로 실행된 경우). |
pipeline.source_pipeline.pipeline_id |
상위 파이프라인의 ID입니다(하위 파이프라인 또는 다중 프로젝트 파이프라인의 경우). |
cicd.pipeline.name |
파이프라인의 이름입니다. |
cicd.pipeline.result |
파이프라인 결과입니다. Attribute value mapping을 참고합니다. |
cicd.pipeline.run.id |
파이프라인의 ID(문자열)입니다. |
cicd.pipeline.run.state |
파이프라인 실행 상태입니다. Attribute value mapping을 참고합니다. |
cicd.pipeline.run.url.full |
파이프라인의 URL입니다. |
vcs.ref.head.name |
파이프라인이 실행된 브랜치 또는 태그입니다. |
vcs.ref.head.revision |
파이프라인이 실행된 커밋 SHA입니다. |
vcs.ref.head.type |
tag 또는 branch 중 하나입니다. |
vcs.ref.base.revision |
파이프라인 실행 전의 커밋 SHA입니다(확인 가능한 경우). |
vcs.change.id |
파이프라인이 연결된 머지 리퀘스트의 내부 ID(문자열)입니다(파이프라인이 머지 리퀘스트용으로 실행된 경우). |
vcs.change.title |
파이프라인이 연결된 머지 리퀘스트의 제목입니다(파이프라인이 머지 리퀘스트용으로 실행된 경우). |
vcs.change.state |
연결된 머지 리퀘스트의 상태입니다. Attribute value mapping을 참고합니다. |
vcs.ref.base.name |
연결된 머지 리퀘스트의 대상 브랜치입니다(파이프라인이 머지 리퀘스트용으로 실행된 경우). |
gitlab.vcs.ref.head.revision.message |
파이프라인과 연결된 커밋의 메시지입니다(확인 가능한 경우). |
gitlab.cicd.pipeline.run.duration |
파이프라인 지속 시간(초)입니다. |
gitlab.cicd.pipeline.run.queued_duration |
파이프라인이 대기열에 머문 시간(초)입니다. |
gitlab.cicd.pipeline.source_pipeline.id |
상위 파이프라인의 ID입니다(하위 파이프라인 또는 다중 프로젝트 파이프라인의 경우). |
gitlab.cicd.pipeline.stages |
파이프라인 Stage 이름의 배열입니다(확인 가능한 경우). |
gitlab.cicd.pipeline.trigger.type |
파이프라인을 트리거한 이벤트입니다(예: push, schedule). |
gitlab.cicd.pipeline.user.id |
파이프라인을 트리거한 사용자의 ID입니다(확인 가능한 경우). |
gitlab.cicd.pipeline.user.username |
파이프라인을 트리거한 사용자의 사용자 이름입니다(확인 가능한 경우). |
gitlab.vcs.ref.head.protected |
파이프라인이 보호된 브랜치 또는 태그에서 실행되었는지 여부입니다. |
job span은 각 job 또는 bridge에 대해 다음 속성을 포함합니다:
| 속성 | Description |
|---|---|
job.id |
job의 ID입니다. |
job.name |
job의 이름입니다. |
job.stage |
job 이 속한 Stage입니다. |
job.status |
job 상태입니다(예: success, failed). |
job.duration |
job 지속 시간(초)입니다. |
job.queued_duration |
job 이 대기열에 머문 시간(초)입니다. |
job.manual |
job 실행에 수동 작업이 필요한지 여부입니다. |
job.allow_failure |
job 이 실패해도 파이프라인 결과에 영향을 주지 않도록 허용되는지 여부입니다. |
job.failure_reason |
job이 실패한 경우 그 사유입니다. Job 실패 증거를 참고합니다. |
job.exit_code |
job이 실패한 경우 GitLab이 저장한 종료 코드입니다(있는 경우). Job 실패 증거를 참고합니다. |
job.type |
다운스트림 파이프라인을 트리거하는 job에는 값 bridge가 들어갑니다. |
job.created_at |
job 이 생성된 시각입니다(Unix 나노초). |
job.when |
job 실행 여부를 결정한 rules 또는 when 키워드 값입니다(확인 가능한 경우). |
job.user.id |
job과 연결된 사용자의 ID입니다(확인 가능한 경우). |
job.user.username |
job과 연결된 사용자의 사용자 이름입니다(확인 가능한 경우). |
job.artifacts.filename |
job 이 아티팩트를 생성한 경우 해당 아티팩트 아카이브의 파일 이름입니다. |
job.artifacts.size |
job 이 아티팩트를 생성한 경우 해당 아티팩트 아카이브의 크기(바이트)입니다. |
job.runner.id |
job에 러너가 있는 경우 해당 job을 실행한 러너의 ID입니다. |
job.runner.description |
job에 러너가 있는 경우 해당 job을 실행한 러너의 설명입니다. |
job.runner.tags |
job에 러너가 있는 경우 해당 job을 실행한 러너의 태그입니다. |
job.runner.type |
러너 유형입니다(예: instance_type, project_type, 확인 가능한 경우). |
job.runner.active |
러너가 활성 상태인지 여부입니다(확인 가능한 경우). |
job.runner.is_shared |
러너가 여러 프로젝트에서 공유되는지 여부입니다(확인 가능한 경우). |
job.environment.name |
job에 환경이 있는 경우 해당 job 이 배포되는 환경의 이름입니다. |
job.environment.action |
job에 환경이 있는 경우 배포 액션입니다(예: start, stop). |
job.environment.deployment_tier |
환경의 배포 티어입니다(확인 가능한 경우). |
cicd.pipeline.task.name |
job의 이름입니다. |
cicd.pipeline.task.run.id |
job의 ID(문자열)입니다. |
cicd.pipeline.task.run.result |
job 결과입니다. Attribute value mapping을 참고합니다. |
cicd.pipeline.task.run.state |
job 실행 상태입니다. Attribute value mapping을 참고합니다. |
cicd.pipeline.task.run.url.full |
job의 URL입니다. |
cicd.pipeline.task.type |
job 이 속한 Stage입니다. |
gitlab.cicd.pipeline.task.allow_failure |
job 이 실패해도 파이프라인 결과에 영향을 주지 않도록 허용되는지 여부입니다. |
gitlab.cicd.pipeline.task.kind |
다운스트림 파이프라인을 트리거하는 job에는 값 bridge가 들어갑니다. |
gitlab.cicd.pipeline.task.run.created_at |
job 이 생성된 시각입니다(Unix 나노초). |
gitlab.cicd.pipeline.task.run.duration |
job 지속 시간(초)입니다. |
gitlab.cicd.pipeline.task.run.failure_reason |
job이 실패한 경우 그 사유입니다. Job 실패 증거를 참고합니다. |
gitlab.cicd.pipeline.task.run.exit_code |
job이 실패한 경우 GitLab이 저장한 종료 코드입니다(있는 경우). Job 실패 증거를 참고합니다. |
gitlab.cicd.pipeline.task.run.queued_duration |
job 이 대기열에 머문 시간(초)입니다. |
gitlab.cicd.pipeline.task.run.when |
job 실행 여부를 결정한 rules 또는 when 키워드 값입니다(확인 가능한 경우). |
gitlab.cicd.pipeline.task.trigger.type |
파이프라인을 트리거한 이벤트입니다(예: push, schedule). |
gitlab.cicd.pipeline.task.tags |
job이 요청한 태그이며 정렬되어 있습니다. 태그가 없는 job에서는 비어 있습니다. bridge job에는 설정되지 않습니다. |
gitlab.cicd.pipeline.task.tag_set |
job이 요청한 태그를 정렬된 JSON 배열로 나타낸 값입니다(예: ["docker","linux"]). 태그가 없는 job과 bridge job에는 설정되지 않습니다. |
gitlab.cicd.pipeline.task.untagged |
job이 태그를 요청하지 않았는지 여부입니다. bridge job에는 설정되지 않습니다. |
gitlab.cicd.pipeline.task.artifacts.filename |
job 이 아티팩트를 생성한 경우 해당 아티팩트 아카이브의 파일 이름입니다. |
gitlab.cicd.pipeline.task.artifacts.size |
job 이 아티팩트를 생성한 경우 해당 아티팩트 아카이브의 크기(바이트)입니다. |
gitlab.cicd.pipeline.task.environment.action |
job에 환경이 있는 경우 배포 액션입니다(예: start, stop). |
gitlab.cicd.pipeline.task.environment.deployment_tier |
환경의 배포 티어입니다(확인 가능한 경우). |
gitlab.cicd.pipeline.task.environment.name |
job에 환경이 있는 경우 해당 job 이 배포되는 환경의 이름입니다. |
gitlab.cicd.pipeline.task.user.id |
job과 연결된 사용자의 ID입니다(확인 가능한 경우). |
gitlab.cicd.pipeline.task.user.username |
job과 연결된 사용자의 사용자 이름입니다(확인 가능한 경우). |
cicd.worker.id |
job에 러너가 있는 경우 해당 job을 실행한 러너의 ID(문자열)입니다. |
cicd.worker.name |
job에 러너가 있는 경우 해당 job을 실행한 러너의 설명입니다. |
cicd.worker.state |
러너 상태입니다. Attribute value mapping을 참고합니다. |
gitlab.cicd.runner.is_shared |
러너가 여러 프로젝트에서 공유되는지 여부입니다(확인 가능한 경우). |
gitlab.cicd.worker.tags |
job에 러너가 있는 경우 해당 job을 실행한 러너의 태그입니다. |
gitlab.cicd.worker.type |
러너 유형입니다(예: instance_type, project_type, 확인 가능한 경우). |
요청 태그 속성은 러너가 job을 가져가지 않은 경우에도 설정됩니다. 예를 들어 job이
대기 중에 취소되었거나 시간 초과된 경우입니다.
job이 어떤 태그 집합을 기다리는지 보려면 gitlab.cicd.pipeline.task.run.queued_duration을
gitlab.cicd.pipeline.task.tag_set와 gitlab.cicd.pipeline.task.untagged로 그룹화합니다.
bridge job에 의해 트리거된 하위 파이프라인의 경우, GitLab은 하위 파이프라인의 트레이스를 트리거한 job의 span에 연결합니다. 상위·하위 파이프라인이 하나로 이어진 트레이스로 표시됩니다.
Job 실패 증거#
job span에는 job이 실패했을 때 GitLab이 저장한 내용이 기록됩니다. 이 값은 증거이며 근본 원인이 아닙니다.
gitlab.cicd.pipeline.task.run.failure_reason(문자열)은 GitLab이 기록한 실패 사유입니다. 예를 들어script_failure,scheduler_failure,job_execution_timeout,runner_system_failure가 있습니다. 이 속성은 job이 실패한 경우에만 존재합니다. 실패했지만 기록된 사유가 없는 job의 값은unknown_failure입니다. 포괄적인 사유는 job이 어떻게 끝났는지를 설명할 뿐, 누가 또는 무엇이 원인인지를 설명하지 않습니다. 예를 들어script_failure는 포괄적인 기록 사유입니다. 이 값은 근본 원인을 확정하지 않으며, GitLab이 특정 스크립트 종료 코드를 기록했다는 것을 증명하지도 않습니다.gitlab.cicd.pipeline.task.run.exit_code(정수)는 GitLab이 실패한 job에 대해 저장한 종료 코드입니다. GitLab은 0에서 32767 사이의 값을 저장합니다. Windows 러너의 종료 코드처럼 더 큰 값은 32767로 저장됩니다. 음수 종료 코드는 0으로 저장됩니다. 러너가 종료 코드를 보고하지 않았다면 이 속성은 존재하지 않습니다. 스케줄링 실패나 서버 측 시간 초과처럼 스크립트를 실행하지 않고 실패한 job도 여기에 해당합니다. 속성이 없다고 해서 종료 코드가0이었다는 뜻은 아닙니다. GitLab은 실패하지 않은 job의 종료 코드는 내보내지 않습니다. 저장되는 값의 범위 때문에 이 값은 job이 자체 span에서 내보내는process.exit.code속성과 다를 수 있습니다.
시작하지 않고 끝난 job(예: 대기 중에 실패하거나 취소된 job)에는 시작 시각이 없습니다. 이 job의 span은 시작 시각과 종료 시각이 같으며, 이는 job이 끝난 시각입니다.
각 job 시도에는 고유한 job ID가 있으므로 고유한 span ID도 있습니다.
실패 증거를 특정 시도와 연결하려면 cicd.pipeline.task.run.id를 사용합니다.
GitLab은 파이프라인을 내보낼 때마다 같은 span ID로 모든 job span을 다시 전송합니다.
개수를 셀 때는 span ID로 중복을 제거합니다.
GitLab은 각 job의 최신 시도만 내보냅니다.
자동 재시도로 대체된 이전 시도에는 job span이 없습니다.
메트릭#
히스토리
- GitLab 19.5에서 지속 시간 메트릭 값이 초 단위로 수정되었습니다. 이전에는 지속 시간 게이지 값이 실제 지속 시간보다 1000배 작았고, 히스토그램 데이터 포인트가 잘못된 버킷에 배치되었습니다.
GitLab은 각 파이프라인에 대해 다음 메트릭을 내보냅니다:
| Metric | Type | Description |
|---|---|---|
pipeline.duration_seconds |
Gauge | 파이프라인 지속 시간(초)입니다. 파이프라인에 지속 시간이 있을 때만 방출됩니다. |
cicd.pipeline.run.duration |
Histogram | 파이프라인 실행 지속 시간(초)입니다. 파이프라인에 지속 시간이 있을 때만 방출됩니다. |
pipeline.status_total |
Counter | 파이프라인 상태 변경 횟수입니다. |
cicd.pipeline.run.count |
Counter | 파이프라인 실행 횟수입니다. |
pipeline.jobs_total |
Gauge | 파이프라인 내 job 개수입니다. |
cicd.pipeline.task.total |
Gauge | 파이프라인 내 job 개수입니다. |
job.duration_seconds |
Histogram | Stage별로 그룹화된 job 지속 시간(초)입니다. 파이프라인에 job 이 있을 때만 방출됩니다. |
cicd.pipeline.task.duration |
Histogram | Stage별로 그룹화된 job 지속 시간(초)입니다. 파이프라인에 job 이 있을 때만 방출됩니다. |
pipeline.queue_duration_seconds |
Gauge | 파이프라인이 대기열에 머문 시간(초)입니다. 파이프라인이 큐에 있었을 때만 방출됩니다. |
gitlab.cicd.pipeline.run.queued_duration |
Gauge | 파이프라인이 대기열에 머문 시간(초)입니다. 파이프라인이 큐에 있었을 때만 방출됩니다. |
cicd.pipeline.run.errors |
Counter | 파이프라인 오류 횟수입니다. 파이프라인 결과가 failure 일 때만 방출됩니다. |
메트릭 데이터 포인트는 pipeline.status, pipeline.ref, cicd.pipeline.name,
cicd.pipeline.result, gitlab.cicd.pipeline.trigger.type, vcs.ref.head.type 등의 속성을
포함합니다.
job.duration_seconds 및 cicd.pipeline.task.duration 히스토그램은 각 데이터 포인트마다
job.stage 속성을 포함합니다.
메트릭 데이터의 리소스에는 메트릭을 파이프라인의 트레이스와 연관 지을 수 있도록
gitlab.cicd.pipeline.trace_id 속성도 포함됩니다.
cicd.pipeline.run.errors 데이터 포인트는 error.type 속성을 포함합니다.
로그#
GitLab은 파이프라인에 대한 로그 레코드 1개와 각 job에 대한 로그 레코드 1개를 내보냅니다. 각 로그 레코드는 다음 필드를 포함합니다:
| Field | Description |
|---|---|
severityNumber and severityText |
파이프라인 또는 job 상태에서 매핑됩니다. Attribute value mapping을 참고합니다. |
body |
사람이 읽을 수 있는 요약입니다(예: Pipeline success: my-pipeline, Job failed: test-job (test)). |
log.level |
severityText와 같은 값입니다. |
log.source |
pipeline 또는 job 중 하나입니다. |
| Remaining attributes | 트레이스 span과 동일한 속성군입니다: 파이프라인 또는 job 식별 정보, cicd.* 및 vcs.* semantic convention 속성, 그리고 가능한 경우 러너·환경·아티팩트 속성입니다. |
속성 값 매핑#
GitLab은 내부 상태 값을 OpenTelemetry CI/CD semantic convention에서 정의한 enum 값으로 매핑합니다.
파이프라인 및 job 결과(cicd.pipeline.result, cicd.pipeline.task.run.result):
| GitLab status | OpenTelemetry result |
|---|---|
success |
success |
failed |
failure |
canceled |
cancellation |
skipped |
skip |
파이프라인 및 job 실행 상태(cicd.pipeline.run.state, cicd.pipeline.task.run.state):
| GitLab status | OpenTelemetry run state |
|---|---|
pending |
pending |
waiting_for_resource |
pending |
preparing |
pending |
running |
executing |
러너 상태(cicd.worker.state):
Runner active attribute |
OpenTelemetry worker state |
|---|---|
true |
available |
false |
offline |
동작 방식#
변수가 설정되면 GitLab은 자동으로 다음을 수행합니다:
- 각 파이프라인이 완료된 후 파이프라인 실행 데이터를 수집합니다
- 설정에 따라 데이터를 OpenTelemetry 형식으로 변환합니다
- 텔레메트리 데이터를 GitLab Observability 인스턴스로 내보냅니다
- observability 대시보드에서 데이터를 사용할 수 있도록 합니다
.gitlab-ci.yml 파일을 변경할 필요가 없습니다. 계측은 백그라운드에서 자동으로 이루어집니다.
그룹 계층 구조의 텔레메트리 라우팅#
파이프라인이 완료되면 GitLab은 해당 텔레메트리를 프로젝트의 계층 구조에서 Observability가 활성화된 가장 가까운 그룹으로 전송합니다. GitLab은 프로젝트가 속한 그룹에서 시작해 상위 그룹을 차례로 확인합니다. Observability가 활성화된 첫 번째 그룹이 텔레메트리를 받습니다.
그 결과는 다음과 같습니다.
- Observability가 활성화된 하위 그룹의 프로젝트는 상위 그룹이 아니라 하위 그룹으로 텔레메트리를 전송합니다.
- Observability가 활성화되지 않은 하위 그룹의 프로젝트는 Observability가 활성화된 가장 가까운 상위 그룹으로 텔레메트리를 전송합니다.
- 계층 구조의 어떤 그룹에도 Observability가 활성화되어 있지 않으면 파이프라인은 내보내지지 않습니다.
각 파이프라인은 하나의 그룹으로만 텔레메트리를 전송합니다. 자체 Observability가 활성화된 하위 그룹의 텔레메트리 사본은 상위 그룹이 받지 않습니다.
예를 들어 다음 계층 구조에서는 my-org와 my-org/backend 모두 Observability가 활성화되어 있습니다.
소스 코드 보기
flowchart TD
accTitle: CI/CD telemetry routing in a group hierarchy
accDescr: Each project sends pipeline telemetry to the nearest group above it that has Observability enabled.
org["Group: my-org<br>Observability enabled"]
frontend["Subgroup: my-org/frontend<br>Observability not enabled"]
backend["Subgroup: my-org/backend<br>Observability enabled"]
services["Subgroup: my-org/backend/services<br>Observability not enabled"]
web("Project: web-app")
api("Project: api")
billing("Project: billing")
org --> frontend
org --> backend
backend --> services
frontend --> web
backend --> api
services --> billing
web -. telemetry .-> org
api -. telemetry .-> backend
billing -. telemetry .-> backend
classDef enabled stroke-width:4px
classDef notEnabled stroke-width:1px,stroke-dasharray: 5 5
class org,backend enabled
class frontend,services notEnabled</code></pre></details></div>
다이어그램에서 Observability가 활성화된 그룹은 굵은 실선 테두리로 표시됩니다.
Observability가 활성화되지 않은 그룹은 점선 테두리로 표시됩니다.
이 예시에서는 다음과 같이 동작합니다.
web-app은 my-org/frontend에 Observability가 활성화되어 있지 않으므로 my-org로 텔레메트리를 전송합니다.
api는 프로젝트가 속한 그룹인 my-org/backend로 텔레메트리를 전송합니다.
billing은 Observability가 활성화된 가장 가까운 상위 그룹인 my-org/backend로 텔레메트리를 전송합니다.
그룹 계층 구조의 CI/CD 변수#
라우팅은 텔레메트리가 어디로 갈지를 결정합니다. GITLAB_OBSERVABILITY_EXPORT 변수는
파이프라인을 내보낼지 여부와 어떤 데이터 유형을 전송할지를 결정합니다.
GitLab은 이 변수를 표준
CI/CD 변수 우선순위에 따라 확인하므로,
프로젝트나 하위 그룹이 상위 그룹에 설정된 값을 재정의할 수 있습니다.
GitLab.com에서는 그룹에 Observability를 활성화하면 GitLab이 해당 그룹에
GITLAB_OBSERVABILITY_EXPORT 변수를 값 traces,metrics,logs로 추가합니다.
그룹과 그 하위 그룹의 프로젝트는 이 변수를 상속합니다.
GitLab Self-Managed에서는 GitLab이 변수를 추가하지 않습니다.
파이프라인 계측 활성화에 설명된 대로 그룹이나 프로젝트에 직접 추가합니다.
GITLAB_OBSERVABILITY_TOKEN 변수도 상속됩니다.
하위 그룹에 Observability가 활성화되어 있고 해당 인스턴스에 인증이 필요하다면
하위 그룹에 GITLAB_OBSERVABILITY_TOKEN을 설정합니다.
그렇지 않으면 하위 그룹의 프로젝트가 상위 그룹의 토큰을 하위 그룹의 인스턴스로 전송하고,
하위 그룹의 인스턴스는 해당 텔레메트리를 거부합니다.
기존 파이프라인 내보내기#
그룹에 Observability를 활성화하고 약 1시간 후에 GitLab은 그룹에 속한 프로젝트의 최근 10일간 완료된
파이프라인을 내보냅니다.
이미 Observability가 활성화된 하위 그룹의 프로젝트는 하위 그룹으로 텔레메트리를 전송하므로
이 내보내기에서 제외됩니다.
파이프라인 텔레메트리 보기#
계측이 활성화된 상태로 파이프라인을 실행한 후:
- 상단 바에서 Search or go to를 선택하고 그룹 또는 프로젝트를 찾습니다.
- 왼쪽 사이드바에서 Observe > Services를 선택합니다.
- 파이프라인 실행의 트레이스, 메트릭, 로그를 보려면
gitlab-ci 서비스를 선택합니다.
GitLab Observability Templates
의 CI/CD 대시보드 템플릿은 파이프라인 성능 분석을 위한 사전 구성된 시각화를 제공합니다.
관련 주제#