Go SDK
Go 서비스에서 직접 동기 이벤트 및 쿼리 호출을 수행하려면 telemetry-go를 사용하세요. 게시된 클라이언트는 각 메서드 호출에 대해 HTTP 요청을 생성합니다. 컨텍스트, 사용자 정의 http.Client, SDK 시간 초과, 자동 재시도, 일괄 처리 또는 플러시 대기열을 노출하지 않습니다.
설치 및 초기화
go get github.com/telemetry-sh/telemetry-go
import (
"os"
telemetry "github.com/telemetry-sh/telemetry-go"
)
telemetryClient := telemetry.NewTelemetry()
telemetryClient.Init(os.Getenv("TELEMETRY_API_KEY"))
애플리케이션 시작 중에 하나의 클라이언트를 초기화합니다. 수집에는 쓰기 범위 키를 사용하고 쿼리 전용 자동화에는 읽기 범위 키를 사용하세요.
구조화된 이벤트 보내기
event := map[string]interface{}{
"event_id": eventID,
"route_template": "/api/projects/:id",
"method": "POST",
"status_code": 201,
"status": "success",
"latency_ms": float64(time.Since(startedAt).Microseconds()) / 1000,
"request_id": requestID,
"release": os.Getenv("APP_RELEASE"),
}
response, err := telemetryClient.Log("api_request_completed", event)
if err != nil {
log.Printf("telemetry delivery failed event_id=%s error_type=transport_error", eventID)
}
_ = response
식별자, 헤더, 쿠키, 요청 본문, 자격 증명 또는 개인 고객 콘텐츠가 포함된 원시 요청 경로를 보내지 마세요. 정규화된 경로 패턴과 제어된 오류 범주를 사용합니다.
Go SDK는 Log 호출당 하나의 map[string]interface{}를 허용합니다. 애플리케이션 소유 작업자에게 대량 수집이 필요한 경우 HTTP 로그 API를 직접 사용하세요.
쿼리 실행
query := `
SELECT
route_template,
COUNT(*) AS requests
FROM api_request_completed
WHERE timestamp_utc >= now() - INTERVAL '24 hours'
GROUP BY route_template
ORDER BY requests DESC
`
result, err := telemetryClient.Query(query)
if err != nil {
return fmt.Errorf("query telemetry: %w", err)
}
rows, _ := result["data"].([]interface{})
fmt.Printf("rows=%d\n", len(rows))
응답은 일반 맵과 슬라이스를 사용합니다. 자동화에서 값을 사용하기 전에 유형, 누락된 필드, API 상태 및 빈 결과를 확인하세요. 대규모 JSON 또는 Parquet 내보내기에는 비동기 쿼리 API를 사용하세요.
프로덕션 운송 경계
현재 SDK는 시간 초과 없이 http.Client{}를 구성합니다. 따라서 중단된 네트워크 요청은 HTTP 핸들러 또는 작업자의 대기 시간 예산보다 오래 지속될 수 있습니다. 제한된 시간 초과, 컨텍스트 취소, 연결 풀 구성, 대량 페이로드 또는 명시적 상태 처리가 필요한 경우 서비스의 기존 http.Client에 Telemetry HTTP 계약을 래핑합니다.
동일한 이벤트 스키마 및 권한 부여 규칙을 유지하십시오.
client := &http.Client{Timeout: 2 * time.Second}
table 및 data를 포함하는 JSON 본문이 있는 POST https://api.telemetry.sh/log에 해당 클라이언트를 사용합니다. 응답을 디코딩하기 전에 HTTP 상태를 확인하세요.
재시도 및 중요 경로 정책
일시적인 연결 실패(429, 502, 503 및 504)만 재시도합니다. 지터를 사용하여 지수 백오프를 적용하고 경과 시간을 제한하고 동일한 event_id를 재사용합니다. 변경되지 않은 스키마나 요청 오류를 다시 시도하지 마세요.
일반적인 애플리케이션 분석의 경우 텔레메트리이 실패했기 때문에 완료된 고객 응답을 대체하지 마십시오. 내구성이 필요한 청구 또는 승인된 감사 이벤트의 경우 비즈니스 트랜잭션을 소유한 시스템에 보낸 편지함 기록을 유지하고 작업자로부터 전달합니다.
이벤트 전달 및 멱등성 및 배치 및 배압을 참조하세요.
통합 확인
합성 성공, 실패, 재시도 및 시간 초과 이벤트를 보낸 후 다음을 실행합니다.
SELECT timestamp_utc, event_id, route_template, status, latency_ms, error_type
FROM api_request_completed
ORDER BY timestamp_utc DESC
LIMIT 20;
테이블 이름, 필드 유형, 단위, 민감한 콘텐츠가 없는지 확인하세요. 트래픽이 많은 처리기에 계측을 연결하기 전에 프로세스 종료 및 정지된 Telemetry 요청을 테스트하세요.
문제 해결
- 초기화 오류: 첫 번째 메서드 호출 전에 서버 측 키가 비어 있지 않은지 확인하세요.
- 요청 중단: 시간 초과 및 요청 컨텍스트가 있는 클라이언트를 통해 HTTP API를 사용합니다.
- 비성공 응답은 데이터로 나타납니다. 반환된 상태 필드를 검사합니다. 현재 SDK는 HTTP 성공을 적용하지 않고 JSON 본체를 디코딩합니다.
- 스키마 거부: 필드 유형을 안정적으로 유지하고 null 또는 지원되지 않는 모양을 제거합니다.
- 재시도 후 중복 행:
event_id를 보존하고 중복 이벤트 레시피로 감사합니다.
Go HTTP 서버 구조적 로깅, 로그 API, 요청 속도 제한 및 API 오류를 계속 살펴보세요.