웹사이트 가동 시간 모니터링

하트비트는 성공 및 실패 확인을 모두 기록합니다. 이렇게 하면 중단이 표시되지만 모니터링 작업 자체가 데이터 전송을 중지하는 시기도 표시됩니다.

성공적인 검사, 두 개의 HTTP 503 오류 및 10분 사고가 포함된 웹 사이트 하트비트 타임라인 — 정기적인 확인을 통해 가동 중지 시간과 예상치 못한 침묵을 쿼리 가능한 이벤트로 전환합니다.

Telemetry SDK로 웹사이트를 확인할 때마다 하트비트를 보내세요. 그런 다음 실패한 확인과 데이터가 끊긴 구간을 조회하세요.

전제 조건

Telemetry에 대한 유효한 API 키
JavaScript 및 Node.js에 대한 기본 이해

1. Telemetry SDK를 설치합니다.

먼저 프로젝트에 Telemetry SDK를 설치해야 합니다. 아직 실행하지 않았다면 다음 명령을 실행하세요.

npm install telemetry-sh axios

2. Telemetry 초기화

Node.js 18 이상을 사용하세요. 스크립트를 실행하기 전에 서버 환경에 TELEMETRY_API_KEY를 설정하고 브라우저 코드에 키를 넣지 마세요.

import telemetry from "telemetry-sh";
import axios from "axios";

const apiKey = process.env.TELEMETRY_API_KEY;
if (!apiKey) throw new Error("Set TELEMETRY_API_KEY in server-side configuration");
telemetry.init(apiKey);

3. 하트비트 확인 만들기

가동 시간을 모니터링하려면 Telemetry 서비스에 주기적으로 핑을 보내는 하트비트 기능을 설정할 수 있습니다. 하트비트는 웹사이트의 상태를 기록하므로 웹사이트의 가용성을 모니터링할 수 있습니다.

다음은 하트비트 기능의 기본 예입니다.

const sendHeartbeat = async (url) => {
  const startedAt = performance.now();
  let heartbeat;

  try {
    const response = await axios.get(url, {
      timeout: 10_000,
      validateStatus: () => true,
    });
    const isOnline = response.status >= 200 && response.status < 400;
    heartbeat = {
      url,
      timestamp: new Date().toISOString(),
      status_code: response.status,
      status: isOnline ? "check_passed" : "http_error",
      is_online: isOnline,
      latency_ms: performance.now() - startedAt,
    };
  } catch {
    heartbeat = {
      url,
      timestamp: new Date().toISOString(),
      status_code: 0,
      status: "probe_error",
      is_online: false,
      error_type: "request_failed",
      latency_ms: performance.now() - startedAt,
    };
  }

  try {
    await telemetry.log("website_uptime", heartbeat);
  } catch {
    try { console.warn("Heartbeat export failed"); } catch {}
  }
  return heartbeat;
};

이 예제는 한 호스트에서 수행하는 기본 검사이며 운영 환경의 가용성을 보장하지 않습니다. 자격 증명이나 토큰이 없는 공개 URL만 사용하세요. HTTP 2xx/3xx는 이 예제의 검사 기준을 통과합니다. 시간 초과나 전송 실패는 탐지 실패이며 모든 사용자에게 사이트가 중단되었다는 증거는 아닙니다. Axios의 10초 시간 제한은 전체 처리의 엄격한 마감 시간이 아닙니다.

이벤트 전송은 별도로 기다리며 전송 실패가 HTTP 결과를 바꾸지 않습니다. 이 SDK에는 여기서 설정할 수 있는 전송 시간 제한이 없으므로 전송이 멈추면 이후 검사가 지연될 수 있습니다. 운영 환경에서는 애플리케이션이 관리하는 용량 제한 큐나 HTTP 클라이언트로 전송을 분리하고 검사기 자체도 독립적으로 감시하세요.

4. 하트비트 예약

검사를 즉시 시작하고 현재 검사와 전송이 끝난 뒤 다음 실행을 예약합니다:

const urlToMonitor = "https://example.com"; // Replace with a public URL.
const interval = 5 * 60 * 1000;

async function runHeartbeat() {
  try {
    await sendHeartbeat(urlToMonitor);
  } catch {
    try { console.warn("Heartbeat check failed"); } catch {}
  } finally {
    setTimeout(runHeartbeat, interval);
  }
}

void runHeartbeat();

이 스케줄러는 즉시 시작하고 한 번의 검사와 전송이 끝난 뒤 5분을 기다려 다음 실행을 시작합니다. 검사가 겹치지 않지만 실행 시각은 밀립니다. 고정 5분 주기나 영속 스케줄러가 아닙니다.

5. 쿼리 가동 시간

기록된 검사 중 HTTP 기준을 통과한 비율을 조회합니다:

const results = await telemetry.query(`
  SELECT
    url,
    COUNT(*) AS total_pings,
    SUM(CASE WHEN is_online THEN 1 ELSE 0 END) AS online_pings,
    (SUM(CASE WHEN is_online THEN 1 ELSE 0 END) * 100.0 / COUNT(*)) AS observed_check_success_percentage
  FROM
    website_uptime
  WHERE
    timestamp_utc >= now() - INTERVAL '30 days'
  GROUP BY
    url
`);

console.log(results);

이 쿼리는 관측된 검사 중 통과한 비율을 계산합니다. 누락된 예정 검사는 분모에 없으므로 실제 경과 시간에 따른 가동률이나 SLA가 아닙니다. 예정 검사 등록부와 독립적인 모니터로 관측 누락과 관측된 실패를 구분하세요.

6. Telemetry의 가동 시간 살펴보기

Telemetry의 UI를 사용하면 가동 시간 데이터를 대화형으로 시각화하고 탐색할 수 있습니다. Telemetry 대시보드를 방문하여 자격 증명으로 로그인하여 가동 시간 모니터링 데이터를 기반으로 대시보드, 차트 등을 만드세요.

다음 단계

가동 시간 비율은 실행이 중지된 모니터를 감지할 수 없습니다. 누락된 하트비트 레시피를 추가하고 최신 검사가 예상 일정보다 오래되고 약간의 유예 기간이 더해진 경우 알림합니다.

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