내부 애널리틱스 시스템은 GitLab 인스턴스의 사용자 행동과 시스템 상태를 추적해, 고객 성공 서비스와 이후 제품 개발에 활용할 수 있는 정보를 제공합니다.

이 문서는 새 기능을 개발하거나 기존 기능을 계측할 때 GitLab의 내부 애널리틱스 기능을 활용하는 방법과 관련 정보를 안내합니다.

기본 개념#

이벤트와 메트릭은 내부 애널리틱스 시스템의 기반입니다. 두 개념의 차이를 이해하는 것이 시스템을 사용하는 데 매우 중요합니다.

이벤트#

이벤트는 GitLab 인스턴스 안에서 일어난 동작의 기록입니다. 이슈 페이지 방문이나 상단 내비게이션 검색 위로 마우스 커서를 올리는 것과 같은 사용자 상호작용이 그 예입니다. 예약된 파이프라인의 성공이나 서드파티 시스템의 API 호출 수신처럼 백그라운드 시스템 처리로 발생하는 동작도 있습니다. 모든 동작이 추적되어 자동으로 기록된 이벤트가 되는 것은 아닙니다. 대신 어떤 동작이 제품 인사이트를 끌어내고 더 근거 있는 비즈니스 판단에 도움이 된다면, 그 동작이 일어날 때 이벤트를 추적할 수 있습니다. 생성된 이벤트 기록은 최소한 해당 동작이 일어났다는 정보를 담고 있으며, 그 동작에 수반된 컨텍스트에 대한 추가 정보를 담을 수도 있습니다. 컨텍스트의 예로는 누가 그 동작을 수행했는지, 동작 시점의 시스템 상태가 어땠는지에 대한 정보가 있습니다.

메트릭#

이벤트 기록 하나만으로는 충분한 정보가 되지 않으며 우연의 결과일 수도 있습니다. 분석의 토대를 마련하려면 공통된 특성을 가진 이벤트 집합을 살펴봐야 합니다. 여기에서 메트릭이 필요해집니다. 메트릭은 여러 정보 조각에 대해 수행하는 계산입니다. 예를 들어 새 기능이 릴리스된 뒤 유료 사용자가 그 기능 페이지를 방문한 이벤트 하나만으로는 새 기능의 성과를 알 수 없습니다. 그러나 새 기능 릴리스 직전 한 주 동안 발생한 페이지 조회 이벤트 수를 세어 릴리스 이후 한 주의 이벤트 수와 비교하면, 새 기능 릴리스로 인한 관심 증가에 대한 인사이트를 얻을 수 있습니다.

이 과정의 결과가 바로 메트릭입니다. 이벤트 기반 메트릭은 어떤 이벤트가 전체 기간 또는 지정한 기간에 몇 번 발생했는지 셉니다. 같은 이벤트를 여러 메트릭에서 사용할 수 있고, 하나의 메트릭이 이벤트 하나 또는 여러 개를 셀 수도 있습니다. 이벤트를 수행한 고유 사용자만 세는 것처럼 고유성 기준을 둘 수도 있지만, 반드시 그럴 필요는 없습니다.

메트릭이 반드시 이벤트에 기반할 필요는 없습니다. 설정값이나 데이터베이스 테이블의 행 수처럼 GitLab 인스턴스 자체의 상태에 대한 관측값일 수도 있습니다.

계측#

• 계측 계획을 세울 때는 이 템플릿을 사용합니다.
• 이벤트 기반 메트릭을 계측하는 방법은 내부 이벤트 추적 빠른 시작 가이드를 참고합니다.
• GitLab 인스턴스 상태를 관측하는 메트릭을 계측하는 방법은 메트릭 계측을 참고합니다.

데이터 탐색#

이벤트와 메트릭 데이터는 최종적으로 Snowflake 데이터 웨어하우스에 저장됩니다. 임시 분석을 위해 Snowflake에서 SQL로 직접 조회하거나, Snowflake에 접근할 수 있는 데이터 시각화 도구 Tableau에서 시각화할 수 있습니다. 두 플랫폼 모두 접근 요청이 필요합니다(Snowflake, Tableau).

Tableau#

