Relay는 Sentry 아키텍처 내에서 클라이언트와 서버 간 데이터 전송을 중계하는 핵심 컴포넌트입니다. 특히 static 또는 proxy 모드로 실행 중인 경우, 로컬 파일 시스템을 통해 프로젝트 구성 정보를 관리할 수 있습니다. 이 방식은 기업 환경에서 데이터 필터링 및 접근 제어를 세밀하게 조정하는 데 유용합니다.

정적 프로젝트 설정은 기본적으로 .relay/projects 디렉터리에 위치합니다. 각 프로젝트는 고유한 ID를 기반으로 한 JSON 파일로 정의되며, 형식은 <PROJECT_ID>.json 입니다. 예를 들어:

.relay/
└── projects/
    ├── 17.json
    ├── 21.json
    └── 42.json
  

각 JSON 파일은 최소한 아래와 같은 필수 구조를 포함해야 합니다:

{
  "slug": "example-project",
  "publicKeys": [
    {
      "publicKey": "a1b2c3d4e5f67890123456789abcdefg",
      "isEnabled": true
    }
  ],
  "config": {
    "allowedDomains": ["*"]
  }
}

여기서 publicKey 값은 해당 프로젝트의 DSN(데이터 소스 이름)에서 추출한 것이며, Relay 자체 등록용 키와는 별개입니다. 이 키는 이벤트 전송 요청의 유효성을 검사하는 데 사용됩니다.

주요 구성 항목

slug

프로젝트의 사용자 정의 별칭으로, Sentry UI 상에서 표시됩니다. Relay는 현재 이 값을 필수로 요구하며, 누락 시 이벤트 처리가 거부될 수 있습니다.

"slug": "web-frontend"

disabled

프로젝트의 활성 상태를 제어합니다. true로 설정하면 해당 프로젝트로 들어오는 모든 이벤트가 즉시 폐기됩니다. 일시적인 차단이나 유지보수 시 유용합니다.

"disabled": false

publicKeys

하나 이상의 공개 키 목록을 포함하며, 각 키는 활성화 여부 플래그와 함께 제공됩니다. 단일 프로젝트가 여러 키를 가질 수 있지만, 오직 isEnabled: true로 설정된 키만 유효한 요청으로 간주됩니다.

"publicKeys": [
  {
    "publicKey": "validkey123abc",
    "isEnabled": true
  },
  {
    "publicKey": "deprecatedkey456xyz",
    "isEnabled": false
  }
]

DSN에서 키를 확인하려면 Sentry > Project Settings > Client Keys (DSN) 메뉴로 이동하고, URL 형식 https://<KEY>@oX.ingest.sentry.io/<PROJECT_ID> 에서 키 부분을 추출하면 됩니다.

config.allowedDomains

이벤트를 허용할 출처 도메인 목록을 지정합니다. 브라우저 기반 SDK에서 전송되는 Origin 또는 Referer 헤더와 비교하여 검증됩니다. 이 설정은 Sentry의 '허용된 도메인' 기능과 동일한 역할을 수행합니다.

"config": {
  "allowedDomains": ["app.company.com", "staging.company.com"]
}

빈 배열 [] 은 모든 도메인을 차단하며, 반대로 ["*"] 은 모든 출처를 허용합니다. 운영 환경에서는 가능한 한 구체적인 도메인을 명시하는 것이 보안상 권장됩니다.