문서 찾아보기

가이드업데이트된 2026년 7월 28일Telemetry 편집 및 제품 팀의 검토4 최소 읽기

코딩 에이전트와 함께 이 문서를 사용하세요.

Claude Code, Codex, Cursor 또는 다른 코딩 에이전트에 대한 집중 프롬프트 팩을 연 다음 여기에서 다루는 워크플로에 맞게 조정하세요.

이 페이지에서

1. 실제 HTTP 결과 캡처
2. 대상 테이블 확인
3. 허용된 데이터 형태의 유효성을 검사합니다.
4. 타임스탬프 동작 확인
5. 스키마 호환성 검사
6. 대량 오류 격리
7. SQL로 이벤트 확인
예방 체크리스트

이벤트 수집 문제 해결

이벤트가 예상한 위치에 나타나지 않는 경우 별도의 요청 전달, 인증, 페이로드 유효성 검사, 스키마 호환성 및 쿼리 새로 고침이 필요합니다. 성공적인 애플리케이션 작업은 원격 분석 수집이 성공했음을 증명하지 않으며, 수락된 HTTP 요청은 이후 쿼리가 동일한 테이블 및 시간 범위를 보고 있음을 증명하지 않습니다.

진단하는 동안 고유한 안전 식별자가 있는 합성 이벤트를 사용하세요. 프로덕션 페이로드를 로그, 티켓 또는 명령 기록에 복사하지 마세요.

1. 실제 HTTP 결과 캡처

응답 상태와 본문을 볼 수 있도록 cURL을 사용하여 하나의 이벤트를 일시적으로 보냅니다.

curl -i -X POST https://api.telemetry.sh/log \
  -H "Content-Type: application/json" \
  -H "Authorization: $API_KEY" \
  -d '{
    "table": "ingestion_diagnostics",
    "data": {
      "event_id": "diagnostic-2026-07-28-01",
      "source": "manual_check",
      "status": "expected"
    }
  }'

API 키를 환경 변수에 유지하세요. 진단 정보를 수집하는 동안 페이로드에 붙여넣거나 인쇄하지 마세요.

재시도하기 전에 상태를 해석하세요.

400는 JSON, 테이블 이름, 타임스탬프, 데이터 형태 또는 필드 유형이 변경되어야 함을 의미합니다. 동일한 본체를 다시 시도하면 복구되지 않습니다.
401는 키가 누락되었거나, 형식이 잘못되었거나, 유효하지 않거나 취소되었음을 의미합니다.
403는 키에 작업에 대한 쓰기 범위가 없음을 의미합니다.
429는 현재 요청 속도 또는 할당량이 초과되었음을 의미합니다. 제공된 경우 Retry-After를 존중하고 지터가 있는 제한된 지수 백오프를 사용합니다.
5xx는 유효한 요청에 대한 서버 측 오류를 나타냅니다. 기본 애플리케이션을 무기한 차단하지 않고 제한된 횟수만큼 다시 시도하세요.

전체 클라이언트 정책을 보려면 비율 제한 및 API 오류를 읽어보세요.

2. 대상 테이블 확인

로그 API는 요청된 테이블 이름을 정규화합니다. 공백은 밑줄이 되고 문자는 소문자로 됩니다. 정규화 후에는 소문자 ASCII 문자, 숫자 및 밑줄만 유효합니다.

예를 들어, Checkout Events는 checkout_events가 됩니다. CheckoutEvents와 같이 추측된 이름을 쿼리하면 동일한 대상을 검사하지 않습니다.

진단 중에 요청에 간단하고 명시적인 이름을 사용한 다음 Telemetry에서 테이블 목록이나 스키마를 검사하세요. 두 서비스가 하나의 테이블에 써야 하는 경우 둘 다 동일한 정규화된 이름과 필드 유형을 사용해야 합니다.

3. 허용된 데이터 형태의 유효성을 검사합니다.

data 속성은 다음과 같습니다.

JSON 객체 1개
JSON 객체의 배열
객체로 디코딩되는 JSON 문자열
객체와 각각 객체로 디코딩되는 JSON 문자열을 포함하는 배열

최상위 숫자, 부울, null 및 해당 값으로 디코딩되는 문자열은 거부됩니다. 배열은 임의의 스칼라 값을 포함할 수 없습니다. 문서화된 제한을 초과하여 깊게 중첩된 페이로드도 거부됩니다.

실패한 이벤트를 3개의 무해한 필드로 줄입니다. 요청이 다시 실패할 때까지 필드를 소그룹으로 다시 추가하세요. 이렇게 하면 원래 고객 페이로드를 노출하지 않고 잘못된 형태를 격리할 수 있습니다.