Tableau는 데이터 시각화 플랫폼으로, 대시보드를 만들고 GUI로 이벤트와 메트릭을 탐색할 수 있습니다. 이 탐색 방식은 비즈니스 인텔리전스 도구에 익숙한 사용자, 기본적인 검증 작업, 그리고 저장해 공유할 수 있는 대시보드와 시각화를 만드는 데 가장 적합합니다. Tableau 접근에는 접근 요청이 필요합니다.

이벤트 확인#

Snowplow 이벤트 탐색 대시보드를 방문합니다. 이 대시보드에서는 이벤트 수와 가장 많이 발생한 이벤트를 확인할 수 있습니다. 아래로 스크롤해 "Structured Events Firing in Production Last 30 Days" 차트에서 원하는 이벤트 액션을 필터링할 수 있습니다. 이 필터는 정확한 이름으로만 동작합니다.

메트릭 확인#

메트릭 탐색 대시보드를 방문할 수 있습니다. 측면에는 메트릭의 key_path에 해당하는 메트릭 경로 필터와 설치 ID 필터가 있으며, GitLab.com을 필터링하는 방법도 안내되어 있습니다.

커스텀 차트 및 대시보드#

Tableau에서는 이 퍼널 분석처럼 더 복잡한 차트도 만들 수 있습니다. 커스텀 차트와 대시보드는 Product Data Insights 팀의 프로젝트에 이슈를 생성해 요청할 수 있습니다.

Snowflake#

Snowflake에서는 Snowflake SQL 방언으로 UI 안에서 웨어하우스의 관련 테이블을 직접 조회할 수 있습니다. 이 탐색 방식은 SQL에 익숙한 사용자와, 데이터가 올바르게 전파되었는지 빠르고 유연하게 확인하려는 경우에 가장 적합합니다. Snowflake 접근에는 접근 요청이 필요합니다.

이벤트 쿼리#

다음 예시 쿼리는 feature_used 이벤트의 일별 발생 횟수를 반환합니다.

SELECT
  behavior_date,
  COUNT(*) as event_occurences
FROM prod.common_mart.mart_behavior_structured_event
WHERE event_action = 'feature_used'
AND behavior_date > '2023-08-01' --restricted minimum date for performance
AND app_id='gitlab' -- use gitlab for production events and gitlab-staging for events from staging
GROUP BY 1 ORDER BY 1 desc

다른 메트릭 테이블 목록은 데이터 모델 치트 시트를 참고합니다.

메트릭 쿼리#

다음 예시 쿼리는 최근 6개월 동안 count_distinct_user_id_from_feature_used_7d로 보고된 모든 값과 그에 대응하는 instance_id를 반환합니다.

SELECT
  date_trunc('week', ping_created_at),
  dim_instance_id,
  metric_value
FROM prod.common.fct_ping_instance_metric_rolling_6_months --model limited to last 6 months for performance
WHERE metrics_path = 'counts.users_visiting_dashboard_weekly' --set to metric of interest
ORDER BY ping_created_at DESC

다른 메트릭 테이블 목록은 데이터 모델 치트 시트를 참고합니다.

Product Analytics#

내부 애널리틱스는 이벤트도 시각화할 수 있는 GitLab Product Analytics 기능을 직접 사용하고 있습니다. 커스텀 시각화와 대시보드를 만드는 방법은 애널리틱스 대시보드 문서에 설명되어 있습니다. GitLab 프로젝트 안에서 접근할 수 있는 커스텀 대시보드는 별도 리포지터리에 정의되어 있습니다. 내부 이벤트 시스템으로 계측한 이벤트를 기반으로 대시보드를 만들 수 있습니다. 이때 시각화에는 .com 설치 환경에서 발생한 이벤트만 집계됩니다.

개별 이벤트를 기반으로 차트를 만드는 방법은 Product Analytics 그룹의 대시보드를 참고할 수 있습니다.

데이터 가용성#

GitLab에서는 GitLab.com과 GitLab Self-Managed 또는 GitLab Dedicated 인스턴스의 애널리틱스 구성에 근본적인 차이가 있습니다.

Self-Managed 및 Dedicated#

GitLab 18.0 이상: Self-Managed와 Dedicated 인스턴스는 이벤트 수준 데이터를 수집하므로 GitLab.com과 동일한 수준의 자세한 인사이트를 제공합니다.

