giip

GA 수집 파이프라인 가이드

GA4 데이터가 등록 → 수집(원시) → AI 집계 → 표시의 어느 단계에서 막혀 있는지 속성별로 한눈에 보여주는 진단 화면입니다.

🔗 GA 수집 파이프라인 열기 →

📋 개요

GA4 지표가 **GA 분석 리포트**에 표시되기까지는 4단계를 거칩니다.

단계의미저장 위치
카탈로그(등록)**GA 속성 관리**에서 속성 등록tGaProperty
수집(원시)수집기가 GA4 Data API에서 받아온 원시 지표tKVS(kType='ga')
AI 집계원시 지표를 AI가 가공한 리포트tGaAiReport
표시위 결과를 화면에 표시/ko/gareport

등록만 해두고 수집기가 없으면 카탈로그 단계에서 멈춰 화면에 아무 것도 안 뜹니다 — 이 페이지가 바로 "어느 단계가 비어 있는지"를 보여줍니다.

🚦 상태 표시

상태의미
정상수집·AI 집계 모두 정상
AI 대기원시 수집은 됐지만 AI 집계가 아직 안 됨
수집 미가동원시 수집 자체가 안 되고 있음(가장 흔한 문제)
비활성속성이 비활성 상태(수집 안 함)

▶️ "수집 개시" 버튼

수집 미가동 상태인 속성은 행에 [수집 개시] 버튼이 뜹니다. 클릭하면 그 속성의 GA4 수집을 지금 즉시 1회 트리거합니다(정기 수집 스케줄과는 별개로 즉시 실행).

버튼을 눌렀을 때 뜰 수 있는 메시지:

메시지원인해결
수집을 개시했습니다정상잠시 후 새로고침해서 "수집(원시)" 시각이 채워지는지 확인
이 조직에는 아직 GA 수집기(GA Collector)가 등록되어 있지 않습니다이 조직(csn) 소속으로 실행되는 GA 수집 스케줄(CQE) 자체가 한 번도 등록된 적이 없음 — 코드 문제가 아니라 미설정 상태아래 "🔗 GA 수집기 서버 연동" 절차대로 관리자가 최초 1회 등록
이 GA 속성에 대한 수집 권한이 없습니다다른 조직 소속 속성이거나 로그인 계정이 그 조직 소속이 아님올바른 조직(csn)으로 전환 후 재시도

🔗 GA 수집기 서버 연동(관리자용)

"GA 수집기가 등록되어 있지 않습니다" 메시지는 어떤 서버(lssn)도 이 조직의 GA 수집 작업을 정기적으로 돌리도록 연결돼 있지 않다는 뜻입니다. 이건 화면에서 속성을 등록하는 것과는 별개의, 서버 인프라 연동 작업이라 별도 절차가 필요합니다.

왜 웹 UI만으로는 안 되나

CQE(예약 스크립트) 등록 화면(/ko/cqeRepoPut)은 스크립트 본문 입력에 4,000자 제한이 있는데, GA 수집 스크립트 본문은 이보다 훨씬 깁니다(Linux판 약 7,800자, Windows판 약 9,700자). 그래서 스크립트 자체의 최초 등록은 CLI로만 가능합니다. 서버(lssn) 연동/스케줄 배정은 웹 UI로도 가능합니다.

1단계 — 수집 스크립트 등록 + 서버 연동(최초 1회, CLI)

giipdb/mgmt/register-ga-cqe.ps1을 사용합니다. 이 스크립트가 아래 두 가지를 한 번에 처리합니다:

  1. 수집 스크립트 본문을 CQE 저장소에 등록(CQERepoPut) → mssn 발급
  2. 그 스크립트를 지정한 서버(lssn)에 매일 실행되도록 배정(CQEQueuePut)
# Linux 서버 대상 (권장 — DB에 저장된 키를 자동 조회해서 사용, 로컬 키 파일 불필요)
pwsh .\mgmt\register-ga-cqe.ps1 -Lssn <대상 서버 lssn> -MsType sh `
     -Property 'properties/123456789' -Auid '<본인 로그인ID>'

# Windows 서버 대상 (giip-803 이후: -KeyFile 생략 시 DB 키 자동 조회)
pwsh .\mgmt\register-ga-cqe.ps1 -Lssn <대상 서버 lssn> -MsType ps1 `
     -Property 'properties/123456789' -Dispatcher 'https://<giip byAK 디스패처 URL>' -Auid '<본인 로그인ID>'

중요: 대상 서버(-Lssn)는 반드시 그 GA 속성이 등록된 조직(csn) 소속 서버여야 합니다. 다른 조직 소속 서버로 등록하면 인증은 통과해도 "이 조직 소속 GA 속성/키를 못 찾음"으로 계속 실패합니다 — **서버 목록**에서 대상 서버가 올바른 조직 소속인지 먼저 확인하세요.

-Property로 지정한 속성은 반드시 GA 속성 관리 화면에 먼저 등록되어 있고(서비스계정 키까지 등록된 상태) 있어야 합니다.

2단계 — 이미 등록된 스크립트를 다른 서버에도 연동(웹 UI 가능)

스크립트(mssn)가 이미 있는 상태에서 다른 서버에도 같은 수집을 돌리고 싶다면 웹 UI로 가능합니다.

  1. CQE 큐 등록 페이지로 이동
  2. mssn: [선택] 버튼으로 기존 "GA Collector..." 스크립트를 검색해 선택
  3. Lssn Group: 대상 서버(들) 체크
  4. csn: 대상 조직 번호
  5. interval: 수집 주기(분). 매일 1회면 1440
  6. custom_values: 아래처럼 서버별 값 입력(셸 스크립트 대상 기준) 
    GaProperty='properties/123456789'
    (서비스계정 키는 DB에서 자동 조회되므로 GaKeyFile은 넣지 않아도 됩니다.)
  7. 저장 — 완료 후 **서버별 실행 목록**에서 등록 확인

등록 상태 확인

🔗 다음 단계

버전: 1.0 최종 업데이트: 2026-07-29 소스 파일: giipv3/public/help/ga-pipeline.ko.md

← PreviousBP Projects & BP Partner Recruitment｜Streamline BP Sales with AINext →GSC Site Management Guide