히스토리

• GitLab 15.5에서 실험으로 도입됨.

• GitLab 17.9에서 인라인 시각화 구성이 도입됨.

• GitLab 18.3에서 패널 툴팁 구성이 도입됨.

• GitLab 19.1에서 패널 뷰 구성이 도입됨.

Analytics 대시보드는 구성 기반의 대시보드 구조를 제공하며, GitLab 또는 사용자가 생성한 대시보드 구성을 렌더링하고 수정하는 데 사용됩니다.

Analytics 대시보드는 Premium 및 Ultimate 구독을 대상으로 합니다.

개요#

Analytics 대시보드는 다음과 같은 논리적 구성 요소로 나눌 수 있습니다:

• 대시보드(Dashboard): 모든 시각화를 구성하고 표시하는 컨테이너

• 패널(Panel): 시각화를 호스팅하는 개별 섹션

• 시각화(Visualization): 데이터 표시 템플릿(차트, 테이블 등)

• 데이터 소스(Data source): 기반 데이터에 대한 연결

대시보드(Dashboard)#

대시보드는 데이터 소스, 패널, 시각화의 집합을 단일 페이지로 결합하여 데이터를 시각적으로 나타냅니다.

대시보드의 각 패널은 관련 데이터 소스를 쿼리하고, 결과 데이터를 지정된 시각화 방식으로 표시합니다. 시각화는 데이터를 표시하는 방식의 템플릿 역할을 하며, 여러 패널에서 재사용할 수 있습니다.

일반적인 대시보드 구조는 다음과 같습니다:

dashboard
├── panelA
│  └── visualizationX
│      └── datasource1
├── panelB
│  └── visualizationY
│      └── datasource2
├── panelC
│  └── visualizationY
│      └── datasource1

대시보드 필터#

대시보드는 다음 필터를 지원합니다:

• 날짜 범위: 날짜별로 데이터를 필터링하는 날짜 선택기.

• 익명 사용자: 데이터셋에서 익명 사용자를 포함하거나 제외하는 토글.

• 프로젝트: 프로젝트별로 데이터를 필터링하는 드롭다운 목록.

• 필터링된 검색: 선택한 속성으로 데이터를 필터링하는 필터 바.

대시보드 상태#

status 배지가 있는 대시보드는 해당 개발 단계와 기능을 나타냅니다. status 배지가 없는 대시보드는 완전히 개발되어 프로덕션 준비가 된 것입니다.

지원되는 옵션은 다음과 같습니다:

• experiment

• beta

패널(Panel)#

패널은 대시보드의 기초를 형성하며 시각화의 컨테이너 역할을 합니다. 각 패널은 GlDashboardPanel이라는 GitLab 표준화된 UI 컴포넌트를 사용하여 구축됩니다.

시각화(Visualization)#

시각화는 데이터를 차트나 테이블과 같은 그래픽 형식으로 변환합니다. 다음 표준 시각화 타입을 사용할 수 있습니다:

• LineChart

• ColumnChart

• DataTable

• SingleStats

지원되는 모든 시각화 타입 목록은 analytics_visualization의 AnalyticsVisualization.type 열거형을 참조하세요. 하지만 이 옵션들로 제한되지 않으며, 필요에 따라 새로운 시각화 타입을 만들 수 있습니다.

데이터 소스(Data source)#

데이터 소스는 데이터베이스, 엔드포인트 또는 데이터 컬렉션에 대한 연결로, 대시보드가 결과를 쿼리, 검색, 필터링 및 시각화하는 데 사용할 수 있습니다. 핵심적으로 지원되는 데이터 소스 세트가 있지만(analytics_visualizations의 Data.type 열거형 참조), 필요에 맞게 새로운 데이터 소스를 추가할 수 있습니다.

모든 시각화 타입을 지원하려면, 데이터 소스가 단일 집계 값과 각 시점의 값을 가진 시계열 데이터를 반환해야 합니다.

각 패널은 다른 패널과 독립적으로 데이터 소스에서 별도로 데이터를 가져온다는 점에 유의하세요.

빌트인 대시보드 생성#

GitLab은 By GitLab이라는 레이블이 붙은 사전 정의된 대시보드를 제공합니다. 사용자는 이를 편집할 수 없지만, 복제하거나 유사한 커스텀 대시보드를 만드는 기초로 사용할 수 있습니다.

빌트인 Analytics 대시보드를 만들려면:

• ee/lib/gitlab/analytics 아래에 새 대시보드를 위한 폴더를 만듭니다. 예를 들어:

ee/lib/gitlab/analytics/cool_dashboard

• 새 폴더에 대시보드 구성 파일(예: dashboard.yaml)을 만듭니다. 구성은 ee/app/validators/json_schemas/analytics_dashboard.json에 정의된 JSON 스키마를 따라야 합니다. 예시:

