SDK 문제 해결 및 디버깅

데이터 검증은 계측 프로세스에서 중요한 단계입니다. Amplitude는 디버깅을 간소화하고 프로젝트의 원활한 구현을 지원하는 도구를 제공합니다.

다음 섹션에서는 일반적인 문제와 그 해결책에 대해 설명합니다.

Amplitude에 표시되지 않는 이벤트

어떠한 이벤트도 수집할 수 없는 경우 다음 사항을 확인하십시오.

• 올바른 API 키를 사용하고 있습니까? init() 중에 API 키를 올바르게 설정했는지 확인하십시오. EU에서 데이터 상주를 활성화한 경우 https://analytics.eu.amplitude.com/에서 API 키를 검색하십시오. 데이터 지역성 규정은 API 세부 정보를 거기에 저장합니다.

• 여러 인스턴스를 사용하고 있습니까? 올바른 인스턴스를 사용하고 있는지 확인하십시오. 여러 SDK 버전이 충돌할 수 있습니다. 충돌을 방지하려면 각 인스턴스에 다른 이름을 지정하십시오. 최신 SDK의 경우 개별 변수를 생성하여 각기 다른 방식으로 인스턴스화해야 할 수도 있습니다.

• Amplitude 데이터를 사용하고 계십니까? Amplitude 데이터를 사용하는 경우 이벤트가 차단되지 않았는지 확인하십시오.

• 유효 userId 및 deviceId 값을 설정하고 있습니까? deviceId 또는 userId가 유효한지 확인하십시오. 잘못된 값은 400 오류를 일으킬 수 있습니다. 자세한 내용은 장치 ID 및 사용자 ID 최소 길이를 참조하십시오.

• flushQueueSize 또는 flushIntervalMillis를 눌렀나요? 기본적으로 SDK는 이벤트를 대기열에 넣고 일괄 처리로 전송하므로 이벤트가 서버에 즉시 도달하지는 않습니다. 정확한 값은 플랫폼에 따라 다릅니다. 이벤트가 서버에 도달할 때까지 기다린 후 차트에서 해당 이벤트를 확인하십시오.

엔드포인트 제한 및 스로틀링

Amplitude는 트래픽 급증으로부터 플랫폼을 보호하기 위해 엔드포인트 제한을 적용합니다. 이러한 제한을 이해하면 속도 제한 시나리오를 효과적으로 처리하는 데 도움이 됩니다.

엔드포인트 제한

Amplitude는 각 엔드포인트가 초당 처리할 수 있는 이벤트 수에 대한 제한을 설정합니다:

• 기본 제한: 초당 프로젝트당 100,000개의 이벤트(각 엔드포인트에 대해 별도로 계산됨).
• 그룹 식별 엔드포인트: 조직당 초당 10,000개의 이벤트.
• SDK 엔드포인트: 프로젝트당 초당 150,000개의 이벤트.
• HTTP API 및 HTTP API v2: 프로젝트당 초당 50,000개 이벤트.

이 제한을 초과하면 Amplitude는 HTTP 429 상태 코드를 반환합니다. 이벤트를 다시 전송하기 전에 60초 동안 기다리십시오.

일반 스로틀링

또한 Amplitude는 조직 전체에서 사용자 또는 장치당 초당 30개 이벤트의 스로틀링 제한을 적용합니다. 이 제한은 SDK 엔드포인트를 포함한 모든 엔드포인트에 적용되며 개별 사용자나 장치의 과도한 이벤트 볼륨으로부터 보호합니다.

이 제한을 초과하면 Amplitude는 이벤트를 조절하고 경고를 기록합니다. 이벤트 트래킹을 시간에 걸쳐 분산하거나 이벤트 호출 빈도를 줄여 이 한도 내로 유지하십시오.

개인정보 보호

이미 IP를 비활성화한 경우에도 최신 SDK를 사용할 때 사용자 조회에서 해당 IP를 계속 볼 수 있습니다. Amplitude는 데이터를 HTTP API로 전송합니다(유지 관리 SDK의 경우 HTTP API V1, 최신 SDK의 경우 HTTP API V2). 도중에 IP 주소를 비활성화한 경우, Amplitude가 사용자의 이전 IP 주소를 백엔드에 불러오기 했을 수 있습니다. 백엔드는 데이터베이스에 불러오기 된 IP를 검색합니다(있는 경우). 테스트 사용자에게는 이 방법이 일반적으로 괜찮습니다. IP를 비활성화한 후에는 새 사용자에게 영향을 주지 않습니다. 이 문제가 모든 사용자에게 영향을 미치는 경우 새 작업 공간을 생성하십시오.

