기능 스펙에서 프런트엔드 및 백엔드 Snowplow 이벤트 캡처
GitLab v19.6요약
expect_snowplow_event는 Gitlab::Tracking.event에 대한 목(mock)입니다. 모든 스펙은 stub_snowplow를 호출하며, 이 호출은 브라우저의 Snowplow 트래커를 localhost로 향하게 합니다.
expect_snowplow_event는 Gitlab::Tracking.event에 대한 목(mock)입니다.
실제 페이로드를 검사하지 않으며 브라우저가 보내는 어떤 것도 볼 수 없으므로,
프런트엔드 Snowplow 이벤트는 스펙에서 전혀 검증할 수 없었습니다.
기능 스펙을 위해 만든 이 메커니즘은 GitLab이 백엔드와 브라우저 양쪽에서 내보내는
실제 페이로드를 캡처합니다.
프런트엔드 이벤트가 보이지 않던 이유#
모든 스펙은 stub_snowplow를 호출하며, 이 호출은 브라우저의 Snowplow 트래커를 localhost로 향하게 합니다.
테스트 환경에서는 그곳에서 수신하는 것이 없으므로, 프런트엔드가 발생시킨 이벤트는 올바르게 내보내지지만
전달될 곳이 없습니다.
캡처 동작 방식#
:capture_snowplow_events 태그가 지정된 스펙은 브라우저 트래커의 수집기 호스트 이름을
스펙이 이미 실행 중인 Capybara 서버로 향하게 합니다.
테스트 환경에 등록된 Rack 미들웨어(Gitlab::Testing::SnowplowCollectorMiddleware)가
해당 수집기 경로에 응답하고 모든 페이로드를 기록합니다.
백엔드 이벤트는 기존 테스트 이미터를 통해 계속 전달됩니다.
둘 다 같은 버퍼에 쌓이므로, 스펙은 출처와 관계없이 한곳에서 이벤트를 읽습니다.
이 방식은 실제 브라우저와 Capybara 서버에 의존하므로, 태그에는 :js가 필요하며
없으면 명확한 오류를 발생시킵니다.
추적에 대해 아무것도 검증하지 않는 예제가 설정 비용을 부담하지 않도록,
:capture_snowplow_events는 둘러싼 describe 또는 context 블록이 아니라
개별 예제에 지정합니다.
이벤트 버퍼는 태그가 지정된 각 예제 전에 생성되고 예제 후에 폐기되므로, 한 예제의 이벤트가 다른 예제에 보이는 일은 없습니다. 검증하는 내용은 단일 예제 안에서 충족할 수 있어야 합니다.
expect_snowplow_event는 :capture_snowplow_events 예제에서 동작하지 않습니다. 이 메서드는
stub_snowplow가 allow(Gitlab::Tracking).to receive(:event)로 설치하는 스파이에 대해 검증하지만,
:capture_snowplow_events 태그는 수집기 호스트 이름을 직접 제어해야 하므로 의도적으로
stub_snowplow를 건너뜁니다. 스파이가 없으면 expect_snowplow_event는 추적과 관련된 내용이 아니라
객체가 스파이가 아니라는 오류로 실패합니다. 대신 이 페이지의 헬퍼를 사용합니다.
기존 스펙을 이벤트 캡처를 사용하도록 변환할 때 특히 중요합니다.
이벤트를 직접 검증#
일회성 확인에는 다음 헬퍼를 직접 사용합니다.
captured_snowplow_events는 지금까지 캡처된 모든 항목을SnowplowEvent구조체로 반환합니다.find_snowplow_event(**attributes)는 기다리지 않고 첫 번째 일치 항목을 반환하며, 없으면nil을 반환합니다.wait_for_snowplow_event(**attributes)는 일치 항목이 나타날 때까지 폴링한 다음 그것을 반환합니다.
SnowplowEvent에는 다음 리더가 있습니다.
event_type, category, action, label, property, platform, experiment_context입니다.
platform은 Snowplow 자체가 정의한 필드입니다.
브라우저 이벤트는 "web", 백엔드 이벤트는 "srv"이며, 이 값으로 둘을 구별합니다.
event_type은 Snowplow의 e 필드입니다.
구조화된 이벤트는 "se", 페이지 뷰는 "pv"입니다.
event_type: 'pv'로 페이지 뷰를 일치시킬 수는 있지만, 어느 페이지였는지는 검증할 수 없습니다.
URL은 캡처되지 않습니다.
프런트엔드 이벤트는 수집기에 비동기로 POST되므로, 이벤트가 아직 도착하지 않았을 수 있으면
find_snowplow_event보다 wait_for_snowplow_event를 사용합니다.
이 헬퍼는 최대 Capybara.default_max_wait_time(로컬에서는 10초, CI에서는 30초) 동안 폴링하며,
실패하면 캡처된 모든 이벤트를 출력합니다.
속성 값은 케이스 동등(===)으로 비교되므로, 리터럴 문자열뿐 아니라 include(...) 같은 RSpec 매처나
정규식도 전달할 수 있습니다.
it 'tracks the upgrade banner dismissal', :js, :capture_snowplow_events do
click_button 'Dismiss'
event = wait_for_snowplow_event(action: 'dismiss_upgrade_banner')
expect(event.property).to include('trial')
end
추적 여정 계약 검증#
스펙에 인라인으로 작성한 검증은 그 스펙이 삭제되거나 다시 작성되는 날 사라지며,
이벤트 집합이 계속 발생한다는 보장도 함께 사라집니다.
추적 여정 계약은 이를 방지합니다. 여정의 이름을 딴 spec/fixtures/snowplow_tracking_journeys/ 아래의
YAML 파일로, 여정이 내보내야 하는 이벤트를 선언합니다.
계약은 개별 스펙보다 오래 유지되며, 여정을 진행하는 Ruby 코드를 읽지 않고도 이해할 수 있습니다.
파일 이름은 검증에 사용하는 인수와 직접 대응합니다.
spec/fixtures/snowplow_tracking_journeys/invite_registration.yml의 계약은
expect_snowplow_tracking_journey('invite_registration')로 검증하며, 이 호출은 선언된 모든 이벤트를
차례로 기다립니다.
전체 스펙은 다음과 같습니다.
RSpec.describe 'SaaS registration from an invite', :js, :saas_registration, feature_category: :onboarding do
let_it_be(:group) { create(:group, name: 'Test Group') }
it 'registers the user and sends them to the group page', :capture_snowplow_events do
registers_from_invite(group: group)
fill_in_welcome_form
click_on 'Get started!'
expect_snowplow_tracking_journey('invite_registration')
end
end
이벤트를 발생시키는 상호 작용 뒤에 검증을 마지막으로 두어, 선언된 모든 이벤트가 발생할 기회를 가지도록 합니다.
계약은 다음과 같습니다.
---
description: |
What this journey is, and why these events matter.
events:
- category: InvitesController
action: join_clicked
label: invite_email
- category: registrations:new
action: register
label: invite_registration
나열한 필드만 확인하므로, 계약은 여정에 필요한 만큼 느슨하게도 엄격하게도 작성할 수 있습니다. 여정 중에 발생하지만 선언되지 않은 이벤트는 허용됩니다. 계약은 선언된 이벤트가 발생한다는 것만 보장하며, 다른 이벤트가 발생하지 않는다는 것은 보장하지 않습니다.
발생하는 이벤트 찾기#
이벤트 이름과 카테고리를 추측하지 않습니다. 특히 프런트엔드 카테고리는 이벤트가 발생한 페이지이며, 추측하는 값과 다른 경우가 많습니다.
대신 실패한 검증이 알려 주도록 합니다.
- 여정에 필요한 상호 작용으로 스펙을 작성하고, 확실하게 알고 있는 이벤트 하나를 선언한 계약을 검증합니다.
- 스펙을 실행합니다. 이벤트를 찾지 못하면 실패 메시지에 실행 중 캡처된 모든 이벤트가 카테고리, 액션, 레이블, 속성, 실험 컨텍스트와 함께 출력됩니다.
- 중요한 이벤트를 계약에 복사하고, 조직 폴백이나 일반 활동 이벤트 같은 부수적인 이벤트는 제외합니다.
실험#
계약은 실험의 이름을 지정하고 variants: 아래에 실험군을 선언할 수 있습니다. 이 예시의
이름은 설명을 위한 것입니다.
---
experiment: my_experiment
description: |
...
variants:
candidate:
events:
- category: my_experiment
action: assignment
- action: click_call_to_action
- category: my_experiment
action: finish_signup
control:
events:
- category: my_experiment
action: assignment
- action: click_call_to_action
- category: my_experiment
action: finish_signup
한 번에 하나의 실험군을 variant:로 검증합니다.
expect_snowplow_tracking_journey('my_experiment', variant: variant)
experiment:가 설정되면, 검증 중인 실험군에 선언된 모든 이벤트는 주어진 변형에 대해 해당 실험의
컨텍스트를 추가로 포함해야 하므로, 이벤트마다 컨텍스트를 반복해서 쓸 필요가 없습니다.
실험 이벤트는 category가 아니라 그 컨텍스트로 일치시킵니다.
백엔드 실험 이벤트는 실험 이름을 카테고리로 사용하지만, 프런트엔드 이벤트는
root:index처럼 이벤트가 발생한 페이지로 분류됩니다.
컨텍스트는 두 종류의 이벤트가 모두 가지고 있는 유일한 필드입니다.
variants:는 임시로 사용하도록 만들어졌습니다.
실험을 정리한 후 우승한 실험군의 이벤트를 최상위 events: 키로 옮기고
experiment:와 variants:를 삭제하여 영구적인 여정 계약을 남깁니다.
발생할 수 있는 오류#
스펙이나 계약이 잘못 구성되면 expect_snowplow_tracking_journey는 ArgumentError를 발생시킵니다.
각 오류는 제품의 문제가 아니라 스펙이나 YAML 파일에서 고쳐야 할 부분이 있다는 뜻입니다.
| 메시지 | 의미 |
|---|---|
No tracking journey named '' in |
해당 이름의 계약 파일이 없습니다. |
declares no variants, drop variant: |
variants: 섹션이 없는 계약에 variant:를 전달했습니다. |
declares variants a, b, pass one |
계약에 실험군이 있으므로 variant:로 어느 것인지 지정해야 합니다. |
has no variant '', only a, b |
전달한 실험군 이름이 계약의 어떤 실험군과도 일치하지 않습니다. |
declares no events to assert |
계약 또는 선택한 실험군에 선언된 이벤트가 없으므로, 아무것도 확인하지 않고 검증이 통과합니다. |
스펙이 캡처한 이벤트 읽기#
:capture_snowplow_events 태그가 지정된 모든 예제는 예제 자체에서 검증하는 내용 외에도
캡처한 내용을 디스크에 기록합니다.
추가 설정은 필요하지 않습니다.
로컬에서는 덤프가 tmp/captured_snowplow_events/ 아래에 저장됩니다.
CI에서는 rspec/captured_snowplow_events/ 아래에 저장되며, .gitlab/ci/rails/shared.gitlab-ci.yml의
.artifact-base 앵커가 이 디렉터리를 포함하므로 테스트 잡이 이를 잡 아티팩트로 수집합니다.
아티팩트는 31일 후에 만료됩니다.
각 예제는 RSpec 예제 ID를 딴 자체 디렉터리를 가지며, 이 ID는 스펙 파일 경로에
예제의 범위 지정 위치를 더한 값입니다(예: 1-1-1-1).
설명은 고유하지 않으므로 설명 대신 ID를 사용합니다.
공유 예제는 실행되는 모든 컨텍스트에 같은 설명을 가져가므로, 그렇지 않으면 실험의 두 실험군이
같은 디렉터리에서 충돌합니다.
tmp/captured_snowplow_events/
index.json
ee/spec/features/experiments/my_experiment_events_spec/
1-1-1-1/ events.yml payloads.json
1-2-1-1/ events.yml payloads.json
각 예제 디렉터리에는 두 파일이 있습니다.
events.yml은 구조화된 이벤트를 추적 여정 계약과 같은 형태로 담으며, 중복을 제거하고 이벤트에 없던 필드는 제외합니다. 헤더 주석에는 예제 설명, 파일과 줄, UTC 타임스탬프, 그리고 계약으로 표현할 수 없는 페이지 뷰와 자기 기술(self-describing) 이벤트의 개수가 기록됩니다.payloads.json은 수집기에 POST되었을 원시 페이로드를 그대로 담습니다.
# Captured from: My experiment when assigned the candidate variant ...
# ./ee/spec/features/experiments/my_experiment_events_spec.rb:16 at 2026-09-02T08:28:00Z
#
# Frontend categories are the page an event fired on, so they are rarely worth asserting.
# Also captured, not expressible in a contract: 1 page view, 1 self-describing event
---
events:
- category: my_experiment
action: assignment
- category: root:index
action: click_call_to_action
루트에 있는 index.json은 예제별로 항목 하나씩, 각 예제의 덤프를 그것이 증명하는 추적 여정과
변형에 매핑하므로, 어떤 스펙이 생성했는지 몰라도 실험 이름으로 덤프를 찾을 수 있습니다.
여정을 검증하지 않고 이벤트를 캡처한 예제나 여정 검증에 실패한 예제는
"journey": null로 나열됩니다.
성공한 항목은 다음과 같습니다.
{
"journey": "my_experiment",
"variant": "candidate",
"events": "ee/spec/features/experiments/my_experiment_events_spec/1-1-1-1/events.yml",
"payloads": "ee/spec/features/experiments/my_experiment_events_spec/1-1-1-1/payloads.json"
}
예제를 다시 실행하면 해당 디렉터리가 교체되므로, 디스크의 내용은 항상 가장 최근 실행의 결과입니다.
이 덕분에 실험 이벤트의 증거를 롤아웃 이슈에 게시할 때 Docker에서 Snowplow Micro를 실행하고
UI에서 이벤트를 수동으로 복사할 필요가 없어집니다.
events.yml의 내용을 이슈에 붙여 넣습니다.
각 CI 잡은 그 안에서 실행된 예제만 기록하므로, 덤프는 병렬 rspec system 및
rspec-ee system 잡에 분산되고 각 index.json은 단일 잡만 다룹니다.
올바른 샤드를 찾는 데는 스펙을 직접 실행하는 것보다 시간이 오래 걸리므로,
롤아웃 증거를 수집할 때는 보통 로컬 실행이 더 빠릅니다.
범위와 제한#
- 이 방식은 애플리케이션이 실제로 내보내는 페이로드를 증명합니다. 캡처는 HTTP POST 직전의 마지막 지점에서 이루어지므로, 재구성한 것이 아니라 실제 페이로드입니다.
- 수집기가 실행되지 않으므로 이벤트 컨텍스트는 Iglu 스키마 레지스트리에 대해 검증되지 않습니다. 검증이 필요하면 Snowplow Micro를 사용합니다. 로컬 설정 및 디버깅을 참조합니다.
- 계약은 이벤트가 프런트엔드인지 백엔드인지 기록하지 않으므로, 둘 사이를 오가는 이벤트도 계약을 계속 충족합니다.