컨테이너 로그와 메트릭을 실시간으로 보여 주는 웹 앱 개발하기

## 버그와 차단 문제만 짚는 짧은 검토 쓰기 변경 요청 검토와 유지관리자 응답에는 극도로 간결한 방식을 사용하세요. 버그, 보안 문제, 차단 요인만 보고하세요. 짧은 글머리표를 사용하고, 관련이 있을 때 `file:line` 참조를 추가하며, 강점이나 요약 같은 섹션은 생략하고, 전체 응답을 약 10~15줄로 유지하세요. 인간 유지관리자처럼 작성하세요. em dash(—)나 en dash(–), 수사적인 “X가 아니라 Y” 대조, 본론에 앞선 의례적인 칭찬, 마지막 요약, 굵은 인라인 레이블, 내용 없는 유보 표현은 사용하지 마세요. 격의 없는 소문자 표기와 축약형은 허용됩니다. 결정을 밝히고 이유 하나만 제시한 뒤 멈추세요. ## 변경 요청의 빌드로 제보자가 수정을 먼저 시험하게 하기 보고된 문제가 진행 중인 변경 요청에서 수정되었다면 제보자에게 해당 요청용으로 빌드된 지속적 통합 산출물을 테스트해 달라고 요청하세요. `{registry}/{image}:change-{number}` 같은 일반 패턴을 사용해 미리 빌드된 이미지나 패키지의 정확한 참조를 제공하세요. 이렇게 하면 제보자가 다음 출시 전에 수정 사항을 검증할 수 있습니다. 이 경로를 권장하기 전에 자동화가 실제로 변경 요청마다 태그가 지정된 산출물 하나를 게시하는지 확인하세요. ## 수정 전에 백엔드와 프런트엔드의 계층 파악하기 시스템을 컴파일된 HTTP 백엔드와 타입이 지정된 단일 페이지 프런트엔드의 조합으로 취급하세요. 백엔드는 라우팅, 인증, 컨테이너 또는 워크로드 클라이언트, 실시간 로그 및 메트릭 스트림, 작업, 알림, 원격 에이전트 통신을 처리합니다. 프런트엔드는 파일 기반 뷰, 재사용 가능한 컴포넌트, 반응형 저장소, 스트림 컴포저블, 라우팅, 현지화, 사용자 환경설정을 처리합니다. 독립 실행형 또는 다중 호스트 서비스, 클러스터 오케스트레이션, 원격 에이전트 운영을 포함해 문서화된 각 배포 모드를 명시적으로 지원하세요. 하나의 클라이언트 구현에서 작동하는 변경 사항이 모든 백엔드에서 작동한다고 가정하지 마세요. 주요 의존성 방향을 명확하게 유지하세요. `HTTP handlers -> host service -> per-host service -> domain client -> runtime implementation` ## 문서에 정한 타깃으로 빌드하고 테스트하기 의존성을 설치하고 인증서, 스키마 또는 프로토콜 코드를 위한 생성 대상을 실행해 프로젝트를 설정하세요. 백엔드와 프런트엔드의 핫 리로드를 함께 조정하려면 전체 개발 작업을 사용하고, 문제를 분리할 때는 두 감시 프로세스를 별도로 실행하세요. 완전한 백엔드 빌드에 프런트엔드 자산을 포함하기 전에 먼저 프런트엔드 자산을 빌드하세요. 프런트엔드 배포본, 전체 애플리케이션, 배포 가능한 이미지의 빌드 대상을 구분하세요. 미리보기 대상을 사용해 운영 환경 방식의 빌드를 로컬에서 점검하세요. 문서화된 대상을 통해 백엔드 테스트, 프런트엔드 단위 테스트, 타입 검사, 브라우저 통합 테스트를 실행하세요. 타임스탬프에 민감한 프런트엔드 테스트에는 `TZ=UTC`를 사용하고, 감시 모드는 반복적인 로컬 작업 중에만 사용하세요. ## 백엔드 계층을 나누고 공통 클라이언트 인터페이스로 구현하기 HTTP 라우팅과 스트리밍 처리기는 호스트 및 클라이언트 서비스보다 상위 계층에 유지하세요. 런타임별 작업을 공유 도메인 클라이언트 인터페이스 뒤에 배치한 다음, 지원되는 각 컨테이너, 클러스터 또는 원격 에이전트 백엔드에 대해 해당 인터페이스를 구현하세요. 인증 제공자, 도메인 모델, 이벤트 분석, 알림 평가, 알림 전달을 전송 처리기와 분리하세요. 명령줄 분석과 다중 호스트 오케스트레이션은 처리기에 중복 구현하지 말고 지원 계층에 유지하세요. 새 워크로드 작업을 추가하려면 도메인 클라이언트 인터페이스, 적용 가능한 모든 런타임 구현, 호스트별 서비스 래퍼, 경로를 포함한 HTTP 처리기를 업데이트하세요. 한 배포 모드만 통과시키기 위해 계층을 우회하지 마세요. ## 프런트엔드 스토어와 로그 항목 유형을 정해진 역할대로 유지하기 경로 뷰, 자동으로 가져오는 컴포넌트, 반응형 저장소, 스트림 컴포저블, 애플리케이션 플러그인을 기존 역할에 유지하세요. 백엔드가 렌더링한 HTML을 통해 주입되는 구성은 변경 불가능한 것으로 취급하세요. 저장된 환경설정은 반응형 저장소 추상화 뒤에 유지하세요. 한 줄 텍스트, 구조화된 객체, 그룹화된 여러 줄 메시지를 서로 다른 로그 항목 타입으로 표현하세요. 유니온 타입을 반복해 정의하지 말고 공유 메시지 별칭을 사용하며, 각 이벤트에 맞는 타입을 선택하는 팩토리를 통해 항목을 생성하세요. 경로나 워크로드 변경 사이에서 재사용되는 컴포넌트는 파생 상태를 모두 새로 고쳐야 합니다. 차트가 마지막 막대만 변경해 업데이트를 최적화한다면 전체 재계산 메서드를 노출하고 전체 데이터 계열이 교체될 때 호출하세요. ## 로그와 메트릭 스트림의 정해진 한도 지키기 로그, 수명 주기 이벤트, 메트릭 스트림에는 서버 전송 이벤트를 사용하고, 대화형 연결 또는 실행 세션에는 WebSocket 연결을 사용하세요. 상태를 변경하는 워크로드 작업은 읽기 전용 스트림이 아니라 명시적인 HTTP 요청으로 전송하세요. 수신되는 프런트엔드 이벤트를 250밀리초 동안 버퍼링하되 늦어도 1,000밀리초 후에는 비우세요. 반응형 업데이트를 일괄 처리하고, 표시된 메시지가 400개를 초과하면 뷰어 계약에 따라 가장 오래된 항목을 교체하거나 표시하세요. 메트릭 기록은 최대 300개 항목의 이동 창으로 추적하세요. 알파 0.2의 지수 이동 평균으로 메트릭을 평활화하고, 허용된 코어 수 또는 호스트 코어 수로 CPU 값을 정규화하며, 메모리 비율 값과 절대값을 구분하세요. 차트는 사용 가능한 표시 너비에 맞게 다운샘플링하세요. 워크로드 전환처럼 전체 데이터 계열을 교체할 때는 일반적인 틱이 마지막 막대만 업데이트하더라도 전체 재계산을 실행해야 합니다. ## 로그인 방식과 배포 모드를 하나씩 따로 다루기 인증 없음, 로컬 파일, 정방향 프록시 인증을 별도의 모드로 지원하세요. 로컬 인증에는 만료되는 서명 토큰을 사용하고, 구성된 사용자 파일을 검증하며, 역할 기반 권한 부여를 신원 제공자와 독립적으로 유지하세요. 독립 실행형 모드에서는 재시도를 지원하는 관리자를 통해 로컬 및 원격 클라이언트를 결합하세요. 클러스터 모드에서는 오케스트레이션 API를 통해 노드를 검색하고 각 노드의 에이전트에 연결하세요. 클러스터 네이티브 모드에서는 해당 플랫폼의 API를 통해 동일한 도메인 클라이언트 인터페이스를 구현하세요. 원격 에이전트 모드에서는 인증서로 인증된 전송을 요구하세요. 모드 선택은 애플리케이션 진입점에 유지하세요. 적용 가능한 모든 모드에서 동작이 정의되거나 지원되지 않는 모드에서는 명시적으로 거부되기 전까지 해당 기능은 완성된 것이 아닙니다. ## 새 기능을 영향받는 모든 계층에 걸쳐 추가하기 새 HTTP 경로를 추가하려면 경로를 등록하고, 처리기를 구현하고, 호스트 서비스를 통해 대상을 확인한 뒤, 구조화된 데이터를 반환하거나 의도한 스트림을 설정하세요. 새 로그 뷰를 추가하려면 경로 뷰를 추가하고, 스트림 컴포저블을 만들고, 필터링된 API URL을 구성하고, 버퍼링을 관리하고, 반응형 메시지와 제어 기능을 반환하며, 기존 뷰어를 재사용하세요. 새 메트릭을 추가하려면 백엔드 통계 타입을 확장하고, 값을 추출하고 계산하고, 프로토콜 스키마를 업데이트하고, 프로토콜 코드를 다시 생성한 뒤, 인터페이스에 필요한 경우 프런트엔드 모델에 필드를 노출하세요. 기존 이벤트 스트림이 별도의 전송 경로 없이 업데이트를 전달해야 합니다. 새 알림 채널을 추가하려면 디스패처 인터페이스를 구현하고, 디스패처 팩토리에 등록하고, 구성 양식을 추가하며, 저장된 규칙과 경보 상태의 동작을 보존하세요. ## 원격 도구의 동시 실행을 제한하고 일시적 실패만 재시도하기 원격 디스패처가 구성되기 전에는 연결하지 마세요. 도구 검색과 호출에는 양방향 스트림을 사용하고, 하나의 레지스트리를 통해 호출을 디스패치하며, 가중 세마포어로 동시 실행을 5개로 제한하세요. 일시적인 실패에는 1~30초 범위의 지수 백오프와 지터를 사용해 다시 연결하세요. 잘못된 자격 증명이나 사용할 수 없는 요금제를 나타내는 권한 거부 응답에는 재시도를 영구적으로 중단하세요. 변경 불가능한 도구 정의를 한 번만 캐시해 원격 작업이 비활성화된 상태의 추가 부담을 무시할 수 있을 정도로 낮게 유지하세요. 도구를 추가하려면 이름, 설명, 매개변수 스키마를 정의하고, 응답 타입을 프로토콜 결과 유니온에 추가하고, 프로토콜 코드를 다시 생성하고, 디스패치 분기를 등록하고, 호스트 서비스 인터페이스 뒤에 구현하고, 집중된 테스트를 추가하세요. ## 로그 이벤트를 종류별로 나누고 메모리에 쌓지 않고 실시간 전달하기 다중화된 런타임 스트림의 헤더와 페이로드를 읽어 분석한 다음, 각 원시 이벤트를 구조화된 데이터, 그룹화된 여러 줄 이벤트 또는 한 줄 이벤트로 분류하세요. 명시적인 패턴으로 심각도를 추출하고, 도메인 이벤트를 직렬화해 실시간 스트림으로 전달하세요. 원격 에이전트의 경우 도메인 클라이언트 호출을 프로토콜 요청으로 변환하고, 로컬 런타임 클라이언트에 위임한 뒤, 응답을 다시 도메인 모델로 변환하세요. 로그, 메트릭, 수명 주기 이벤트의 스트리밍 동작을 보존하고 결과를 메모리에 무제한으로 수집하지 마세요. 수준, 쿼리 또는 정규식에 따른 필터링은 명확한 결과 제한을 유지해야 합니다. 워크로드 작업은 명시적인 활성화 게이트 뒤에 유지해야 합니다. ## 반복 가능한 테스트를 하고 실시간 연결을 보며 디버깅하기 경쟁 상태 탐지기를 사용해 백엔드 테스트를 실행하세요. 프로젝트의 어설션 라이브러리를 일관되게 사용하고, 프런트엔드 테스트를 UTC에서 실행하며, 필요한 서비스 설정을 갖추고 브라우저 통합 테스트를 실행하세요. 빌드 실패를 코드 결함으로 간주하기 전에 필요한 인증서와 프로토콜 산출물을 다시 생성하세요. 포함되지 않은 자산으로 개발할 때는 파일 시스템 제공과 조정된 핫 리로드를 활성화하세요. 백엔드 변경은 백엔드 감시 프로세스를 다시 시작해야 하고, 프런트엔드 변경은 전체 재시작 없이 모듈 교체를 사용해야 합니다. 디버깅할 때는 백엔드 디버그 로깅을 활성화하고, 브라우저 개발 도구로 프런트엔드 상태를 점검하며, 네트워크 패널에서 서버 전송 이벤트와 WebSocket 연결을 확인하세요. 생성된 파일과 자동 편집이 관련 없는 변경을 숨기지 않도록 최종 차이를 검토하세요.