애플리케이션 Telemetry: 실용 가이드
애플리케이션 텔레메트리은 무슨 일이 일어났는지, 누구에게 발생했는지, 시간이 얼마나 걸렸는지, 결과가 유용한지 여부에 대해 소프트웨어가 생성하는 구조화된 증거입니다. 좋은 텔레메트리을 사용하면 무한한 텍스트에서 현실을 재구성하는 대신 제품, 엔지니어링, 지원 및 운영이 동일한 이벤트 계약의 질문에 답할 수 있습니다.
이 가이드에서는 올바른 신호를 선택하고, 안전한 결과 이벤트를 설계하고, 전달하고, SQL로 검증하고, 대시보드와 알림로 전환하는 방법을 보여줍니다.
유용한 애플리케이션 이벤트는 저장 및 SQL 분석을 통해 방출 경계에서 구조화됩니다.
애플리케이션 텔레메트리에 포함되는 내용
로그, 메트릭, 추적, 구조화된 이벤트는 겹치지만 각각에는 유용한 무게 중심이 있습니다.
| 신호 | 최고 | 일반적인 질문 |
|---|---|---|
| 구조화된 이벤트 | 지속적인 비즈니스 또는 애플리케이션 결과 | 가입 후 어떤 계정이 활성화되지 않았습니까? |
| 로그 | 상세한 진단 기록 | 이 프로세스는 한 번의 실패에 대해 무엇을 보고했습니까? |
| 미터법 | 저렴한 집계 추세 | 요청 볼륨이나 CPU가 변경됩니까? |
| 추적 | 분산 작업을 통한 인과 경로 | 어떤 범위로 인해 이 요청이 느려졌나요? |
하나의 신호가 다른 모든 신호를 대체하도록 강요하지 마십시오. 터미널 api_request_completed 이벤트는 오류율 대시보드에 필요한 경로, 계정, 상태, 기간 및 릴리스를 보유할 수 있습니다. 추적은 해당 기간을 소비한 종속성을 설명할 수 있습니다. 진단 로그는 검토된 기술 메시지를 보존할 수 있습니다. 인프라 메트릭은 서비스의 리소스가 제한되었는지 여부를 표시할 수 있습니다.
이러한 신호 간의 공유 식별자는 전체 페이로드를 복제하는 것보다 더 가치 있는 경우가 많습니다.
결정부터 시작하세요
계측은 질문과 작업으로 시작되어야 합니다.
- 질문: 출시 후 대부분의 계정에서 어떤 API 경로가 실패합니까?
- 결정: 롤백하거나, 기능을 비활성화하거나, 종속성을 조사합니다.
- 이벤트:
api_request_completed. - 그레인: 완료된 요청 1개.
- 차원: 경로 템플릿, 메서드, 상태 코드, 오류 범주, 릴리스.
- 측정: 대기 시간(밀리초).
- 안전한 상관 관계: 요청 및 계정 식별자.
알려진 필터, 그룹, 계산, 조인, 조사 또는 정책에서 필드를 사용하지 않는 경우 해당 필드를 그대로 두십시오. "나중에 유용할 수도 있습니다"는 유용한 답변을 보장하지 않고 비용, 개인 정보 보호 위험 및 불안정한 스키마를 생성합니다.
하나의 이벤트 계약을 디자인하세요
터미널 요청 이벤트는 다음과 같습니다.
{
"event_id": "evt_api_01",
"request_id": "req_2f71",
"account_id": "acct_8f31",
"route": "/v1/query/:id",
"method": "POST",
"status_code": 200,
"latency_ms": 184,
"error_type": null,
"release": "2026.07.3"
}
계약서에는 다음 사항이 명시되어야 합니다.
| 재산 | 정의 |
|---|---|
| 이벤트 이름 | api_request_completed와 같은 안정적인 과거 시제 결과 |
| 곡물 | 한 행이 정확히 무엇을 나타내는지 |
| 경계 방출 | 결과가 최종인 이후의 애플리케이션 상태 변경 |
| 소유자 | 제작자를 담당하는 팀 또는 서비스 |
| 필수 입력사항 | 허용되는 모든 행에 있어야 하는 값 |
| 제어된 값 | 허용되는 상태, 범주, 방법 또는 버전 |
| 단위 | _ms, _bytes, _usd 또는 다른 명시적 접미사 |
| 개인 정보 보호 수업 | 민감하지 않거나 가명이거나 검토가 필요함 |
| 보존 필요성 | 결정에 데이터가 필요한 기간 |
모든 식별자를 새로운 차원으로 바꾸는 원시 URL이 아닌 /v1/query/:id와 같은 경로 템플릿을 사용하십시오. 스택 추적이 아닌 제한된 error_type를 사용하십시오. 숫자 측정값을 숫자로 유지하고 안정적인 식별자를 문자열 형식으로 유지합니다.
결과 경계에서 방출
결과가 알려진 경우에만 결과를 기록하십시오. HTTP 요청의 경우 일반적으로 최종 상태 및 기간을 사용할 수 있는 이후입니다.
import telemetry from "telemetry-sh";
telemetry.init("YOUR_API_KEY");
async function recordRequest(context, response, startedAtMs) {
await telemetry.log("api_request_completed", {
event_id: crypto.randomUUID(),
request_id: context.requestId,
account_id: context.accountId,
route: context.routeTemplate,
method: context.method,
status_code: response.status,
latency_ms: Date.now() - startedAtMs,
error_type: response.error
? classifyRequestError(response.error)
: null,
release: process.env.APP_RELEASE ?? "unknown"
});
}
Telemetry는 정규화 중에 null 값을 제거하므로 성공적인 행에는 error_type가 저장되지 않습니다. 쿼리 계층은 timestamp_utc를 제공합니다. 해당 이름을 가진 클라이언트 제공 필드가 제거됩니다. 정확한 허용되는 모양과 정규화 규칙은 로그 API를 참조하세요.
텔레메트리 전달 실패로 인해 완료된 비즈니스 결과가 중복된 결제, 이메일, 작업 또는 요청으로 변경되지 않도록 하세요. 워크플로의 위험에 따라 버퍼링, 재시도, 샘플링 또는 삭제 여부를 결정합니다. 동일한 논리 이벤트 전달을 재시도할 때 동일한 event_id를 재사용합니다.
상관 관계에 대한 식별자 선택
조사 중인 엔터티와 일치하는 식별자를 사용하세요.
event_id는 하나의 텔레메트리 이벤트를 중복 제거합니다.request_id는 하나의 요청에 대한 애플리케이션 증거를 연결합니다.job_id는 수명 주기 이벤트와 재시도를 연결합니다.account_id는 고객 영향을 측정합니다.user_id는 승인 시 행위자 수준의 제품 분석을 지원합니다.trace_id는 분산 추적에 연결됩니다.
식별자를 가명으로 유지하세요. 이메일 주소, 액세스 토큰, 세션 쿠키, 프롬프트, 문서 또는 전체 URL은 편리한 식별자가 아닙니다. 민감한 페이로드 데이터입니다.
카디널리티 및 페이로드 크기 제어
카디널리티는 필드가 생성하는 고유 값의 수입니다. 높은 카디널리티 ID는 조사 및 조인에 유용하지만 기본 대시보드 그룹에는 적합하지 않습니다. 경계가 없는 텍스트는 안전한 분석 차원이 아닙니다.
사용:
/v1/query/9be1...대신route: "/v1/query/:id";- 예외 메시지 대신
error_type: "upstream_timeout"; - 임시 디스플레이 라벨 대신 승인된 공급자 모델 식별자;
- 전체 배포 매니페스트 대신
release: "2026.07.3".
제한된 필드에 그룹화합니다. 제한된 조사 결과에서만 식별자를 선택하세요. 수집 후 가능한 모든 민감한 값을 수정하려고 시도하는 대신 요청 및 응답 본문을 생략하세요.
유형과 의미를 안정적으로 유지
이벤트 유연성은 혼합 유형을 전송하는 이유가 아닙니다. latency_ms는 184, "184 ms" 및 "slow"를 번갈아 사용하면 안 됩니다. account_id는 한 서비스의 사용자와 다른 서비스의 조직을 참조해서는 안 됩니다.
추가 옵션 필드는 일반적으로 가장 안전한 진화입니다. 이름 바꾸기, 단위 변경, 유형 변경 또는 새 행 그레인에는 마이그레이션이나 새 이벤트 버전이 필요합니다. 대시보드나 알림을 변경하기 전에 스키마 진화 가이드를 따르고 릴리스별 현장 채택을 측정하세요.
중첩된 개체는 유용한 네임스페이스를 만들 수 있지만 점으로 구분된 모든 경로는 여전히 계약입니다. 중첩된 JSON 쿼리를 참조하세요.
이벤트 시간과 수집 시간을 분리함
비즈니스 또는 애플리케이션 결과가 발생한 시기를 정의합니다. 지연된 모바일 클라이언트, 큐, 오프라인 에이전트 및 재시도 버퍼는 해당 순간보다 늦게 전달될 수 있습니다.
서버에서 생성된 온라인 이벤트의 경우 Telemetry의 관리형 timestamp_utc가 올바른 운영 쿼리 시간인 경우가 많습니다. 워크플로에 소스 이벤트 시간이 필요한 경우 별도로 명명된 시간대 한정 타임스탬프를 보내고 지연 도착이 보고서에 미치는 영향을 문서화합니다. 부분적인 현재 버킷을 완전한 과거 버킷과 비교하지 마십시오.
타임스탬프 작업 가이드에서는 UTC, 창 및 늦게 도착하는 데이터를 다룹니다.
첫 번째 유용한 질문 쿼리
제한된 샘플로 시작하십시오.
SELECT
timestamp_utc,
route,
status_code,
latency_ms,
release
FROM api_request_completed
WHERE timestamp_utc >= now() - INTERVAL '1 hour'
ORDER BY timestamp_utc DESC
LIMIT 100;
그런 다음 볼륨, 오류율, 영향을 받은 계정 및 꼬리 지연 시간을 계산합니다.
SELECT
route,
COUNT(*) AS requests,
SUM(CASE WHEN status_code >= 500 THEN 1 ELSE 0 END) AS errors,
COUNT(DISTINCT CASE
WHEN status_code >= 500 THEN account_id
END) AS affected_accounts,
100.0 * SUM(CASE WHEN status_code >= 500 THEN 1 ELSE 0 END)
/ NULLIF(COUNT(*), 0) AS error_rate_pct,
approx_percentile_cont(latency_ms, 0.95) AS p95_latency_ms
FROM api_request_completed
WHERE timestamp_utc >= now() - INTERVAL '24 hours'
GROUP BY route
HAVING COUNT(*) >= 20
ORDER BY affected_accounts DESC, error_rate_pct DESC;
최소 볼륨 규칙은 단일 오류가 바쁜 회귀보다 자동으로 순위가 높아지는 것을 방지합니다. 중요한 소량 작업 흐름에는 일반 순위표가 아닌 자체 알림이 필요할 수 있습니다.
의사결정이 가능한 대시보드 구축
애플리케이션 안정성 대시보드를 통해 독자는 탐지부터 범위 및 증거까지 이동할 수 있습니다.
- 요청 또는 워크플로 볼륨
- 전체 시간 버킷에 대한 성공 또는 오류율;
- p50 및 p95 대기 시간;
- 영향을 받은 계정
- 경로, 오류 범주 및 릴리스별 분석
- 조사를 위한 요청 ID가 있는 제한된 테이블입니다.
단위, 시간 범위, 분모, 최소 볼륨, 데이터 최신성 및 이벤트 계약에 주석을 답니다. 검토자가 쿼리가 반환하려는 내용을 알 수 있도록 중요한 SQL 옆에 합성 결과나 알려진 고정 장치를 보관하세요.
API 신뢰성 대시보드 예시 및 API 지연 시간 레시피를 완전한 시작점으로 사용하세요.
소유자가 응답할 수 있는 경우에만 알림
알림 정의에는 쿼리, 정확한 분모, 전체 기간, 임계값 또는 기준, 최소 볼륨, 소유 팀, 런북, 첫 번째 진단 분석 및 누락된 데이터에 대한 동작이 필요합니다.
예를 들어 p95 대기 시간이 3개의 완전한 버킷에 대한 경로 목표를 초과하고 최소 100개의 요청이 관찰되면 API 소유자에게 알립니다. 응답은 릴리스, 오류 카테고리 및 영향을 받는 계정 수를 비교하는 것으로 시작됩니다.
원격 분석 파이프라인 자체를 모니터링합니다. 플랫 0은 조용한 애플리케이션, 손상된 프로듀서, 배달 실패 또는 쿼리 오류를 의미할 수 있습니다. 텔레메트리 전달 이벤트 스키마 및 수집 신선도 레시피는 누락된 증거를 표시합니다.
개인정보 보호 및 보안
결정에 필요한 최소한의 증거를 수집합니다. 출시 전:
- 모든 식별자와 자유 텍스트 필드를 분류합니다.
- 비밀, 자격 증명, 쿠키, 요청 본문, 프롬프트 및 생성된 콘텐츠를 제거합니다.
- 가명 내부 ID를 사용합니다.
- 행위자 또는 리소스 식별자를 노출하는 조사 보기를 제한합니다.
- 문서화된 운영 또는 제품 요구 사항에 따라 보존을 설정합니다.
- 성공적인 요청뿐만 아니라 수정 및 실패 분기를 테스트합니다.
- 데이터의 관할권 및 사용에 대한 삭제 및 액세스 요구 사항을 검토합니다.
페이로드를 확장하기 전에 민감한 데이터 수정 및 보안 개요를 읽어보세요.
전체 경로 검증
프로듀서 단위 테스트는 필요하지만 충분하지는 않습니다. 검증:
- 성공, 실패, 시간 초과, 재시도 및 중복 분기;
- 필드 이름, 유형, 단위 및 제어된 값
- API 수용 및 오류 처리;
- 대상 테이블의 최근 원시 행
- 알려진 고정물에 대한 집계 SQL;
- 대시보드의 기간 및 분모
- 알림의 임계값, 소유자 및 누락된 데이터 동작
- 이전 프로듀서 버전의 롤백 경로.
배포 후 릴리스별로 현장 적용 범위 및 이벤트 볼륨을 추적합니다. 소스에 존재하는 코드 경로는 프로덕션이 완료 이벤트를 내보내고 있음을 증명하지 않습니다.
결과 손실 없이 비용 제어
광범위한 출시 전 예상 수량:
events per day
= requests per day
× events per request
× retained sample fraction
중간 상태가 사용되지 않는 경우 여러 중복 진행 이벤트보다 하나의 최종 결과 이벤트를 선호합니다. 요율에 필요한 분모를 보존한 후에만 대량의 성공적인 진단을 샘플링합니다. 정책이 허용하는 경우 실패 및 드물게 발생하는 중요한 결과를 유지하되 민감한 데이터를 제거하는 대신 샘플링을 사용하지 마십시오.
문서화된 소유자가 있는 가장 긴 비교 또는 조사 기간에 보존 기간을 맞춥니다. 아무도 쿼리하지 않는 필드나 이벤트는 영구적인 비용이 되기 전에 계획에서 제거되어야 합니다.
애플리케이션 텔레메트리 롤아웃 체크리스트
- 질문, 결정, 소유자 및 예상 응답을 작성합니다.
- 한 행의 세부 사항과 정확한 결과 경계를 정의합니다.
- 필수 필드, 제어된 값, 단위 및 안전한 식별자를 선택합니다.
- 개인 정보 보호, 카디널리티, 보존 및 볼륨을 분류합니다.
- 대표적인 성공, 실패, 재시도, 복제 및 롤백 픽스처를 추가합니다.
- 비즈니스 운영 의미를 변경하지 않고 도구를 제공합니다.
- 릴리스별로 허용되는 행과 필수 필드 적용 범위를 확인하세요.
- 알려진 결과에 대해 SQL을 테스트합니다.
- 대시보드 정의, 최신성 및 분모를 게시합니다.
- 소유자와 응답이 명확한 경우에만 알림을 추가하세요.
- 원격 분석 파이프라인 자체를 모니터링합니다.
- 첫 번째 보존 기간 이후 필드를 검토하고 사용하지 않는 데이터를 제거합니다.
이벤트 스키마 설계, 구조적 로깅, 이벤트 스키마 카탈로그 및 엔드 투 엔드 SaaS 옵저버빌리티 데모를 계속 진행하세요.