이 가이드는 파이프라인 제어 게이트웨이와 관련된 일반적인 문제를 해결하는 데 도움이 됩니다. 문제는 증상별로 정리되어 있어 문제를 신속하게 파악하고 해결하는 데 도움이 됩니다.
설치 문제
사용자 기능 부족
문제: 조직 제품 관리자 및 조직 관리자와 관련된 필요한 권한이 없습니다.
증상:
- "에이전트 인증을 설정하는 데 필요한 조직 수준의 권한이 없습니다."라는 오류 메시지가 표시됩니다.
- 게이트웨이 설치 프로세스를 완료할 수 없습니다.
해결책:
- 계정 관리자에게 시스템 ID 생성에 필요한 권한이 포함된 역할을 부여받도록 요청하십시오.
- 자세한 내용은 사용자 권한 관련 문서를 참조하십시오.
구버전 Helm 차트
문제: 로컬에 설치된 Helm 버전이 오래되어 Helm 차트를 설치하는 명령줄 스크립트가 실패합니다.
증상:
- Helm 설치 스크립트가 버전 호환성 오류로 인해 실패합니다.
- Helm 업데이트가 필요함을 나타내는 오류 메시지
해결책:
- 설치 스크립트와의 호환성을 확보하려면 로컬 Helm 설치를 최신 버전으로 업데이트하십시오.
- 오류 메시지에 나와 있는 지침에 따라 Helm을 업그레이드하십시오.
데이터 전송 문제
이러한 문제는 데이터가 단말기 또는 텔레메트리 생산자에서 게이트웨이로, 또는 게이트웨이에서 뉴렐릭으로 흐르지 못할 때 발생합니다.
DNS 확인 실패
문제: DNS 확인 오류로 인해 에이전트가 게이트웨이에 연결할 수 없습니다.
증상:
- 에이전트가 게이트웨이 엔드포인트에 연결할 수 없습니다.
- 에이전트 로그의 연결 오류
해결책:
- (UI를 통해 또는 직접) 에이전트 로그에 액세스하여 연결 오류를 검색하세요.
- 전시 및 네트워크 토폴로지에 따라 DNS 설정을 조정하려면 네트워크 관리자에게 문의하세요.
- 자세한 내용은 에이전트 설명서를 참조하십시오.
SSL 인증서 문제
문제: 에이전트와 게이트웨이 사이의 SSL 인증 설정에 문제가 있습니다.
증상:
- 에이전트 로그의 SSL 연결 오류
- 인증서 유효성 검사 실패
- TLS 핸드셰이크 오류
해결책:
- SSL 연결 오류가 있는지 에이전트 로그를 확인하십시오.
- 인프라 및 네트워크 토폴로지를 고려하여 SSL 인증서가 올바르게 구성되고 유효한지 확인하십시오.
- 인증서 만료일과 인증서 체인을 확인하십시오.
- 자세한 내용은 DNS 및 인증서 설정을 참조하십시오.
게이트웨이 구성 오류
문제: 데이터가 게이트웨이에 도달했지만 뉴렐릭으로 게시되지 못했습니다.
증상:
- 게이트웨이가 에이전트로부터 데이터를 수신했지만 뉴렐릭에는 아무 것도 나타나지 않습니다.
- 시작되지 않거나 반복적으로 재시작됨
해결책:
- 게이트웨이에서 나가는 요청과 오류 발생 여부를 확인하세요.
- 실패한 규칙 지표를 검토하여 설정 문제 식별
- 시작되지 않는 파드의 로그를 검사하세요.
- 게이트웨이 설정이 올바른지 확인하고 모든 파드가 정상적으로 작동하는지 확인하십시오.
- 뉴렐릭 클러스터 키가 올바르게 구성되었는지 확인하세요.
지원되지 않는 텔레메트리 프로듀서 또는 프로토콜
문제: 지원되지 않는 API 또는 프로토콜에서 데이터가 전송되었습니다.
증상:
- 게이트웨이가
501상태 코드(구현되지 않음)를 반환합니다. - 성공적인 에이전트 연결에도 불구하고 뉴렐릭에 데이터가 표시되지 않습니다.
해결책:
- 뉴렐릭 지원 프로토콜(OTLP, 뉴렐릭 에이전트 프로토콜)과의 호환성 확인
- 지원되지 않는 프로토콜을 사용하는 경우, 기능 지원을 위한 요청을 제출하십시오.
- 임시 해결책으로 텔레메트리 프로듀서가 데이터를 뉴렐릭으로 직접 전송하도록 구성하십시오.
모든 데이터를 삭제하는 파괴적인 규칙
문제: 특정 규칙 때문에 모든 데이터가 삭제되어 뉴렐릭에 도달하지 못하고 있습니다.
증상:
- 규칙 구현 후 데이터가 뉴렐릭에 표시되지 않습니다.
- 드롭 데이터에서 높은 볼륨이 필터링되는 것을 확인할 수 있습니다.
해결책:
- 게이트웨이 모니터링 대시보드에서 드롭 데이터 메트릭을 확인하세요.
- 필터 및 샘플링 프로세서 설정을 검토하세요.
- 데이터 흐름을 허용하도록 파괴적인 규칙을 수정하거나 제거하십시오.
- 구현하다, 배포하기 전에 비운영 환경에서 규칙을 테스트합니다.
데이터 수집 후 데이터 누락
문제: 데이터 수집 후 뉴렐릭 백앤드에 데이터가 누락되었습니다.
증상:
- 텔레메트리 데이터의 공백
- 불완전한 트레이스 또는 로그 기록
해결책:
- 오류를 검토하고 클라이언트 측 타임아웃을 확인하십시오.
- 리소스 고갈 징후(CPU, 메모리, 네트워크)를 평가합니다.
- 플랫폼 문제에 대한 뉴렐릭 상태 확인
- 해당 기간 동안의 게이트웨이 로그를 검토하십시오.
데이터 수신 문제
이러한 문제는 게이트웨이가 실행 중이지만 텔레메트리 생산자로부터 데이터를 수신하지 못할 때 발생합니다.
텔레메트리 생성기 구성 오류
문제: 텔레메트리 생성기 구성 오류로 인해 게이트웨이로 텔레메트리 데이터가 전송되지 않습니다.
증상:
- 게이트웨이는 정상적으로 작동 중이지만 데이터를 수신하지 못하고 있습니다.
- 게이트웨이 모니터링 데이터가 존재하지만, 텔레메트리는 없습니다.
해결책:
- 설정 오류를 식별하기 위해 생산자 로그에 액세스
- 에이전트 또는 프로듀서에서 게이트웨이 엔드포인트 URL이 올바르게 구성되었는지 확인하십시오.
- 생산자 측에서 게이트웨이 포트에 접근 가능한지 확인하십시오.
- 올바른 설정 단계는 적절한 API, 에이전트 또는 텔레메트리 생산자 문서를 참조하세요.
- 지침은 수정 에이전트 설정을 참조하세요.
뉴렐릭으로부터의 속도 제한
문제: 텔레메트리 데이터의 속도 제한에 도달했습니다.
증상:
- 게이트웨이 HTTP 클라이언트가 뉴렐릭 API로부터 429 상태 코드를 수신했습니다.
- 계정에 속도 제한을 나타내는 이벤트가 생성되었습니다.
- 데이터가 간헐적으로 또는 지연되어 나타납니다.
해결책:
- 게이트웨이 HTTP 클라이언트 응답 코드에서 429 상태 코드를 확인하십시오.
- 계정에 생성된 이벤트 중 속도 제한 관련 이벤트를 검토하세요.
- 텔레메트리 데이터 속도 관리 및 조정에 대한 지침은 속도 제한 문서를 참조하세요.
- 데이터 용량을 줄이려면 샘플링 프로세서 사용을 고려하십시오.
성능 및 건강 문제
이러한 문제는 게이트웨이 성능, 리소스 활용도 및 데이터 지연 시간에 영향을 미칩니다.
자원 고갈
문제: 클러스터의 CPU 또는 메모리 리소스가 소진되었습니다.
증상:
- 게이트웨이 페이지에서 Cluster 비정상으로 표시됩니다.
- 파드가 시작되지 않거나 시작이 보류 중입니다.
- 파드 충돌 또는 재시작
- 로그에 나타나는 메모리 부족(OOM) 오류
해결책:
- Kubernetes UI 사용하여 파드 이벤트와 대기 중인 작업을 확인하고 리소스 제약 조건을 파악하세요.
- 노드 풀 크기를 늘리거나 리소스 제한(CPU 및 메모리) requests 조정하세요.
- cloud 공급자가 설정한 활성 노드 수 제한을 확인하고 필요에 따라 설정을 조정하십시오.
- 구현 및 배포 규모를 적절하게 조정하기 위한 규모 조정 및 확장 지침을 검토하세요.
데이터 도착 지연(SLA 이후 시간)
문제: 예상 시간 내에 데이터가 수신되지 않고 있습니다.
증상:
- 데이터가 뉴럴릭에 도착했지만 상당한 지연이 발생했습니다.
- 지연시간 지표가 높은 값을 보여줌
- 처리 대기열이 쌓이고 있습니다
해결책:
- 지연시간 지표를 확인하여 데이터 전송 지연 확인
- 게이트웨이 파드의 최소 개수를 늘려 처리 용량을 향상시키고 지연 시간을 줄이십시오.
- 자동 스케일링 설정을 검토하여 부하에 적절하게 반응하는지 확인하십시오.
- 데이터 양이 많은 시간대에 데이터 볼륨을 줄이기 위해 샘플링을 시행하는 것을 고려해 보세요.
모니터링 및 진단 문제
이러한 문제는 자체 모니터링 데이터를 뉴렐릭으로 보내는 게이트웨이의 기능에 영향을 미칩니다.
잘못된 라이선스 키입니다
문제: 게이트웨이가 유효하지 않은 라이선스 키로 구성되었거나 만료된 라이선스 키로 구성되어 있습니다.
증상:
- 뉴렐릭에 게이트웨이 모니터링 데이터가 나타나지 않습니다.
- 게이트웨이 로그에서 내부 모니터링 파이프라인 및 사용량 내보내기 관련 403 오류가 발생했습니다.
- 에이전트 데이터가 뉴렐릭에 성공적으로 도달했지만 게이트웨이 지수는 도달하지 못했습니다.
해결책:
- 게이트웨이 로그에 직접 액세스하여 문제를 확인하십시오. 내부 모니터링 파이프라인 및 사용량 내보내기 도구에서 발생하는 403 오류를 찾아보되, 에이전트 데이터에서는 찾지 마십시오.
- 라이선스 키가 유효하고 올바르게 구성되었는지 확인하십시오.
- 필요한 경우 게이트웨이 설정에서 키를 업데이트하세요.
- 라이선스 키를 업데이트한 후 게이트웨이를 다시 배포하십시오.
게이트웨이 모니터링 데이터에 영향을 미치는 클라우드 규칙
문제: 게이트웨이에서 생성된 링크가 cloud 규칙에 의해 의도치 않게 삭제되고 있습니다.
증상:
- 게이트웨이 모니터링 데이터가 처음에는 표시되지만 곧 사라집니다.
- 클라우드 규칙 사용 데이터에 따르면 게이트웨이 메트릭이 누락되고 있는 것으로 나타났습니다.
해결책:
- cloud 규칙의 사용량 데이터를 검토하여 의도치 않은 데이터 누락을 파악합니다.
- cloud 규칙 설정을 수정하여 게이트웨이 연결이 끊어지지 않도록 하세요.
- cloud 규칙에 적절한 조건을 설정하여 인프라 손실을 방지하십시오.
메트릭 API에 대한 속도 제한
문제: 해당 API 에 대한 요청 제한을 초과했을 수 있으며, 이로 인해 게이트웨이에서 보내는 후속 requests 429 응답 코드와 함께 실패할 수 있습니다.
증상:
- 게이트웨이 로그에 429 응답 코드가 있습니다.
- 게이트웨이 모니터링 데이터가 간헐적으로 나타납니다.
- 계정에서 이벤트 속도 제한을 설정합니다.
해결책:
- 계정에서 OpenTelemetry 메트릭 API와 관련된 속도 제한 이벤트를 확인하세요.
- 계정의 참조 카디널리티와 볼륨을 검토하세요.
- 요청 속도 관리 및 조정에 대한 지침은 속도 제한 관련 문서를 참조하십시오.
설정 및 구현, 배포 흐름 문제
이러한 문제는 게이트웨이 설정을 위한 파이프라인 UI 흐름 및 구현, 배포 프로세스에 영향을 미칩니다.
파이프라인 제어 UI 데이터가 표시되지 않음
문제: 파이프라인 위험 UI 에서 게이트웨이 데이터를 볼 수 없습니다.
증상:
- 게이트웨이가 작동 중이며 모델링 데이터를 뉴렐릭으로 보내고 있습니다.
- 파이프라인 컨트롤 UI 비어 있거나 게이트웨이 정보가 표시되지 않습니다.
- 게이트웨이 설정을 보거나 편집할 수 없습니다.
해결책:
- 파이프라인 취소 UI 의 계정 드롭다운 메뉴를 확인하여 올바른 계정이 선택되었는지 확인하세요.
- All accounts [모든 계정] 또는 게이트웨이 라이선스 키와 연결된 특정 계정을 보고 있는지 확인하십시오.
- 게이트웨이에서 사용하는 라이선스 키가 사용자 UI에 표시되는 계정과 일치하는지 확인하십시오.
설정 변경 사항이 적용되지 않습니다
문제: 사용자 UI 에서 게이트웨이 설정을 변경했지만 적용되지 않습니다.
증상:
- 파이프라인 구성 또는 프로세서 설정이 변경되었지만 데이터 처리는 변경되지 않았습니다.
- 예상되는 규칙은 데이터를 필터링하거나 변환하지 않습니다.
- UI에는 변경 사항이 나타나지만 게이트웨이 동작에는 나타나지 않습니다.
해결책:
- 파이프라인 UI 에서 보류 중인 구현, 배포에 대한 업데이트 페이지를 확인하세요.
- 변경사항은 명시적으로 구현될 때까지 단계적으로 진행되며, 플릿 취소/에이전트 제어를 통해 배포될 수 있음을 기억하세요.
- 보류 중인 구성 변경 사항을 게이트웨이 클러스터에 적용하려면 Deploy [배포]를 클릭하십시오.
- 구현 확인, 배포가 성공적으로 완료되고 새 설정으로 Pad가 다시 시작됩니다.
- 구현, 배포 중 설정 유효성 검사 오류에 대해 게이트웨이 패드 로그를 확인하세요.
설정 변경 사항이 사라졌습니다.
문제: 설정 변경 사항을 저장한 후 UI 에서 해당 내용이 사라집니다.
증상:
- 파이프라인이나 프로세서를 변경했는데 UI에 반영되지 않습니다.
- 업데이트 목록에 최근 수정 사항이 표시되지 않습니다.
- 변경 사항이 손실된 것 같습니다.
해결책:
- 여러 사용자가 동시에 게이트웨이 설정을 편집하고 있는지 확인하세요.
- API 경쟁 조건: 여러 사용자가 설정 업데이트를 동시에 전송할 경우, 변경 사항이 서로 덮어쓰여질 수 있습니다.
- 업데이트 페이지를 검토하여 실제로 저장된 변경 사항을 확인하세요.
- 팀원들과 협력하여 동일한 게이트웨이 설정을 동시에 수정하지 않도록 하십시오.
- 손실된 변경 사항을 다시 실행하세요
- 레이스 조건이 자주 발생하는 경우 뉴렐릭 지원팀 에 문의하십시오.
데이터 스키마 불일치
문제: 게이트웨이 수준에 해당 속성이 존재하지 않기 때문에 필터 또는 변환 프로세서가 예상대로 데이터를 일치시키거나 수정하지 못하고 있습니다.
증상:
- 필터 조건이 예상했던 데이터와 일치하지 않습니다.
- 변환문이 수정할 속성을 찾지 못합니다.
- 프로세서는 NRDB 데이터를 사용한 테스트에서는 작동하지만 게이트웨이에서는 작동하지 않습니다.
entity.guid,appName, 또는entityGuid와 같은 속성에는 접근할 수 없습니다.
해결책:
- NRDB에서 사용 가능한 속성이 데이터 보강 전에 게이트웨이에 존재하지 않을 수 있음을 이해하십시오.
- 게이트웨이 데이터 스키마 차이점을 검토하여 게이트웨이에서 사용할 수 없는 속성을 확인하십시오.
- 요원이나 수집기가 보낸 원시 텔레메트리에 존재하는 속성을 사용하세요.
- 속성 보강(예:
entity.guid또는appName)을 기반으로 필터링하려면 데이터 보강 후 처리하는 클라우드 규칙을 사용하는 것을 고려해 보세요. - 속성에 접근하기 위한 OTTL 구문이 올바른지 확인하십시오 (예:
attributes["key"]사용 vs. 필드 직접 접근).
ConfigMap 구현, 배포 오류
문제: Kubernetes ConfigMap이 오류로 업데이트되어 게이트웨이가 시작되지 않습니다.
증상:
- 게이트웨이 패드가 설정 구현 후 다시 시작되지 않음, 배포
- 파드는 CrashLoopBackOff 또는 Error 상태에 있습니다.
- 설정 변경을 푸시한 후 게이트웨이가 비정상 상태가 됩니다.
- 패드 로그에서 유효성 검사 오류 설정
해결책:
- Pad 상태를 확인하고 설정 오류가 있는지 확인하세요.bash$kubectl get pods -n newrelic$kubectl logs <pod-name> -n newrelic
- YAML 구문 오류 또는 잘못된 프로세서 설정을 찾아보세요.
- ConfigMap 콘텐츠가 예상 스키마와 일치하는지 확인합니다.bash$kubectl get configmap -n newrelic -o yaml
- 이전 정상 작동 설정으로 되돌리기:bash$kubectl rollout undo deployment/<deployment-name> -n newrelic
- 파이프라인 UI 또는 ConfigMap에서 직접 설정 오류 수정
- Re-구현하다, 배포하다 수정된 설정
- 수정 사항을 적용한 후 파드가 성공적으로 재시작되었는지 확인하십시오.
진단 명령
문제 해결, 게이트웨이 문제 해결 시 진단 정보를 수집하려면 다음 명령을 사용하십시오.
패드 상태 확인
$kubectl get pods -n newrelic패드 로그 보기
$kubectl logs <pod-name> -n newrelic파드 리소스 사용량을 확인하세요
$kubectl top pods -n newrelic파드이벤트 보기
$kubectl describe pod <pod-name> -n newrelic게이트웨이 설정 확인
$kubectl get configmap -n newrelic -o yaml구현, 배포 상태 확인
$kubectl rollout status deployment/<deployment-name> -n newrelic다음 단계
이 문제 해결, 해결 가이드를 따른 후에도 문제가 계속 발생하는 경우:
- 게이트웨이 설정 문서를 검토하여 구성을 확인하십시오.
- 적절한 리소스 할당을 보장하기 위해 크기 조정 및 확장 지침을 확인하십시오.
- 로드 밸런서를 사용 중인 경우 로드 밸런서 설정을 확인하십시오.
- 위 명령어를 통해 수집한 진단 정보를 가지고 뉴렐릭 지원팀에 문의하세요.