본문으로 건너뛰기
버전: 4.6.1-saas

문제 해결

NetFUNNEL Java Agent 통합에 대한 일반적인 문제, 해결 방법 및 자주 묻는 질문입니다.

설치 문제​

라이브러리 설치 실패​

증상:

  • netfunnel-agent.jar 파일을 찾을 수 없음
  • 의존성 추가 실패

해결 방법:

  1. JAR 파일 확인: netfunnel-agent.jar 파일이 libs 폴더에 있는지 확인
  2. 의존성 경로 확인: Gradle/Maven 설정에서 JAR 파일 경로가 올바른지 확인
  3. 외부 의존성 확인: gson, jackson-module-kotlin이 올바르게 추가되었는지 확인

초기화 실패​

증상:

  • 서버 시작 시 에러 발생
  • NetFUNNEL이 초기화되지 않음

해결 방법:

  1. clientId 확인: clientId가 올바르게 설정되었는지 확인
  2. secretKey 확인: secretKey가 올바르게 설정되었는지 확인
  3. 빈 문자열 확인: clientId와 secretKey가 빈 문자열이 아닌지 확인
  4. 빌드 확인: 프로젝트가 올바르게 빌드되었는지 확인

Interceptor/Filter 문제​

Interceptor가 동작하지 않음​

증상:

  • Interceptor가 호출되지 않음
  • NetFUNNEL 로직이 실행되지 않음

해결 방법:

  1. 등록 확인: WebMvcConfigurer의 addInterceptors 메서드가 올바르게 구현되었는지 확인
  2. 경로 패턴 확인: addPathPatterns가 올바르게 설정되었는지 확인
  3. 빈 등록 확인: Interceptor가 @Component로 등록되었는지 확인
  4. 순서 확인: 다른 Interceptor와의 순서 문제가 없는지 확인

Filter가 동작하지 않음​

증상:

  • Filter가 호출되지 않음
  • NetFUNNEL 로직이 실행되지 않음

해결 방법:

  1. 등록 확인: FilterRegistrationBean이 올바르게 등록되었는지 확인
  2. URL 패턴 확인: addUrlPatterns가 올바르게 설정되었는지 확인
  3. 순서 확인: setOrder로 Filter 순서가 올바르게 설정되었는지 확인

트리거 규칙 문제​

트리거 규칙이 매칭되지 않음​

증상:

  • 대기열이 적용되지 않음
  • 규칙에 부합하는 URL에도 대기실이 표시되지 않음

해결 방법:

  1. 규칙 확인: 콘솔에서 트리거 규칙이 올바르게 설정되었는지 확인
  2. URL 확인: 접속한 URL이 규칙의 Value와 일치하는지 확인
  3. Match 옵션 확인: Match 옵션(Equals, Contains, StartsWith, EndsWith)이 올바른지 확인
  4. 대소문자 확인: Aa 옵션(대소문자 구분) 설정 확인
  5. 테스트 기능 사용: 콘솔의 트리거 규칙 테스트 기능으로 URL이 규칙에 부합하는지 확인

대기실이 표시되지 않음​

증상:

  • 규칙에 부합하는 URL에도 대기실이 표시되지 않음
  • 사용자가 직접 진행함

해결 방법:

  1. 세그먼트 활성화: 세그먼트가 활성화되어 있는지 확인
  2. 진입 상태 확인: 진입 상태가 Waiting으로 설정되었는지 확인
  3. 진입 허용수 확인: 테스트를 위해 진입 허용수를 0으로 설정
  4. 규칙 매칭 확인: 트리거 규칙이 올바르게 매칭되는지 확인

네트워크 및 연결 문제​

네트워크 연결 오류​

증상:

  • NetFUNNEL 서버에 연결할 수 없음
  • 요청이 실패함

해결 방법:

  1. 연결 확인: 인터넷 연결 상태 확인
  2. 방화벽: NetFUNNEL 도메인이 차단되지 않았는지 확인
  3. 프록시 설정: 필요한 경우 프록시 구성
  4. 서버 URL 확인: serverUrl 설정이 올바른지 확인

타임아웃 오류​

증상:

  • 요청이 타임아웃됨
  • 응답을 받지 못함

해결 방법:

  1. 네트워크 상태 확인: 네트워크 연결 상태 확인
  2. 서버 상태 확인: NetFUNNEL 서버 상태 확인
  3. 설정 확인: 초기화 설정이 올바른지 확인

로깅 문제​

로그가 출력되지 않음​

증상:

  • 로그 레벨을 설정했지만 로그가 출력되지 않음

해결 방법:

  1. 의존성 확인: logback-classic 의존성이 추가되었는지 확인
  2. 로그 레벨 확인: logLevel 설정이 올바른지 확인
  3. 로그 설정 확인: logback.xml 또는 logback-spring.xml 설정 확인

키 관리 문제​

키가 반납되지 않음​

증상:

  • 다음 사용자가 무한정 대기함
  • 대기열이 진행되지 않음

해결 방법:

  1. returnKey 설정 확인: returnKey 설정이 올바른지 확인
  2. 타임아웃 확인: 세그먼트 타임아웃 설정 확인
  3. 서버 로그 확인: 서버 로그에서 키 반납 관련 오류 확인

디버깅 팁​

로그 확인​

디버깅을 위해 logLevel을 설정하여 로그를 확인할 수 있습니다:

import ch.qos.logback.classic.Level;

NetFunnelInitialize config = NetFunnelInitialize.Companion.builder()
    .clientId("{{CLIENT_ID}}")
    .secretKey("{{SECRET_KEY}}")
    .logLevel(Level.DEBUG)  // 디버깅 로그 활성화
    .build();

일반적인 확인 사항​

  1. 초기화 확인: NetFunnelInitialize가 올바르게 생성되었는지 확인
  2. Interceptor/Filter 등록: Interceptor/Filter가 올바르게 등록되었는지 확인
  3. 트리거 규칙: 콘솔에서 트리거 규칙이 올바르게 설정되었는지 확인
  4. 의존성 확인: 모든 필요한 의존성이 올바르게 추가되었는지 확인

관련 문서​