사용자 정의 대시보드

사용자 정의 대시보드는 GitLab이나 사용자가 만든 대시보드 구성을 렌더링하고 수정하는 데 사용되는 구성 기반 대시보드 구조를 제공합니다.

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

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

개요

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

  • 대시보드
  • 패널
  • 시각화

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

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

대시보드
├── 패널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.json의 스키마의 AnalyticsVisualization 유형 목록에 구성 요소를 추가합니다.
기존 구성 요소를 시각화로 마이그레이션

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

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

새 데이터 원본 추가

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

  1. fetch 메서드를 내보내는 새 JavaScript 모듈을 만듭니다. 예시: cube_analytics.js.
  2. data_sources/index.js의 내보내기 목록에 모듈을 추가합니다.
  3. 스키마의 Data 유형 목록에 데이터 원본을 추가합니다. 예시: analytics_visualizations.json.

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

피드백 및 오류 처리

시각화 패널은 패널별로 알림 형태로 피드백을 제공할 수 있습니다. 이를 통해 사용자가 패널 위에 마우스를 올리면 패널을 강조하고 팝오버에서 추가 정보를 표시할 수 있습니다. 예시: GitLab storybook에서 온라인 예시를 확인할 수 있습니다.

Pajamas 가이드라인을 기반으로 지원되는 알림 변형은 다음과 같습니다:

  • danger: 데이터 또는 패널을 로드하는 중에 복구할 수 없는 오류가 발생한 경우
  • warning: 패널에 표시되는 데이터에 영향을 주는 오류 또는 추가 정보가 있는 경우
  • info: 패널에 대한 추가 정보 또는 팁이 있는 경우

시각화 패널은 알림을 렌더링하기 위한 props를 제공합니다: - showAlertState: 패널의 알림을 표시하거나 숨기는 불리언 값 - alertVariant: 기본적으로 danger 변형으로 설정된 알림의 유형 - alertPopoverTitle: 알림의 제목 텍스트

alert-popover 슬롯을 사용하여 알림의 본문 콘텐츠를 사용자 정의할 수 있습니다:

<!-- 실패 목록을 포함하는 위험 팝오버 상태를 표시 -->
<panels-base
 :title="오류가 있는 테스트 패널"
 :show-alert-state="true"
 :alert-variant="VARIANT_DANGER"
 :alert-popover-title="아주 나쁨!"
>
  <template #alert-popover>
    <p>{{ "다음과 같은 실패가 발생했습니다." }}</p>
    <ul>
      <li>{{ "api 로드에 실패했습니다" }}</li>
      <li>{{ "ui 로드에 실패했습니다" }}</li>
    </ul>
  </template>
</panels-base>
danger 알림

패널의 danger 알림 예시입니다.

패널 위험 알림

warning 알림

패널의 warning 알림 예시입니다.

패널 경고 알림

info 알림

패널의 info 알림 예시입니다.

패널 정보 알림

대시보드 구성

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

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

export const dashboard = {
  slug: 'my_dashboard', // 대시보드의 URL 경로를 설정하는 데 사용됩니다.
  title: '나의 대시보드 제목', // 표시할 제목입니다.
  description: '대시보드에 대한 설명입니다.', // 대시보드에 대한 설명
  userDefined: true, // 대시보드 편집기는 true일 때만 사용 가능합니다.
  // 각 대시보드는 표시할 패널의 배열로 구성됩니다.
  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 PanelsBase from `ee/vue_shared/components/customizable_dashboard/panels_base.vue`;
import { dashboard } from './constants';

export default {
  name: '나의사용자정의대시보드',
  components: {
    CustomizableDashboard,
    PanelsBase,
  },
  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,
      // 편집 중인 경우 각 패널에 표시할 GlDisclosureDropdown 항목 배열입니다.
      panelActions: [
        {
          text: __('삭제'),
          action: () => this.$emit('delete'),
          icon: 'remove',
        },
      ],
    };
  },
};
</script>

<template>
  <customizable-dashboard
    :initial-dashboard="dashboard"
    :default-filters="defaultFilters"
    :sync-url-filters="syncUrlFilters"
    :show-date-range-filter="showDateRangeFilter"
    :date-range-limit="dateRangeLimit"
  />
    <template #panel="{ panel, filters, editing, deletePanel }">
      <!-- 패널의 시각화를 여기에 렌더링합니다 -->
      <panels-base
        :title="panel.title"
        :editing="editing"
        :actions="panelActions"
        @delete="deletePanel"
      >
        <template #body>
          <!-- 패널의 시각화를 여기에 렌더링합니다 -->
        </template>
      </panels-base>
    </template>
  </customizable-dashboard>
</template>

대시보드 디자이너

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

CustomizableDashboard 구성 요소는 사용자가 기존 대시보드의 패널을 수정하고 새 대시보드를 만들 수 있는 그래픽 인터페이스를 제공합니다.

대시보드 편집기는 dashboard.userDefinedtrue일 때에만 사용할 수 있습니다.

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

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

export default {
  name: '나의사용자정의대시보드',
  data() {
    return {
      ...,
      // 변경 사항을 추적하기 위해 초기 저장된 대시보드입니다.
      initialDashboard: dashboard,
      // 대시보드 저장 상태를 렌더링할지 여부를 설정합니다.
      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.isSaving = true;
      // 변경 사항을 어딘가에 저장합니다.
      // 그런 다음 저장된 대시보드 버전을 업데이트합니다.
      this.initialDashboard = newDashboardObject;
      this.isSaving = false;
    },
  },
}
</script>

<template>
  <customizable-dashboard
    :initial-dashboard="initialDashboard"
    :available-visualizations="availableVisualizations"
    :is-saving="isSaving"
    @save="saveDashboard"
  />
    <template #panel="{ panel, filters, editing, deletePanel }">
      <my-dashboard-panel :panel="panel" />
    </template>
  </customizable-dashboard>
</template>

기능 플래그 뒤에 있는 시각화 소개

새로운 시각화를 개발하는 동안 기능 플래그를 사용하여 사용자의 중단 또는 잘못된 데이터의 위험을 완화할 수 있습니다.

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

예를 들어, 여기서는 enable_usage_overview_visualization 기능 플래그를 추가했으며 현재 상태를 확인하여 usage_overview 시각화를 사용하는 패널을 렌더링해야 하는지를 결정할 수 있습니다:

panel_yaml.filter_map do |panel|
  # 기능 플래그가 비활성화된 경우 usage_overview 패널 처리 건너뜁니다
  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