18.0 이전 버전: 집계된 메트릭만 제공됩니다. 이 메트릭은 매주 무작위로 정해진 하루에 한 번 계산되어 Service Ping이라는 과정을 통해 Version App으로 전달됩니다. 인스턴스가 실행 중인 버전까지 계측된 메트릭만 제공됩니다. 예를 들어 17.9 버전 개발 중에 계측된 메트릭은 17.9 이상을 실행하는 인스턴스에서는 제공되지만 17.8과 같은 이전 버전에서는 제공되지 않습니다. 전달받은 페이로드는 하루에 한 번 데이터 웨어하우스로 가져옵니다.

GitLab.com#

GitLab.com 인스턴스에서는 개별 이벤트와 사전 계산된 메트릭을 모두 분석에 사용할 수 있습니다. 또한 페이지 조회는 자동으로 계측됩니다.

개별 이벤트 및 페이지 조회#

개별 이벤트와 페이지 조회는 수집 인프라로 곧바로 전달되고, 거기에서 데이터 웨어하우스로 들어갑니다. 다만 이 단계의 데이터는 조회하기 어려운 원시 형태입니다. 그래서 데이터를 정제해 웨어하우스 전반으로 전파하고, 최종적으로 데이터 탐색 절에서 소개한 테이블과 다이어그램에서 사용할 수 있게 합니다.

전파 과정은 완료까지 여러 시간이 걸립니다. 다음 다이어그램은 이벤트의 가용 시점을 보여 줍니다.

출처

사전 계산된 메트릭#

메트릭은 Self-Managed와 마찬가지로 주 1회 계산되며, 계산의 대부분이 인스턴스가 아니라 웨어하우스 안에서 이루어진다는 점만 다릅니다. GitLab.com에서는 이 과정이 월요일 아침에 시작되어 일요일 23:59 UTC부터 그다음 일요일 23:59 UTC 까지의 기간에 대한 메트릭을 계산합니다.

다음 다이어그램은 이 과정을 보여 줍니다.

출처

데이터 흐름#

SaaS와 Self-Managed 인스턴스(GitLab 18.0 이상)에서는 이벤트 기록이 Snowplow라는 수집 시스템으로 직접 전송되어 데이터 웨어하우스로 들어갑니다. 18.0 이전 버전의 Self-Managed 인스턴스에서는 이벤트 수만 로컬에 기록됩니다. 매주 Service Ping이라는 과정이 사전 정의된 활성 메트릭의 현재 값을 데이터 웨어하우스로 전송합니다. GitLab.com에서는 메트릭이 데이터 웨어하우스에서 직접 계산됩니다.

다음 다이어그램은 이 데이터 흐름을 보여 줍니다.

flowchart LR;
    feature-->track
    track-->|send event record - GitLab.com, Self-Managed 18.0+ and Dedicated 18.0+|snowplow
    track-->|increase metric counts|redis
    database-->service_ping
    redis-->service_ping
    service_ping-->|json with metric values - weekly export|snowflake
    snowplow-->|event records - continuous import|snowflake
    snowflake-->vis
subgraph glb[Gitlab Application]
    feature[Feature Code]
    subgraph events[Internal Analytics Code]
        track[track_event / trackEvent]
        redis[(Redis)]
        database[(Database)]
        service_ping[\Service Ping Process\]
    end
end
snowplow[\Snowplow Pipeline\]
snowflake[(Snowflake Data Warehouse)]
vis[Dashboards in Tableau]</code></pre></details></div>

데이터 프라이버시#
GitLab 18.0 이상: GitLab은 프라이버시 보호를 위해 가명화된 식별자와 함께 Self-Managed 인스턴스의 이벤트 수준 데이터를 수집합니다.
18.0 이전 버전: GitLab은 Self-Managed 인스턴스에서 이벤트 수 또는 그와 비슷하게 집계된 정보만 받습니다. GitLab.com 버전에서는 개별 이벤트의 사용자 식별자가 가명화됩니다.
내부 애널리틱스 시스템으로 수집하는 데이터의 종류에 대한 정확한 설명은 핸드북에 있습니다.
기여 가이드라인#

내부 애널리틱스로 기능 계측하기
내부 애널리틱스 기여 리뷰하기
Internal Events CLI에 기여하기