4. 타임스탬프 동작 확인

Telemetry는 UTC timestamp가 누락되었거나 null인 경우 이를 추가합니다. Unix 타임스탬프 정수 및 숫자 문자열은 지원되는 범위 내에 있을 때 Unix 초로 해석되고 RFC 3339로 정규화됩니다. 클라이언트가 제공한 timestamp_utc는 해당 필드가 쿼리 계층에서 관리되므로 제거됩니다.

쿼리 창 외부에 새로운 이벤트가 나타나는 경우:

사용자 정의 timestamp를 제거하고 새로운 합성 이벤트를 보냅니다.
생성된 timestamp_utc에 의한 쿼리
애플리케이션 시계, 소스 타임스탬프 및 쿼리 시간대를 비교합니다.
원래 타임스탬프가 실수로 초가 아닌 밀리초인지 확인하세요.

소스 이벤트 시간을 수신 시간과 별도로 보존해야 하는 경우 타임스탬프 작업을 사용하세요.

5. 스키마 호환성 검사

처음으로 허용되는 이벤트는 필드 유형을 설정합니다. 새 선택적 필드를 추가하는 것은 기존 필드를 숫자에서 문자열, 부울, 타임스탬프 또는 중첩 객체로 변경하는 것과 다릅니다.

테이블 스키마를 검사하고 실패한 페이로드 필드를 필드별로 비교합니다. 일반적인 드리프트에는 다음이 포함됩니다.

한 프로듀서에 의해 정수로 전송된 식별자와 다른 프로듀서에 의해 문자열로 전송된 식별자
한 릴리스에서는 기간이 숫자로 전송되고 다른 릴리스에서는 "842ms"로 전송됩니다.
스칼라로 대체된 중첩 객체
정수 센트와 소수 통화 단위 사이에서 변화하는 화폐 가치
SDK가 열거형을 다르게 직렬화하기 때문에 상태 변경 유형

개념이 실제로 유형이나 단위를 변경하는 경우 버전이 지정된 필드 이름을 추가하고 쿼리를 의도적으로 마이그레이션하세요. 이벤트 데이터 유형 및 Null 허용 여부 및 스키마 진화를 읽어보세요.

6. 대량 오류 격리

거부된 배치의 경우 작은 합성 하위 집합으로 재현합니다. 필요한 경우 호환되지 않는 항목이 식별될 때까지 배치를 분할합니다. 중복 전송을 측정할 수 있도록 동일한 논리적 이벤트를 재시도하는 동안 안정적인 event_id를 유지합니다.

모든 네트워크 시도에 자동으로 새 식별자를 할당하지 마십시오. 이는 하나의 결과를 여러 행으로 변환하고 재시도 복구, 청구 총액 및 퍼널을 신뢰할 수 없게 만듭니다. 중복 이벤트 ID SQL 레시피를 사용하여 중복을 감사합니다.

7. SQL로 이벤트 확인

정확한 진단 식별자와 넉넉한 UTC 범위를 쿼리합니다.

SELECT
  event_id,
  source,
  status,
  timestamp_utc
FROM ingestion_diagnostics
WHERE event_id = 'diagnostic-2026-07-28-01'
  AND timestamp_utc >= now() - INTERVAL '24 hours'
ORDER BY timestamp_utc DESC;

행이 있지만 대시보드가 비어 있는 경우 대시보드의 테이블, 필터, 시간 범위 및 예상 필드 유형을 비교하세요. 전체 소스의 새로운 행이 표시되지 않으면 수집 신선도 레시피를 사용하여 간격을 표시합니다.

예방 체크리스트

서버 측 키를 브라우저 번들에서 제외하고 필요한 작업 범위로 지정하세요.
수집 실패에 대한 안전 상태, 엔드포인트, 요청 ID 및 오류 카테고리를 캡처합니다.
안정적인 테이블 이름, 이벤트 이름, 필드 유형 및 명시적 단위를 사용합니다.
프로덕션 전에 합성 또는 스테이징 검사를 통해 스키마 변경 사항을 보냅니다.
텔레메트리으로 작업자가 소진되거나 완료된 고객 응답을 변경할 수 없도록 재시도 제한
비즈니스 대시보드와 별도로 신선도 및 중복 식별자를 모니터링합니다.

정확한 정규화 규칙은 로그 API를 참조하고 보다 안전한 이벤트 계약 설계는 구조화된 로깅 가이드를 참조하세요.

소유권 및 기술 참조

이 설명은 Telemetry 편집팀의 소유입니다. 제품 팀은 동작, 예시, 경계를 검토합니다.

편집 기준 검토

OpenTelemetry 로그 데이터 모델