InfoGrab DocsInfoGrab Docs

GitLab Self-Managed에서 Observability 설정

요약

Observability 데이터는 GitLab.com 인스턴스 외부의 별도 애플리케이션에서 수집됩니다. GitLab Self-Managed의 경우, 데이터 저장 위치를 직접 제어할 수 있습니다. GitLab Self-Managed 인스턴스에서 Observability를 설정하려면 다음 단계를 수행합니다.

Observability 데이터는 GitLab.com 인스턴스 외부의 별도 애플리케이션에서 수집됩니다. GitLab 인스턴스에 문제가 발생해도 Observability 데이터 수집이나 조회에 영향을 미치지 않으며, 그 반대도 마찬가지입니다.

GitLab Self-Managed의 경우, 데이터 저장 위치를 직접 제어할 수 있습니다.

워크플로#

GitLab Self-Managed 인스턴스에서 Observability를 설정하려면 다음 단계를 수행합니다.

  1. 사전 요구 사항을 충족하는지 확인합니다.
  2. 서버와 스토리지를 프로비저닝합니다.
  3. Docker를 구성하고 컨테이너에 Observability를 설치합니다.
  4. 네트워크 접근을 구성합니다.
  5. 관리자 영역에서 그룹의 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의 경우:

  1. 최소 2 vCPU 및 8 GB RAM을 갖춘 EC2 인스턴스를 시작합니다.
  2. 최소 100 GB의 EBS 볼륨을 추가합니다.
  3. 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를 실행하기 전에 다음 단계를 완료합니다.

  1. docker-compose.yml 파일을 엽니다.
  2. 다음 항목을 주석 처리합니다.
    • clickhouse 및 zookeeper 서비스.
    • x-clickhouse-defaults 및 x-clickhouse-depend 섹션.
  3. 다음 파일에서 clickhouse:9000의 모든 항목을 관련 ClickHouse 엔드포인트 및 TCP 포트(예: my-clickhouse.example.com:9000)로 교체합니다. ClickHouse 인스턴스에 인증이 필요한 경우, 자격 증명을 포함하도록 연결 문자열도 업데이트해야 할 수 있습니다.
    • docker-compose.yml
    • otel-collector-config.yaml
    • prometheus-config.yml

GitLab Observability의 네트워크 접근 구성#

텔레메트리 데이터를 올바르게 수신하려면 GitLab Observability 인스턴스의 보안 그룹에서 특정 포트를 열어야 합니다.

  1. AWS Console > EC2 > Security Groups로 이동합니다.
  2. GitLab Observability 인스턴스에 연결된 보안 그룹을 선택합니다.
  3. Edit inbound rules를 선택합니다.
  4. 다음 규칙을 추가합니다.
    • 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용 - 선택 사항)
  5. 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을 선택합니다.
  1. 오른쪽 상단에서 Admin을 선택합니다.
  2. 왼쪽 사이드바에서 Observability를 선택합니다.
  3. New O11y service setting을 선택합니다.
  4. 필드를 입력합니다.
    • 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.
  5. 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 콘솔을 통해 설정을 직접 구성합니다.

  1. Rails 콘솔에 접근합니다.

    docker exec -it gitlab gitlab-rails console
    
  2. 개인 네임스페이스의 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를 저장합니다.

다음 단계#

GitLab Self-Managed에서 Observability 설정

GitLab v19.6
Tier: Free, Premium, Ultimate
Offering: 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를 설정하려면 다음 단계를 수행합니다.

  1. 사전 요구 사항을 충족하는지 확인합니다.
  2. 서버와 스토리지를 프로비저닝합니다.
  3. Docker를 구성하고 컨테이너에 Observability를 설치합니다.
  4. 네트워크 접근을 구성합니다.
  5. 관리자 영역에서 그룹의 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의 경우:

  1. 최소 2 vCPU 및 8 GB RAM을 갖춘 EC2 인스턴스를 시작합니다.
  2. 최소 100 GB의 EBS 볼륨을 추가합니다.
  3. 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를 실행하기 전에 다음 단계를 완료합니다.

  1. docker-compose.yml 파일을 엽니다.
  2. 다음 항목을 주석 처리합니다.
    • clickhouse 및 zookeeper 서비스.
    • x-clickhouse-defaults 및 x-clickhouse-depend 섹션.
  3. 다음 파일에서 clickhouse:9000의 모든 항목을 관련 ClickHouse 엔드포인트 및 TCP 포트(예: my-clickhouse.example.com:9000)로 교체합니다. ClickHouse 인스턴스에 인증이 필요한 경우, 자격 증명을 포함하도록 연결 문자열도 업데이트해야 할 수 있습니다.
    • docker-compose.yml
    • otel-collector-config.yaml
    • prometheus-config.yml

GitLab Observability의 네트워크 접근 구성#

텔레메트리 데이터를 올바르게 수신하려면 GitLab Observability 인스턴스의 보안 그룹에서 특정 포트를 열어야 합니다.

  1. AWS Console > EC2 > Security Groups로 이동합니다.
  2. GitLab Observability 인스턴스에 연결된 보안 그룹을 선택합니다.
  3. Edit inbound rules를 선택합니다.
  4. 다음 규칙을 추가합니다.
    • 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용 - 선택 사항)
  5. 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을 선택합니다.
  1. 오른쪽 상단에서 Admin을 선택합니다.
  2. 왼쪽 사이드바에서 Observability를 선택합니다.
  3. New O11y service setting을 선택합니다.
  4. 필드를 입력합니다.
    • 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.
  5. 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 콘솔을 통해 설정을 직접 구성합니다.

  1. Rails 콘솔에 접근합니다.

    docker exec -it gitlab gitlab-rails console
    
  2. 개인 네임스페이스의 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를 저장합니다.

다음 단계#