히스토리

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

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

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

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

• GitLab 19.2에서 패널 제목 아이콘 구성이 도입됨.

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"
    titleIcon: chart
    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"
    titleIcon: chart
    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 대시보드 그리드 내에서 패널의 위치를 지정합니다.

titleIcon은 패널 제목 옆에 아이콘을 추가합니다. 패널이 오류 상태일 때는 제목 아이콘 대신 경고 아이콘이 표시됩니다.

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