# cool_dashboard/dashboard.yaml
---
title: My dashboard
description: My cool dashboard
panels: []

• 선택 사항. .yaml 구성 파일에서 필터의 enabled 옵션을 true로 설정하여 대시보드 필터를 활성화합니다:

# cool_dashboard/dashboard.yaml
---
title: My dashboard
filters:
  excludeAnonymousUsers:
    enabled: true
  dateRange:
    enabled: true
  projects:
    enabled: true
  filteredSearch:
    enabled: true
    # Use `options` to define an array of tokens to override the default ones
    options:
      - token: assignee
        unique: false
      - token: label
        maxSuggestions: 10

지원되는 필터 목록은 ee/app/validators/json_schemas/analytics_dashboard.json의 DashboardFilters 타입을 참조하세요.

• 선택 사항. 대시보드가 프로덕션 준비가 되지 않은 경우 적절한 상태를 설정합니다:

# cool_dashboard/dashboard.yaml
---
title: My dashboard
status: experiment

• 선택 사항. 대시보드 디렉터리에 템플릿 폴더(예: visualizations/)를 만들고 각 템플릿에 대한 구성 파일을 추가하여 시각화 템플릿을 만듭니다.

시각화 템플릿은 하나의 시각화가 여러 대시보드에서 사용될 때 사용할 수 있습니다. 템플릿을 사용하면 동일한 YAML 블록을 여러 번 복제하는 것을 방지할 수 있습니다. 빌트인 대시보드의 경우, 시각화 템플릿이 변경될 때 대시보드가 자동으로 업데이트됩니다. 사용자 정의 대시보드의 경우, 시각화 템플릿은 참조가 아닌 복사됩니다. 대시보드에 복사된 시각화 템플릿은 시각화 템플릿이 업데이트되어도 업데이트되지 않습니다.

각 파일은 ee/app/validators/json_schemas/analytics_visualization.json에 정의된 JSON 스키마를 따라야 합니다. 예시:

# cool_dashboard/visualizations/cool_viz.yaml
---
version: 1
type: LineChart    # The render type of the visualization.
data:
  type: my_datasource    # The name of the datasource
  query: {}
options: {}

query와 options 객체 모두 데이터 소스에 전달되어 적절한 쿼리를 구성하는 데 사용됩니다.

지원되는 데이터 소스 목록은 데이터 소스를, 지원되는 시각화 렌더 타입 목록은 시각화를 참조하세요.

• 시각화를 참조하는 패널을 대시보드에 추가하려면 다음 중 하나를 사용하세요:

권장. 대시보드 구성 파일 내에서 인라인 시각화를 사용합니다:

# cool_dashboard/dashboard.yaml
---
title: My dashboard
description: My cool dashboard
panels:
  - title: "My cool panel"
    tooltip:
      description: "This is a cool panel. %{linkStart}Learn more%{linkEnd}."
      descriptionLink: "https://gitlab.com"
    visualization:
      version: 1
      slug: 'cool_viz' # Recommended to define a slug when a visualization is inline
      type: LineChart    # The render type of the visualization.
      data:
        type: my_datasource    # The name of the datasource
        query: {}
      options: {}
    gridAttributes:
      yPos: 0
      xPos: 0
      width: 3
      height: 1

query와 options 객체 모두 데이터 소스에 전달되어 적절한 쿼리를 구성하는 데 사용됩니다.

지원되는 데이터 소스 목록은 데이터 소스를, 지원되는 시각화 렌더 타입 목록은 시각화를 참조하세요.

• 시각화 템플릿을 사용합니다:

# cool_dashboard/dashboard.yaml
---
title:  My dashboard
description: My cool dashboard

panels:
  - title: "My cool panel"
    tooltip:
      description: "This is a cool panel. %{linkStart}Learn more%{linkEnd}."
      descriptionLink: "https://gitlab.com"
    visualization: cool_viz    # Must match the visualization config filename
    gridAttributes:
      yPos: 0
      xPos: 0
      width: 3
      height: 1

gridAttributes는 12x12 대시보드 그리드 내에서 패널의 위치를 지정합니다.

tooltip은 패널 제목 옆에 도움말 아이콘을 추가하여 마우스 오버 시 description 텍스트와 %{linkStart} 및 %{linkEnd} 플레이스홀더 사이에 링크를 삽입하는 선택적 descriptionLink를 사용해 맥락별 도움말을 표시합니다. 또한 visualization.options의 시각화 레벨에서 tooltip을 정의하거나, 데이터 소스의 setVisualizationOverrides 콜백 함수를 사용하여 동적으로 정의할 수 있습니다. 패널 레벨 툴팁이 시각화 레벨 툴팁보다 우선합니다.

