GitLab Self-Managed에서 Observability 설정
GitLab v19.6Offering: GitLab Self-Managed
요약
Observability 데이터는 GitLab.com 인스턴스 외부의 별도 애플리케이션에서 수집됩니다. GitLab Self-Managed의 경우, 데이터 저장 위치를 직접 제어할 수 있습니다. GitLab Self-Managed 인스턴스에서 Observability를 설정하려면 다음 단계를 수행합니다.
Observability 데이터는 GitLab.com 인스턴스 외부의 별도 애플리케이션에서 수집됩니다. GitLab 인스턴스에 문제가 발생해도 Observability 데이터 수집이나 조회에 영향을 미치지 않으며, 그 반대도 마찬가지입니다.
GitLab Self-Managed의 경우, 데이터 저장 위치를 직접 제어할 수 있습니다.
워크플로#
GitLab Self-Managed 인스턴스에서 Observability를 설정하려면 다음 단계를 수행합니다.
- 사전 요구 사항을 충족하는지 확인합니다.
- 서버와 스토리지를 프로비저닝합니다.
- Docker를 구성하고 컨테이너에 Observability를 설치합니다.
- 네트워크 접근을 구성합니다.
- 관리자 영역에서 그룹의 URL을 구성하거나, Rails 콘솔을 사용해 개인 네임스페이스의 URL을 구성합니다.
사전 요구 사항#
- 다음 사양을 갖춘 EC2 인스턴스 또는 유사한 가상 머신이 필요합니다.
- 최소 사양:
t3.large(2 vCPU, 8 GB RAM). - 권장 사양: 프로덕션 사용을 위해
t3.xlarge(4 vCPU, 16 GB RAM). - 최소 100 GB 스토리지 공간.
- 최소 사양:
- Docker 및 Docker Compose가 설치되어 있어야 합니다.
- GitLab 버전이 18.1 이상이어야 합니다.
- GitLab 인스턴스가 Observability 인스턴스에 연결되어 있어야 합니다.
서버 및 스토리지 프로비저닝#
AWS EC2의 경우:
- 최소 2 vCPU 및 8 GB RAM을 갖춘 EC2 인스턴스를 시작합니다.
- 최소 100 GB의 EBS 볼륨을 추가합니다.
- SSH를 사용하여 인스턴스에 연결합니다.
스토리지 볼륨 마운트#
sudo mkdir -p /mnt/data
sudo mount /dev/xvdbb /mnt/data # Replace xvdbb with your volume name
sudo chown -R $(whoami):$(whoami) /mnt/data
영구 마운트를 위해 /etc/fstab에 추가합니다.
echo '/dev/xvdbb /mnt/data ext4 defaults,nofail 0 2' | sudo tee -a /etc/fstab
Docker 설치#
Ubuntu/Debian의 경우:
sudo apt update
sudo apt install -y docker.io docker-compose
sudo systemctl enable docker
sudo systemctl start docker
sudo usermod -aG docker $(whoami)
Amazon Linux의 경우:
sudo dnf update
sudo dnf install -y docker
sudo systemctl enable docker
sudo systemctl start docker
sudo usermod -aG docker $(whoami)
로그아웃 후 다시 로그인하거나 다음을 실행합니다.
newgrp docker
마운트된 볼륨을 사용하도록 Docker 구성#
sudo mkdir -p /mnt/data/docker
sudo bash -c 'cat > /etc/docker/daemon.json << EOF
{
"data-root": "/mnt/data/docker"
}
EOF'
sudo systemctl restart docker
다음 명령으로 확인합니다.
docker info | grep "Docker Root Dir"
GitLab Observability 설치#
cd /mnt/data
git clone -b main https://gitlab.com/gitlab-org/embody-team/experimental-observability/gitlab_o11y.git
cd gitlab_o11y/deploy/docker
docker-compose up -d
타임아웃 오류가 발생하는 경우 다음을 사용합니다.
COMPOSE_HTTP_TIMEOUT=300 docker-compose up -d
선택 사항: 외부 ClickHouse 데이터베이스 사용#
원하는 경우 자체 ClickHouse 데이터베이스를 사용할 수 있습니다.
사전 요구 사항:
- 외부 ClickHouse 인스턴스에 접근할 수 있으며, 필요한 인증 자격 증명으로 올바르게 구성되어 있는지 확인합니다.
docker-compose up -d를 실행하기 전에 다음 단계를 완료합니다.
docker-compose.yml파일을 엽니다.- 다음 항목을 주석 처리합니다.
clickhouse및zookeeper서비스.x-clickhouse-defaults및x-clickhouse-depend섹션.
- 다음 파일에서
clickhouse:9000의 모든 항목을 관련 ClickHouse 엔드포인트 및 TCP 포트(예:my-clickhouse.example.com:9000)로 교체합니다. ClickHouse 인스턴스에 인증이 필요한 경우, 자격 증명을 포함하도록 연결 문자열도 업데이트해야 할 수 있습니다.docker-compose.ymlotel-collector-config.yamlprometheus-config.yml
GitLab Observability의 네트워크 접근 구성#
텔레메트리 데이터를 올바르게 수신하려면 GitLab Observability 인스턴스의 보안 그룹에서 특정 포트를 열어야 합니다.
- AWS Console > EC2 > Security Groups로 이동합니다.
- GitLab Observability 인스턴스에 연결된 보안 그룹을 선택합니다.
- Edit inbound rules를 선택합니다.
- 다음 규칙을 추가합니다.
- Type: Custom TCP, Port: 8080, Source: 사용자 IP 또는 0.0.0.0/0 (UI 접근용)
- Type: Custom TCP, Port: 4317, Source: 사용자 IP 또는 0.0.0.0/0 (OTLP gRPC용)
- Type: Custom TCP, Port: 4318, Source: 사용자 IP 또는 0.0.0.0/0 (OTLP HTTP용)
- Type: Custom TCP, Port: 9411, Source: 사용자 IP 또는 0.0.0.0/0 (Zipkin용 - 선택 사항)
- Type: Custom TCP, Port: 14268, Source: 사용자 IP 또는 0.0.0.0/0 (Jaeger HTTP용 - 선택 사항)
- Type: Custom TCP, Port: 14250, Source: 사용자 IP 또는 0.0.0.0/0 (Jaeger gRPC용 - 선택 사항)
- Save rules를 선택합니다.
이제 다음 주소에서 GitLab Observability UI에 접근할 수 있습니다.
http://[your-instance-ip]:8080
TLS 구성#
Docker Compose 스택은 일반 HTTP로 서비스합니다. GitLab은 서비스 URL과 OpenTelemetry 엔드포인트 모두에 HTTPS를 요구하므로, 계속하기 전에 TLS 인증서가 있는 리버스 프록시를 스택 앞에 둡니다.
다음 두 업스트림에 대해 TLS를 종료합니다.
| 업스트림 | 컨테이너 포트 | 용도 |
|---|---|---|
| GitLab Observability UI 및 API | 8080 |
GitLab이 연결하는 서비스 URL |
| OpenTelemetry HTTP 수신기 | 4318 |
내보낸 텔레메트리를 수신하는 엔드포인트 |
OTel URL 재정의에 포트가 명시되어 있지 않으면 GitLab은 포트 14318로 OpenTelemetry 수신기에
연결합니다.
https://otel.example.com처럼 포트가 없는 URL은 https 스킴이 443을 의미하더라도
포트 14318로 해석됩니다.
443을 포함해 다른 포트를 사용하려면 재정의에 포트를 추가합니다. 예:
https://otel.example.com:443.
http:// URL은 오류 없이 저장되지만, 나중에 사용자가 Observability를 열거나
파이프라인이 텔레메트리를 내보낼 때 실패합니다.
그룹 또는 개인 네임스페이스의 URL 구성#
관리자 영역에서 그룹의 GitLab Observability URL을 구성하거나, Rails 콘솔을 사용해 개인 네임스페이스의 URL을 구성합니다.
사전 요구 사항:
- GitLab 인스턴스에 대한 관리자 액세스 권한이 있어야 합니다.
- GitLab Observability 인스턴스의 TLS 엔드포인트가 있어야 합니다.
- 그룹의 네임스페이스 ID를 알고 있어야 합니다. ID를 찾으려면 그룹으로 이동해 Settings > General을 선택합니다.
- 오른쪽 상단에서 Admin을 선택합니다.
- 왼쪽 사이드바에서 Observability를 선택합니다.
- New O11y service setting을 선택합니다.
- 필드를 입력합니다.
- Namespace ID: 구성할 그룹의 ID.
- Service URL: GitLab Observability 인스턴스의 HTTPS URL. 예:
https://o11y.example.com. - User email 및 Password: GitLab Observability 인스턴스에 인증하는 데 사용하는 자격 증명.
- Encryption key: 32자 이상의 보안 문자열.
- OTel URL override: 인스턴스의 HTTPS OpenTelemetry 엔드포인트. 예:
https://o11y.example.com:14318.
- Save changes를 선택합니다.
OTel URL override를 설정합니다. GitLab Self-Managed에서 기본값은 GitLab.com 서비스 이름에서 파생되므로 사용자의 인스턴스를 가리키지 않습니다. 이 필드를 비워 두면 텔레메트리가 존재하지 않는 엔드포인트로 전송되며, 오류는 표시되지 않습니다.
MCP URL override는 비워 둡니다. Model Context Protocol 서버는 GitLab.com에서만 사용할 수 있습니다. 자세한 내용은 Observability MCP 서버를 참고합니다.
저장하면 GitLab이 New O11y service setting 페이지로 돌아가므로 다른 그룹의 구성을 추가할 수 있습니다. 기존 구성을 보거나 변경하려면 왼쪽 사이드바에서 Observability를 선택한 다음, 해당 네임스페이스의 Edit를 선택합니다.
O11y service settings 페이지의 Service name 열에는 URL 자체가 아니라 서비스 URL에서 파생된 값이 표시됩니다.
GitLab Self-Managed에는 개인 네임스페이스에 대해 Observability를 활성화하는 UI 경로가 없습니다. Rails 콘솔을 통해 설정을 직접 구성합니다.
-
Rails 콘솔에 접근합니다.
docker exec -it gitlab gitlab-rails console -
개인 네임스페이스의 Observability 설정을 구성합니다.
namespace = User.find_by_username('your-username').namespace Observability::GroupO11ySetting.create!( group_id: namespace.id, o11y_service_url: 'your-o11y-instance-url', o11y_service_user_email: 'your-email@example.com', o11y_service_password: 'your-secure-password', o11y_service_post_message_encryption_key: 'your-super-secret-encryption-key-here-32-chars-minimum', o11y_otel_url: 'your-otel-endpoint' )다음 항목을 교체합니다.
your-username을 개인 네임스페이스를 소유한 사용자 이름으로 교체합니다.your-o11y-instance-url을 GitLab Observability 인스턴스의 HTTPS URL로 교체합니다(예:https://o11y.example.com).- 이메일과 비밀번호를 원하는 자격 증명으로 교체합니다.
- 암호화 키를 32자 이상의 보안 문자열로 교체합니다.
your-otel-endpoint를 인스턴스의 HTTPS OpenTelemetry 엔드포인트로 교체합니다(예:https://o11y.example.com:14318).
o11y_otel_url을 설정합니다.
이 값을 설정하지 않으면 기본값이 GitLab.com 서비스 이름에서 파생된 엔드포인트로 지정되며,
이는 사용자의 인스턴스를 가리키지 않습니다.
해당 엔드포인트로 전송된 텔레메트리는 유실되며, 오류는 표시되지 않습니다.
group_id 열은 그룹과 개인 네임스페이스 모두에 대해 네임스페이스 ID를 저장합니다.