Client Event Time 예기치 않은 값을 표시합니다

Client Event Time 는 디바이스가 이벤트를 기록한 시점의 로컬 타임스탬프(UTC)입니다. 다양한 Amplitude 타임스탬프에 대한 설명은 원시 데이터 필드를 참조하십시오.

• Client Event Time 미래의 시간을 표시합니다 client_upload_time가 미래의 시간을 표시하는 경우 이 섹션을 확인하십시오. 고객의 장치가 client_upload_time를 결정합니다. 고객의 시계가 잘못 설정되어 있을 경우 이 값은 미래 시간으로 표시될 수 있습니다. 최신 SDK를 사용하는 경우 Enrichment 플러그인을 통해 이벤트 페이로드에서 시간을 제거할 수 있습니다. Enrichment 플러그인은 SDK가 고객의 기기 클럭을 사용하지 못하도록 방지하고 대신 server_upload_time에 의존합니다. 이 접근법에는 단점이 있습니다. 이벤트가 즉시 업로드되지 않을 경우 기록된 이벤트 시간이 원래 이벤트 시간과 상당히 다를 수 있습니다.

• Client Event Time은(는) Client Upload Time와(과) 다릅니다. Client Event Time Client Upload Time와는 다를 수 있습니다. 고성능 환경을 지원하기 위해 SDK는 이벤트를 일괄 처리로 전송합니다. SDK는 track 메서드에 의해 기록된 모든 이벤트를 클라이언트 측 대기열에 넣습니다. SDK는 flushQueueSize또는 flushIntervalMillis중 하나가 먼저 정의된 값을 충족할 때 이벤트를 일괄 처리하고 플러시합니다. 따라서 SDK는 이벤트를 추적하여 나중에 업로드할 수 있습니다. 이벤트를 더 자주 전송하려면 수동으로 조정 flushQueueSize 및flushIntervalMillis/또는 호출하십시오.flush()

장치 제품군이 적절하지 않습니다.

• 웹의 경우, Amplitude는 @amplitude/analytics-browser@^2.0를 제외하고 Navigator.userAgent 정보를 구문 분석하기 위해 타사 라이브러리를 사용합니다. 부적절한 장치 제품군을 발견한 경우 먼저 Navigator.userAgent의 값이 예상치와 일치하는지 확인하십시오. Chrome 110부터는 Chrome이 Android 버전 및 기기 모델에 대해 고정된 값을 사용합니다. Chrome의 사용자 에이전트 감소는 기기 정보에 영향을 줄 수 있습니다.

• 모바일 SDK의 경우 Amplitude는 서버 장치 매핑에 의존합니다. Amplitude는 Google의 지원되는 기기 목록과 Android용 Android 스마트폰 목록, iOS용 태블릿 컴퓨터 비교를 참조합니다. 이러한 소스 전체 중 어느 곳에도 나타나지 않는 부적절한 장치 제품군을 발견하면 티켓을 제출하십시오.

user_properties지연된 identify 호출이 나타나는 것을 통해

요청에 deviceId이(가) 포함되어 있지 않거나 배치 API를 거치지 않는 경우 경합 상태가 발생할 수 있습니다. Amplitude 백엔드는 파티션 논리를 사용합니다. 동일한 deviceId가 없거나 배치 API를 사용하지 않을 경우 두 호출이 별도의 버킷에 포함될 수 있습니다. Amplitude는 서로 다른 버킷과 큐에 걸친 처리 시간을 보장할 수 없습니다. identify 호출 및 track 호출의 순서를 유지하려면 배치 API를 통해 동일한 deviceId를 포함한 호출을 전송하십시오.

요청 수를 줄이기 위해 최신 모바일 SDK는 특정 ID 업데이트를 대기열에 넣고 통합합니다. SDK는 track()를 통해 전송되는 다음 비식별 이벤트와 함께 이를 전송하기 위해 기다립니다. 사용자 속성을 즉시 업데이트하려면 flush()를 호출하십시오.

이벤트 회가 매우 부정확함

특정 사용자의 세션에서 부정확한 이벤트 회가 리포트되는 경우(예: 미래 또는 과거 수백 년), 가장 가능성이 높은 원인은 다음과 같습니다.

• 최종 사용자의 비정상적인 구성으로 인해 장치가 잘못된 날짜로 설정되었습니다.
• 최종 사용자의 브라우저 확장 프로그램으로 인해 시간 보고가 부정확합니다.

이러한 문제는 인스트루멘테이션에 오류가 있음을 나타내는 것이 아닙니다.