• 선택 사항. 패널에 views를 추가하여 사용자가 여러 시각화 간에 전환할 수 있도록 합니다. 패널은 2개에서 5개 사이의 뷰를 정의해야 합니다(Pajamas 세그먼트 컨트롤 참조). 각 뷰에는 text 레이블과 visualization(인라인 시각화 또는 시각화 템플릿)이 필요합니다. 첫 번째 뷰가 기본으로 선택됩니다. views가 설정될 때 스키마에 의해 패널 레벨 visualization 속성이 여전히 필요합니다. 첫 번째 뷰와 동일한 시각화로 설정하세요.

# cool_dashboard/dashboard.yaml
---
panels:
  - title: "Code Suggestions"
    visualization: suggestions_weekly
    views:
      - text: Weekly
        visualization: suggestions_weekly
      - text: Monthly
        visualization: suggestions_monthly
    gridAttributes:
      yPos: 0
      xPos: 0
      width: 6
      height: 4

• ee/app/models/analytics/dashboard.rb의 builtin_dashboards에 추가하여 대시보드를 등록합니다. 여기서 프로젝트 레벨 또는 그룹 레벨(또는 둘 다)에서 대시보드를 사용할 수 있도록 만들고, 기능 플래그, 라이선스 또는 사용자 권한 등에 따라 접근을 제한할 수 있습니다.

• 선택 사항. ee/app/models/analytics/visualization.rb의 get_path_for_visualization에 추가하여 시각화 템플릿을 등록합니다.

완전한 예시는 GitLab Duo 및 SDLC 트렌드 대시보드 구성을 참조하세요.

새 데이터 소스 추가#

새 데이터 소스를 추가하려면:

• fetch 메서드를 내보내는 새 JavaScript 모듈을 만듭니다. fetch API의 전체 문서는 analytics_dashboards/data_sources/index.js를 참조하세요. 예시로 cube_analytics.js도 참고할 수 있습니다.

• data_sources/index.js의 목록 내보내기에 모듈을 추가합니다.

• analytics_visualizations.json의 스키마 Data 타입 목록에 데이터 소스를 추가합니다.

데이터 소스는 필터를 준수하여 모든 패널이 동일한 필터링된 데이터를 표시해야 합니다.

새 시각화 렌더 타입 추가#

새 시각화 렌더 타입을 추가하려면:

• data와 options 속성을 받는 새 Vue 컴포넌트를 만듭니다. 예시로 line_chart.vue를 참조하세요.

• 시각화의 다양한 상태에 대한 관련 스토리북 스토리를 추가합니다. 예시로 line_chart.stories.js를 참조하세요.

• analytics_dashboard_panel.vue의 조건부 컴포넌트 임포트 목록에 컴포넌트를 추가합니다.

• analytics_visualization.json의 스키마 AnalyticsVisualization 열거형 타입 목록에 컴포넌트를 추가합니다.

기존 컴포넌트를 시각화로 마이그레이션#

기존 컴포넌트를 대시보드 시각화로 마이그레이션할 수 있습니다. 이를 위해 기존 컴포넌트를 필요한 컨텍스트와 데이터를 컴포넌트에 제공하는 새 시각화로 래핑합니다. 예시로 dora_performers_score.vue를 참조하세요.

업그레이드 경로로, 컴포넌트가 내부적으로 자체 데이터를 가져올 수 있습니다. 하지만 시각화를 공유 Analytics 데이터 소스 방법을 사용하도록 마이그레이션하는 방법을 계획해야 합니다. 예시로 value_stream.js를 참조하세요.

기능 플래그 뒤에 시각화 도입#

새 시각화를 개발하는 동안 기능 플래그를 사용하여 사용자에 대한 중단이나 잘못된 데이터의 위험을 줄일 수 있습니다.

from_data 메서드는 대시보드의 패널 객체를 구성합니다. filter_map 메서드를 사용하면 개발 중인 시각화를 포함하는 패널 렌더링을 건너뛰는 조건을 추가할 수 있습니다.

예를 들어, 여기서는 enable_usage_overview_visualization 기능 플래그를 추가하고 현재 상태를 확인하여 usage_overview 시각화를 사용하는 패널을 렌더링할지 여부를 결정합니다:

panel_yaml.filter_map do |panel|
  # Skip processing the usage_overview panel if the feature flag is disabled
  next if panel['visualization'] == 'usage_overview' && Feature.disabled?(:enable_usage_overview_visualization)

  new(
    title: panel['title'],
    project: project,
    grid_attributes: panel['gridAttributes'],
    query_overrides: panel['queryOverrides'],
    visualization: panel['visualization']
  )
end