사용자 정의 대시보드

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

대시보드 구조는 사용자 구성 파일을 저장하고 버전 관리하는 수단을 제공하지 않습니다. 이 기능은 Analytics 대시보드에서 제공되며, 이는 사용자 지정 대시보드 구성 요소를 사용합니다.

참고: 사용자 정의 대시보드는 프리미엄 및 얼티메이트 구독을 위해 제공됩니다.

개요

사용자 정의 대시보드는 3가지 논리적 구성 요소로 나뉠 수 있습니다.

  • 대시보드(대시보드)
  • 패널(패널)
  • 시각화(Visualizations)

대시보드는 렌더링할 패널 목록으로 구성되며, 각 패널은 하나의 시각화를 참조하며, 단일 시각화는 여러 패널에서 공유될 수 있습니다.

전형적인 대시보드 구조는 다음과 같습니다.

대시보드
├── 패널A
│  └── 시각화X
├── 패널B
│  └── 시각화Y
├── 패널C
│  └── 시각화Y

사용법

사용자 정의 대시보드를 사용하려면:

  1. 대시보드용 새 Vue 구성 요소를 생성하세요.
  2. 시각화 구성을 만드세요.
  3. 대시보드 구성을 만드세요.
  4. CustomizableDashboard의 인스턴스를 렌더링하고 대시보드 구성을 전달하세요.

시각화 구성

각 시각화는 데이터 원본에서 가져온 쿼리 결과의 그래픽 표현입니다.

// visualizations.js

export const pageViewsOverTime = {
  // 쿼리를 렌더링하는 데 사용되는 Vue 구성 요소의 이름입니다.
  type: 'LineChart',
  // 패널에서 사용되는 차트 라이브러리에서 정의된 차트 옵션입니다.
  options: {
    xAxis: { name: __('시간'), type: 'time' },
    yAxis: { name: __('횟수'), type: 'value' },
  },
  // 쿼리할 데이터
  data: {
    // 여기서는 제품 분석입니다.
    type: 'cube_analytics',
    // 데이터 원본에 대한 실행할 쿼리입니다. 여기서 Cube.js 형식입니다.
    query: {
      dimensions: [],
      filters: [
        {
          member: 'TrackedEvents.eventName',
          operator: 'equals',
          values: ['page_view']
        }
      ],
      measures: ['TrackedEvents.pageViewsCount'],
      timeDimensions: [
        {
          dimension: 'TrackedEvents.derivedTstamp',
          granularity: 'day',
        },
      ],
      limit: 100,
      timezone: 'UTC',
    },
  },
};

새로운 시각화 렌더링 유형 추가

새로운 시각화 렌더링 유형을 추가하려면:

  1. dataoptions 속성을 허용하는 새 Vue 구성 요소를 생성하세요. 예: line_chart.vue 참조.
  2. panel_base.vue의 조건부 가져오기 목록에 구성 요소를 추가하세요.
  3. analytics_visualizations.jsonAnalyticsVisualization 유형 목록에 구성 요소를 추가하세요.
기존 구성 요소를 시각화로 마이그레이션

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

업그레이드 경로로 구성 요소가 내부적으로 자체 데이터를 가져올 수 있습니다. 이 방법은 처음 몇 번의 반복에 대해서는 괜찮지만, 최종적으로는 표준 및 공유된 분석 데이터 원본 방법을 사용하도록 시각화를 마이그레이션해야 합니다. 예: value_stream.js 참조.

새 데이터 원본 추가

새 데이터 원본을 추가하려면:

  1. fetch 메서드를 내보내는 새 JavaScript 모듈을 생성하세요. 예: cube_analytics.js 참조.
  2. data_sources/index.js에서 모듈을 내보내는 리스트에 추가하세요.
  3. analytics_visualizations.jsonData 유형 목록에 데이터 원본을 추가하세요.

참고: 모든 패널에 동일한 날짜 범위의 데이터가 표시되도록 필터를 준수해야 합니다.

대시보드 구성

다음은 대시보드 구성의 예시입니다.

// constants.js
import { pageViewsOverTime } from './visualizations';

export const dashboard = {
  slug: 'my_dashboard', // 대시보드의 URL 경로를 설정하는 데 사용됩니다.
  title: '내 대시보드 제목', // 표시할 제목입니다.
  description: '대시보드에 대한 설명입니다.', // 대시보드에 대한 설명
  // 각 대시보드는 표시할 패널의 배열로 구성됩니다.
  panels: [
    {
      id: 1,
      title: '시간별 페이지 뷰', // 표시할 패널 제목입니다.
      // 시각화 구성입니다. 여러 패널에서 공유될 수 있습니다.
      visualization: pageViewsOverTime,
      // https://github.com/gridstack/gridstack.js/tree/master/doc#item-options를 기반으로 한 Gridstack 설정입니다.
      // 모든 값은 12까지의 그리드 행/열 번호입니다.
      // 우리는 기본 12열 그리드를 사용합니다. https://github.com/gridstack/gridstack.js#change-grid-columns.
      gridAttributes: {
        yPos: 1,
        xPos: 0,
        width: 6,
        height: 5,
      },
      // `visualization.data.query`의 값을 재정의하는 선택적 오버라이드입니다.
      // 여기서는 Cube.js 쿼리를 일자 대신 주간 단위의 페이지 뷰를 얻도록 오버라이드합니다.
      queryOverrides: {
        timeDimensions: {
          dimension: 'TrackedEvents.derivedTstamp',
          granularity: 'week',
        },
      },
    },
  ],
};

