활성화하면 GitLab Observability가 CI/CD 파이프라인을 자동으로 계측하여, 코드 변경 없이도 파이프라인 성능·job 지속 시간·실행 흐름에 대한 가시성을 제공합니다.

• 파이프라인을 지연시키는 job을 파악할 수 있는 가시성을 제공합니다.
• 파이프라인 성능이 시간에 따라 어떻게 변화하는지 보여줍니다.
• 배포 프로세스의 병목 구간을 나타냅니다.

파이프라인 계측 활성화#

자동 파이프라인 계측을 활성화하려면 프로젝트 또는 그룹에 GITLAB_OBSERVABILITY_EXPORT CI/CD 변수를 추가합니다:

1. 상단 바에서 Search or go to를 선택하고 프로젝트 또는 그룹을 찾습니다.
2. 왼쪽 사이드바에서 Settings > CI/CD를 선택합니다.
3. Variables를 펼칩니다.
4. Add variable을 선택합니다.
5. 다음과 같이 변수를 구성합니다:
   • Key: GITLAB_OBSERVABILITY_EXPORT
   • Value: traces, metrics, logs 중 하나 이상(여러 개를 지정할 때는 쉼표로 구분)
   • Type: Variable
   • Environment scope: All(또는 특정 환경)
6. 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에서 토큰 생성#

수집 토큰(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에 토큰 설정#

계측된 파이프라인을 실행하는 프로젝트 또는 그룹에 토큰을 추가합니다:

1. 상단 바에서 Search or go to를 선택하고 프로젝트 또는 그룹을 찾습니다.
2. 왼쪽 사이드바에서 Settings > CI/CD를 선택합니다.
3. Variables를 펼칩니다.
4. Add variable을 선택합니다.
5. 다음과 같이 변수를 구성합니다:
   • Key: GITLAB_OBSERVABILITY_TOKEN
   • Value: GitLab Observability에서 생성한 토큰
   • Type: Variable
   • Flags: job 로그에 토큰이 노출되지 않도록 Mask variable을 선택합니다.
6. 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 엔드포인트는 유효한 토큰이 없는 텔레메트리를 모두 거부합니다.

토큰 순환#

인스턴스는 동시에 두 개 이상의 유효한 토큰을 허용하므로, 텔레메트리 손실 없이 토큰을 교체하려면 토큰을 순환시킵니다:

1. GitLab Observability에서 토큰 생성에 설명된 대로 새 토큰을 생성합니다.

2. GITLAB_OBSERVABILITY_TOKEN 변수(및 다른 모든 클라이언트)를 새 토큰 값으로 업데이트합니다. 이전 토큰과 새 토큰이 모두 존재하는 동안에는 둘 다 유효하므로 텔레메트리 내보내기에 공백이 생기지 않습니다.

3. 이전 토큰을 폐기합니다. 토큰 목록을 조회해 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.*) 양쪽에서 함께 방출됩니다.

트레이스#

각 파이프라인은 파이프라인 span 하나와, 파이프라인 내 각 job 또는 bridge에 대한 job span 하나를 포함하는 단일 리소스 span으로 내보내집니다.

리소스는 다음 속성을 포함합니다:

파이프라인 span은 다음 속성을 포함합니다:

job span은 각 job 또는 bridge에 대해 다음 속성을 포함합니다:

bridge job에 의해 트리거된 하위 파이프라인의 경우, GitLab은 하위 파이프라인의 트레이스를 트리거한 job의 span에 연결합니다. 상위·하위 파이프라인이 하나로 이어진 트레이스로 표시됩니다.

메트릭#

GitLab은 각 파이프라인에 대해 다음 메트릭을 내보냅니다:

메트릭 데이터 포인트는 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개를 내보냅니다. 각 로그 레코드는 다음 필드를 포함합니다:

속성 값 매핑#

GitLab은 내부 상태 값을 OpenTelemetry CI/CD semantic convention에서 정의한 enum 값으로 매핑합니다.

파이프라인 및 job 결과(cicd.pipeline.result, cicd.pipeline.task.run.result):

파이프라인 및 job 실행 상태(cicd.pipeline.run.state, cicd.pipeline.task.run.state):

러너 상태(cicd.worker.state):

동작 방식#

변수가 설정되면 GitLab은 자동으로 다음을 수행합니다:

1. 각 파이프라인이 완료된 후 파이프라인 실행 데이터를 수집합니다
2. 설정에 따라 데이터를 OpenTelemetry 형식으로 변환합니다
3. 텔레메트리 데이터를 GitLab Observability 인스턴스로 내보냅니다
4. observability 대시보드에서 데이터를 사용할 수 있도록 합니다

.gitlab-ci.yml 파일을 변경할 필요가 없습니다. 계측은 백그라운드에서 자동으로 이루어집니다.

파이프라인 텔레메트리 보기#

계측이 활성화된 상태로 파이프라인을 실행한 후:

1. 상단 바에서 Search or go to를 선택하고 그룹 또는 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 Observe > Services를 선택합니다.
3. 파이프라인 실행의 트레이스, 메트릭, 로그를 보려면 gitlab-ci 서비스를 선택합니다.

GitLab Observability Templates 의 CI/CD 대시보드 템플릿은 파이프라인 성능 분석을 위한 사전 구성된 시각화를 제공합니다.

관련 주제#

• Observability 문제 해결