개발 환경 구성
Sentry Relay는 최신 안정 버전의 Rust로 빌드되며, 워크스페이스 내 다수의 크레이트(crate)로 분리되어 있습니다. 따라서 빌드나 테스트 시 --all 및 --all-features 플래그를 함께 사용하는 것이 중요합니다. 특히 processing 기능을 활성화하려면 C 컴파일러와 CMake도 필요합니다.
빌드 전 librdkafka 라이브러리가 시스템 경로에 설치되어 있어야 합니다. macOS에서는 Homebrew를 통해 설치해야 하며, 다음 명령어로 간편하게 처리할 수 있습니다:
brew install librdkafka스크립트는 brew --prefix librdkafka를 사용하여 설치 위치를 확인하므로, 반드시 이 방법을 권장합니다.
IDE 설정
VSCode를 주요 개발 도구로 사용하며, 저장소 루트에 포함된 설정 파일을 통해 코드 스타일, Lint 규칙, 유용한 확장 프로그램을 관리합니다. 프로젝트를 처음 열 때 "추천 확장 프로그램 설치"를 수행하면 코딩 중 자동 형식 지정 및 정적 분석 기능을 즉시 활용할 수 있습니다.
주요 Make 명령어
루트 디렉터리의 Makefile은 개발 작업을 단순화하는 핵심 명령어들을 제공합니다:
make check: 코드 포맷과 Clippy 검사를 실행합니다. PR 생성 전 점검용으로 적합합니다.make test: Rust 단위 테스트, 통합 테스트, Python 패키지 테스트를 모두 실행합니다.make all: CI에서 수행되는 대부분의 검사와 테스트를 종합적으로 실행합니다.make clean: 빌드 산출물, virtualenv, 캐시 등을 완전히 제거합니다.
통합 테스트 준비
통합 테스트는 Redis와 Kafka가 기본 포트(각각 6379, 9092)에서 동작 중이어야 합니다. 가장 쉬운 방법은 Sentry의 devservices를 사용하는 것입니다. 이는 Sentry 로컬 개발 환경의 일부로, 필요한 모든 미들웨어를 컨테이너로 실행합니다.
빌드 및 실행
가장 간단한 실행 방법은 Cargo를 직접 사용하는 것입니다. 초기 설정 후 다음과 같이 실행합니다:
# Relay 설정 초기화
cargo run --all-features -- config init
# 전체 기능을 포함해 Relay 시작
cargo run --all-features -- run빌드 관련 make 타겟도 제공됩니다:
# 디버그 모드 빌드 (최적화 없음)
make build
# 릴리스 모드 빌드 (최적화 + 디버그 심볼 유지)
make release빠른 컴파일 검증은 다음 명령어로 가능합니다:
cargo check --all --all-features기능(feature) 관리
기본적으로 Relay는 프록시 전용 모드로 컴파일되며, 이벤트 처리 기능은 비활성화됩니다. 주요 선택 기능은 다음과 같습니다:
- processing: 이벤트 정규화, 필터링, 속도 제한, Kafka로의 데이터 생산 등 전체 처리 파이프라인을 활성화합니다.
- ssl: HTTPS 연결을 위한 SSL/TLS 지원을 포함합니다.
특정 기능을 활성화하려면 Cargo 명령에 --features 플래그를 추가하세요. 예:
cargo run --features=processing테스트 전략
테스트는 세 가지 범주로 나뉩니다:
- Rust 단위/통합 테스트:
# 기본 기능만 테스트
make test-rust
# 모든 기능 조합 테스트
make test-rust-allmake test-integration
# 특정 테스트만 실행
make build
.venv/bin/pytest tests/integration -k "test_event_processing"코드 품질 관리
코딩 스타일과 정적 분석은 rustfmt와 clippy를 사용하며, 다음 make 명령어로 실행합니다:
# 전체 코드베이스 포맷팅
make format
# lint 검사 실행
make lintPython 바인딩 및 C ABI 개발
Python 패키지에 새로운 기능을 추가하려면 먼저 C ABI 계층에서 인터페이스를 노출해야 합니다. 관련 문서는 Relay C-ABI 문서를 참조하세요.
Python 개발은 virtual environment 내에서 진행하는 것이 안전합니다. 네이티브 확장 모듈을 설치하려면:
# 릴리스 빌드 설치 (권장)
pip install --editable ./py
# 디버그 빌드 설치 (빠른 설치, 느린 실행)
RELAY_DEBUG=1 pip install --editable ./py테스트는 pytest를 사용하며, 다음 명령어로 실행합니다:
# 전체 Python 테스트 실행
make test-python
# 특정 테스트 실행
.venv/bin/pytest py/tests -k "test_sanitize_pii"자동 재시작 개발 서버
실시간 코드 변경 감지를 위해 systemfd와 cargo-watch를 설치하고 개발 모드를 사용할 수 있습니다:
cargo install systemfd cargo-watch
make devserver이 명령어는 소스 수정 시 자동으로 Relay를 재시작합니다.
SSL 인증서
저장소에는 개발용 SSL 인증서와 개인 키가 포함되어 있으며, PEM 및 PKCS #12(.pfx) 형식으로 제공됩니다. .pfx 파일의 암호는 password입니다.
Sentry 연동 설정
기존 Sentry 인스턴스(devserver, self-hosted, SaaS)와 연동하려면 .relay/config.yml에서 upstream 값을 설정하세요. 예:
relay:
upstream: http://localhost:8000/
port: 3001
logging:
level: trace
enable_backtraces: true
limits:
shutdown_timeout: 0
processing:
enabled: true
kafka_config:
- name: "bootstrap.servers"
value: "127.0.0.1:9092"
redis: "redis://127.0.0.1"Sentry devserver는 기본적으로 포트 3000에서 자체 Relay를 실행하지만, 포트 3001로 바인딩하면 충돌 없이 병렬 운영이 가능합니다. SDK에서 개발용 Relay를 사용하려면 DSN의 포트를 3001로 변경하세요:
http://<key>@localhost:3001/<id>
릴리스 관리
릴리스는 craft 도구를 사용해 관리됩니다:
- Relay 바이너리: 루트 디렉터리에서
craft prepare및craft publish실행. 캘린더 버전 체계(CalVer)를 사용하며 Sentry와 배포 일정을 조율합니다. - Python 라이브러리 및 C-ABI:
py/디렉터리 내에서 동일한 명령어 실행. SemVer(의미 버전)를 따릅니다.
관련 링크:
변경 사항 기록
변경 로그는 용도에 따라 두 곳에 기록됩니다:
- Python 패키지 영향 변경 (예: PII 필터링, 이벤트 정규화):
py/CHANGELOG.md - Relay 서버 변경: 루트
CHANGELOG.md에 아래 항목 중 하나로 분류 - Features: 사용자에게 공개되는 신규 기능
- Bug Fixes: 외부에 영향을 주는 오류 수정
- Internal: 내부 처리 로직 또는 processing 모드 관련 변경
각 항목은 PR 링크와 설명적인 메시지를 포함해야 하며, 형식 예:
- 이벤트 속성 길이 제한 강화. (#1234)변경 사항이 로깅 대상이 아닐 경우, PR 설명에 #skip-changelog를 추가하여 생략할 수 있습니다.