컨텐츠로 건너뛰기
레시피 생태계 소스 코드 문서

원격 서버 트러블슈팅

운영 서버가 문제를 일으킬 때, 몇 시간이 아니라 몇 분 안에 진단이 필요합니다. OpenCode는 관련 로그를 읽고, 최근 변경과 교차 참조하며, 여러분이 서버 통제권을 유지하는 동안 수정을 제안할 수 있습니다.

이 레시피를 사용하는 경우

  • 서비스가 가동 중이지만 느리거나, 오류를 발생시키거나, 간헐적으로 5xx를 반환할 때
  • 로그가 크고 어떤 서브시스템이 원인인지 모를 때
  • 수정 작업이 필요하지만 무엇이든 재시작하기 전에 두 번째 의견이 필요할 때

사전 준비

  • 로컬 머신에 설치된 OpenCode
  • 영향을 받는 서버에 대한 SSH 접근
  • 관련 로그 및 설정 파일에 대한 읽기 전용 접근

단계

  1. 증상을 정확히 정의

    한 문단으로 무엇이 잘못되었는지, 언제 시작되었는지, 이미 무엇을 배제했는지 서술하세요.

    오늘 14:00 UTC 이후로 checkout 서비스가 약 3%의 요청에 대해 504를 반환하고 있습니다. 지연 시간 p99가 800ms에서 6초로 증가했습니다. 지난 6시간 동안 배포는 없었습니다. 앱 노드의 CPU와 메모리는 정상입니다. 아직 아무것도 재시작하지 않았습니다.

  2. 관련 로그 가져오기

    OpenCode에게 로그의 적절한 부분을 가져오고 이상을 드러내달라고 요청하세요.

    prod-app 클러스터에 SSH 접속하세요 (자격 증명은 1Password에 있음). checkout 서비스의 stdout과 stderr 최근 2시간 분량을 가져오세요. 에러 패턴, 스택 트레이스, 비정상적인 지연 시간 급증을 드러내세요. 정상 트래픽은 포함하지 마세요.

  3. 최근 변경과 상관 관계 파악

    배포가 없었더라도 인프라 변경은 여전히 중요할 수 있습니다.

    지난 24시간 동안의 인프라 변경(Terraform, ingress, DNS)을 확인하세요. 각 변경을 지연 시간 증가의 시점과 교차 참조하세요.

  4. 가설 형성

    OpenCode에게 가장 가능성 높은 원인과 검증 방법을 제안해 달라고 요청하세요.

    로그와 인프라 변경을 바탕으로, 지연 시간 증가의 상위 3개 가설 순위 목록을 제공하세요. 각각에 대해 뒷받침하는 증거와 확인 또는 배제할 수 있는 하나의 명령어를 알려주세요.

  5. 방해 없이 검증

    항상 가장 영향이 적은 검증 경로를 먼저 사용하세요. 재시작으로 바로 점프하지 마세요.

    # 예시: 다운스트림이 타임아웃하는지 확인
curl -w '%{time_total}\n' -o /dev/null -s https://internal.api/ping

  6. 가장 작고 안전한 수정 적용

    검증되면 문제를 해결하는 가장 작은 변경을 만드세요. 수정이 위험하다면 먼저 팀원에게 제안하세요.

    가설 #2가 이제 확인되었다고 가정할 때, 가장 작고 안전한 변경을 제안하세요. 정확한 명령어, 다음 10분 동안 모니터링할 항목, 롤백 계획을 알려주세요.

  7. 사후 인시던트 노트 작성

    작은 인시던트라 할지라도 무슨 일이 있었는지, 왜 발생했는지, 무엇을 바꿔야 하는지 기록하세요.

    다음을 포함해 1페이지 사후 인시던트 노트를 incidents/2026-06-27-checkout-504.md에 작성하세요: 타임라인, 근본 원인, 완화 조치, 하나의 예방 조치(알림, 런북, 테스트, 또는 리팩터링).

핵심 프롬프트

[vault path]의 자격 증명으로 [host]에 SSH 접속하세요. [service] 로그의 최근 [N hours]를 가져오고 에러 패턴, 스택 트레이스, 지연 시간 이상을 드러내세요. 그런 다음 같은 기간 동안의 인프라 변경을 확인하세요. [symptom]에 대한 상위 3개 가설 순위 목록을 제공하세요 — 각각에 대해 뒷받침 증거와 하나의 검증 명령어를 알려주세요. 파괴적인 작업은 실행하지 마세요.

검증

  • 명확한 근본 원인이 식별되고 문서화됨
  • 수정이 적용되고 지표가 기준선으로 돌아옴
  • 사후 인시던트 노트가 작성되어 팀과 공유됨
  • 알림이 누락되었다면 추가하기 위한 후속 조치를 파일에 기록

흔한 실수

  • 먼저 재시작: 재시작은 증거를 숨기고 두 번째 인시던트를 일으킬 수 있습니다. 항상 행동하기 전에 진단하세요.
  • 단일 로그 파일: 증상은 종종 여러 로그에 걸쳐 있습니다. 명백한 것 하나만이 아니라 모든 로그에서 가져오세요.
  • 사후 인시던트 생략: 기록이 없으면 같은 인시던트가 3개월 안에 다시 발생할 것입니다.

관련 문서

  • 트러블슈팅 — 일반적인 OpenCode 문제와 해결 방법
  • TUI — 여러 서버에서 병렬로 작업하기 위한 멀티 세션 터미널 UI

관련 레시피

관련 문서

다음 단계