컴포넌트 사용

다음은 사용자 정의 대시보드를 렌더링하는 예시 컴포넌트입니다.

<script>
import CustomizableDashboard from 'ee/vue_shared/components/customizable_dashboard/customizable_dashboard.vue';
import { dashboard } from './constants';

export default {
  name: 'AnalyticsDashboard',
  components: {
    CustomizableDashboard,
  },
  data() {
    return {
      // 변경 사항을 추적하기 위해 원본(기본) 대시보드 객체를 유지합니다.
      dashboard: {
        ...dashboard,
        default: { ...dashboard, }
      },
      // 선택적 대시보드 필터입니다. 현재 사용 가능한 필터는 날짜 범위뿐입니다.
      defaultFilters: {
        dateRangeOption: 'last_7_days' // 'custom', 'today', 'last_7_days', 'last_30_days'
        endDate: new Date(2023, 06, 14),
        startDate: new Date(2023, 06, 7),
      },
      // URL 쿼리 문자열과 필터 객체를 동기화하려면 true로 설정합니다.
      syncUrlFilters: true,
      // 날짜 범위 필터를 표시하려면 true로 설정합니다.
      showDateRangeFilter: true,
      // 허용된 날짜 범위의 최대 크기입니다. 무제한으로 설정하려면 0입니다.
      dateRangeLimit: 0,
    };
  },
};
</script>

<template>
  <customizable-dashboard
    :initial-dashboard="dashboard"
    :default-filters="defaultFilters"
    :sync-url-filters="syncUrlFilters"
    :show-date-range-filter="showDateRangeFilter"
    :date-range-limit="dateRangeLimit"
  />
</template>

대시보드 디자이너

  • GitLab 16.1에 플래그 ‘combined_analytics_dashboards_editor’로 소개되었습니다. 기본으로 비활성화됩니다.
  • GitLab 16.6에서 일반 사용 가능하게 됩니다. 플래그 ‘combined_analytics_dashboards_editor’가 제거되었습니다.

대시보드 디자이너는 사용자가 사용자 정의 대시보드에서 패널을 수정하고 추가하기 위한 그래픽 인터페이스를 제공합니다. GitLab의 하드코딩된 대시보드에서는 사용할 수 없습니다.

참고: 대시보드 디자이너는 초기 실험 단계에 있으며 변경될 수 있습니다.

<script>
import { s__ } from '~/locale';

export const I18N_MY_NEW_CATEGORY = s__('Namespace|My data source');

export default {
  name: 'AnalyticsDashboard',
  data() {
    return {
      ...,
      // 대시보드 저장 상태를 렌더링하기 위해 true로 설정합니다.
      isSaving: false,
      // 기능별로 분류된 사용 가능한 시각화 목록입니다.
      availableVisualizations: {
        // 표시할 시각화 카테고리 제목입니다.
        [I18N_MY_NEW_CATEGORY]: {
          // 시각화 ID를 비동기적으로로드할 때 true로 설정합니다.
          loading: false,
          // 사용자가 대시보드에 추가할 수 있는 사용 가능한 시각화 ID 목록입니다.
          visualizationIds: [
            'page_views_over_time',
            'events_over_time',
          ],
        },
      }
    };
  },
  methods: {
    /**
     * 사용자가 현재 대시보드에 대한 변경 사항을 저장할 때의 이벤트 핸들러입니다.
     * @param  {String} dashboardId 현재 대시보드 ID입니다.
     * @param  {String} newDashboardObject 새로 수정된 대시보드 객체입니다.
     */
    saveDashboard(dashboardId, newDashboardObject) {
      // 변경 사항을 저장하고 `this.dashboard`를 수정합니다.
    },
    /**
     * 사용자가 새로운 패널에 시각화를 추가할 때의 이벤트 핸들러입니다.
     * @param  {String} visualizationId 시각화의 ID(일반적으로 파일 이름)입니다.
     * @param  {String} visualizationSource 새로운 시각화 구성을 가져오는 소스입니다.
     */
    addNewPanel(visualizationId, visualizationSource) {
      // 시각화를 로드하고 `this.dashboard.panels`에 새로운 패널을 추가합니다.
    },
  },
}
</script>

<template>
  <customizable-dashboard
    ...
    :available-visualizations="availableVisualizations"
    :is-saving="isSaving"
    @save="handleSave"
    @add-panel="handleAddPanel"
  />
</template>