---

GitLab Observability에 텔레메트리 데이터 전송#

  - 
  Tier: Free, Premium, Ultimate

- Offering: GitLab.com, GitLab Self-Managed#

  Status: Experiment

Observability를 구성한 후 GitLab에 데이터 전송을 시작할 수 있습니다.

시작하려면 CI/CD 파이프라인 데이터를 확인하거나, 테스트 데이터를 전송하거나, 템플릿을 사용하세요.

Observability 데이터 보기#

GitLab Observability를 구성한 후:

• 상단 바에서 검색 또는 이동을 선택하고 그룹을 찾으세요.

• 왼쪽 사이드바에서 Observability > Services를 선택하세요.

• 세부 정보를 볼 서비스를 선택하세요.

[

](/19.1/operations/img/gitLab_o11y_gitlab_com_dashboard_v18_1.png)

애플리케이션 계측#

애플리케이션에 OpenTelemetry 계측을 추가하려면:

• 사용하는 언어의 OpenTelemetry SDK를 추가하세요.

• OTLP 익스포터가 GitLab Observability 인스턴스를 가리키도록 구성하세요.

• 권장 리소스 속성을 구성하세요.

• 작업과 메타데이터를 추적하는 span 및 속성을 추가하세요.

언어별 지침은 OpenTelemetry 문서를 참조하세요.

권장 리소스 속성#

이 리소스 속성으로 OpenTelemetry SDK를 구성하면 텔레메트리 데이터를 GitLab 프로젝트 및 코드와 연결할 수 있습니다. 이를 통해 트레이스를 커밋에 연관 짓거나 예외 발생 시 이슈를 자동으로 생성하는 기능을 활성화할 수 있습니다.

service.version과 deployment.environment.name은 OpenTelemetry 시맨틱 컨벤션입니다. gitlab.* 속성은 GitLab 특정 컨텍스트를 위한 벤더 네임스페이스를 사용합니다.

네 가지 변수 모두 GitLab CI/CD에 사전 정의되어 있으며, 애플리케이션이 파이프라인에서 실행될 때 추가 구성이 필요하지 않습니다. 로컬 개발 환경에서는 이 환경 변수를 수동으로 설정하거나 빈 기본값을 그대로 사용하세요.

다음 Ruby 예시는 이러한 속성을 구성하는 방법을 보여줍니다:

OpenTelemetry::SDK.configure do |c|
  c.resource = OpenTelemetry::SDK::Resources::Resource.create(
    'gitlab.project.id'           => ENV.fetch('CI_PROJECT_ID', ''),
    'gitlab.project.name'         => ENV.fetch('CI_PROJECT_NAME', ''),
    'service.version'             => ENV.fetch('CI_COMMIT_SHA', ''),
    'deployment.environment.name' => ENV.fetch('CI_ENVIRONMENT_NAME', '')
  )

  c.use_all
end

다른 언어의 경우, 해당 언어의 OpenTelemetry SDK를 사용하여 동일한 리소스 속성을 설정하세요. 속성 이름과 환경 변수는 모든 언어에서 동일합니다.

테스트 데이터 전송#

OpenTelemetry SDK를 사용하여 샘플 텔레메트리 데이터를 전송함으로써 GitLab Observability 설치를 테스트할 수 있습니다. 이 예시는 Ruby를 사용하지만, OpenTelemetry에는 다양한 언어용 SDK가 있습니다.

사전 요구사항#

로컬 머신에 Ruby가 설치되어 있어야 합니다.

필요한 gem:

gem install opentelemetry-sdk opentelemetry-exporter-otlp

기본 테스트 스크립트 생성#

다음 내용으로 test_o11y.rb 파일을 생성하세요:

require 'opentelemetry/sdk'
require 'opentelemetry/exporter/otlp'

OpenTelemetry::SDK.configure do |c|
  # Define service information
  resource = OpenTelemetry::SDK::Resources::Resource.create({
    'service.name' => 'test-service',
    'service.version' => '1.0.0',
    'deployment.environment.name' => 'production',
    'gitlab.project.id' => ENV.fetch('CI_PROJECT_ID', ''),
    'gitlab.project.name' => ENV.fetch('CI_PROJECT_NAME', '')
  })
  c.resource = resource

  # Configure OTLP exporter to send to GitLab Observability
  c.add_span_processor(
    OpenTelemetry::SDK::Trace::Export::BatchSpanProcessor.new(
      OpenTelemetry::Exporter::OTLP::Exporter.new(
        endpoint: 'http://[your-o11y-instance-ip]:4318/v1/traces'
      )
    )
  )
end

# Get tracer and create spans
tracer = OpenTelemetry.tracer_provider.tracer('basic-demo')

# Create parent span
tracer.in_span('parent-operation') do |parent|
  parent.set_attribute('custom.attribute', 'test-value')
  puts "Created parent span: #{parent.context.hex_span_id}"

  # Create child span
  tracer.in_span('child-operation') do |child|
    child.set_attribute('custom.child', 'child-value')
    puts "Created child span: #{child.context.hex_span_id}"
    sleep(1)
  end
end

puts "Waiting for export..."
sleep(5)
puts "Done!"

[your-o11y-instance-ip]를 GitLab Observability 인스턴스의 IP 주소 또는 호스트명으로 교체하세요.

테스트 실행#

스크립트를 실행하세요:

ruby test_o11y.rb

Observability > Services로 이동하세요. test-service 서비스를 선택하면 트레이스와 span을 확인할 수 있습니다.

GitLab Observability 템플릿#

GitLab은 Observability를 빠르게 시작할 수 있도록 사전 구축된 대시보드 템플릿을 제공합니다. 이 템플릿은 GitLab Observability Templates에서 확인할 수 있습니다.

사용 가능한 템플릿#

표준 OpenTelemetry 대시보드: 표준 OpenTelemetry 라이브러리로 애플리케이션을 계측한 경우, 다음 플러그 앤 플레이 대시보드 템플릿을 사용할 수 있습니다:

• 애플리케이션 성능 모니터링 대시보드

• 서비스 의존성 시각화

• 오류율 및 레이턴시 추적

GitLab 전용 대시보드: GitLab OpenTelemetry 데이터를 GitLab Observability 인스턴스에 전송할 때, 다음 대시보드를 사용하면 즉시 인사이트를 얻을 수 있습니다:

• GitLab 애플리케이션 성능 메트릭

• GitLab 서비스 상태 모니터링

• GitLab 특정 트레이스 분석

CI/CD Observability: 이 리포지터리에는 OpenTelemetry 계측이 포함된 GitLab CI/CD 파이프라인 예시가 포함되어 있으며, GitLab Observability CI/CD 대시보드 템플릿 JSON 파일과 함께 작동합니다. 이를 통해 CI/CD 파이프라인 성능을 모니터링하고 병목 지점을 파악할 수 있습니다.

템플릿 사용#

• 리포지터리에서 템플릿을 클론하거나 다운로드하세요.

• 예시 애플리케이션 대시보드의 서비스 이름을 실제 서비스 이름에 맞게 업데이트하세요.

• JSON 파일을 GitLab Observability 인스턴스에 가져오세요.

• 애플리케이션 계측 섹션에 설명된 대로 표준 OpenTelemetry 라이브러리를 사용하여 애플리케이션이 텔레메트리 데이터를 전송하도록 구성하세요.

• 이제 GitLab Observability에서 애플리케이션의 텔레메트리 데이터가 포함된 대시보드를 사용할 수 있습니다.

관련 항목#

• Observability 트러블슈팅