20.1 트러블슈팅 기본 원칙과 방법론

장애가 발생했을 때 충분한 원인 분석 없이 인스턴스를 단순 재기동(Reboot) 하거나 무계획적인 롤백(Rollback)을 수행하는 대증적 접근 방식은 극히 지양해야 한다. 이러한 행위는 일시적으로 시스템의 표면적 상태를 복구할 수는 있으나, 근본 원인(Root Cause)을 영구적으로 은폐하여 향후 동일한 조건 하에서 시스템 장애가 재발하도록 방치하는 안티 패턴(Anti-Pattern)이다.

특히 Zenoh 프로토콜 생태계와 같이 노드의 참여 및 이탈에 따라 네트워크 위상(Topology)이 실시간으로 재현되고, 멀티캐스트 기반의 가십 프로토콜(Gossip Protocol)을 내재화한 분산 시스템에서는 장애 해결 프로세스가 엄정한 체계성(Systematicity)을 바탕으로 수행되어야 한다. 트러블슈팅(Troubleshooting)은 객관적 지표에 근거하여 오류 단계를 논리적으로 차단해 나가는 연역적 수단론이어야 한다.

1. 방법론의 3대 원칙 (Three Principles of Troubleshooting)

1. 가시성(Observability)의 확보
   장애 발생 시, 시스템 내부 상태를 추측으로 예단해서는 안 되며, 반드시 수집된 데이터를 통해 증명해야 한다. Zenoh 라우터 데몬의 tracing 단위의 로그 덤프, 클라이언트 프로세스의 메모리 풋프린트, 그리고 물리 인터페이스 계층(NIC)의 패킷 캡처 유틸리티(예: Wireshark) 데이터 등을 동원하여 시스템의 현재 이상 징후를 계량화 가능한 정량 수치와 순수 텍스트(Raw Text) 지표로 치환해야 한다.

2. 가설 주도 디버깅 (Hypothesis-Driven Debugging)
   관찰된 이상 증상을 바탕으로 확률적 유의미성이 높은 가설 배열을 독립적으로 수립하라. 예를 들어 “에구동 모터의 제어 명령이 누락된다“는 증상에 대해,

• 가설 A: C++ 클라이언트 측 퍼블리셔(Publisher) 소켓 버퍼의 기한 만료(Overflow)로 인한 패킷 강제 폐기 현상.
• 가설 B: Wi-Fi 통신 음영 지역 횡단에 따른 물리 계층의 일시적 링크 단절(Link Dropped).
• 가설 C: Zenoh 라우터 단의 접근 제어 체계(ACL)에 의한 쓰기 권한(Write Permission) 거부.
  이후 각 개별 가설에 대해 통제된 격리 검증 절차(Isolated Validation)를 거쳐 논리적으로 기각시켜 나가는 분석 과정에 돌입한다.

3. 단일 변인 통제 (Single Variable Control)
   결함 보정 과정에서 복수의 시스템 매개변수(Parameters)를 동시에 조작하는 행위는 금기시된다. zenohd.json5 설정 내에서 바인딩 포트를 수정하는 동시에 큐(Queue) 할당 길이를 확장한 뒤 재기동하여 정상 상태가 복구되었다면, 정확히 어떤 변수로 인해 시스템 안정성이 확보되었는지 인과 관계(Causation)를 특정할 수 없다. 오직 단일 설정치 변경과 단일 관측을 반복하는 통제성이 핵심 검증 규칙이다.

2. 장애 대응 라이프사이클 (Incident Response Lifecycle)

분산 시스템의 장애 복구는 표준화된 5단계의 생애 주기(Lifecycle)를 거쳐 순환된다. 높은 가동률과 신뢰성 공학(SRE, Site Reliability Engineering) 측면에서 지켜져야 할 엄격한 대응 절차다.

graph TD
    A[이상 증후 보고/알람] --> B(식별 Identification)
    B --> C(위치 격리 Isolation)
    C --> D(원인 규명 Root Cause Analysis)
    D --> E(해결 Resolution)
    E --> F(검증 Verification)
    F -->|이상 지속 시| D
    F -->|검증 완료| G[사후 분석 및 재발 방지 Post-mortem]

2.0.1 단계: 식별 (Identification)

관제 대시보드(Frontend)에서 로봇 상태 지표의 갱신이 중단된 상황을 감지했을 때, 막연한 현상 공유를 넘어 정량적인 시스템 상태(State) 선언으로 치환하는 과정이다.

• 예시: “오후 3시 15분부터, 관할 구역 2공장 내 10대 모바일 단말에서 발행 중이던 /telemetry/odom 토픽 스트림 교환이 전면 중단되었음. 단, 코어 중앙 라우터 데몬의 상태 확인(Health) 포트는 응답하며 CPU 논리 자원 할당률은 정상 기준치(10%)를 상회하지 않음.”

2.0.2 단계: 격리 (Isolation)

분산 네트워크 토폴로지 내부에서는 특정 노드의 버그성 쿼리 폭주가 전체 대역폭 할당량을 고갈시켜, 정상 노드 간의 통신 기능 이행마저 마비시키는 연쇄 장애(Cascading Failure) 위험을 동반한다.
따라서 원인 분석 행위에 앞서 가상 또는 물리적 방해가 전파되는 트래픽 연결망을 컷오프(Cut-off) 해야 한다. 비정상 트래픽 발생이 의심되는 지역망의 라우터를 중앙 클러스터 토폴로지에서 연결 해제(Unbind)하거나 전위 방화벽(iptables 등) 차단을 통해 시스템의 2차 피해 전이를 선제적으로 봉쇄(Containment)한다.

2.0.3 단계: 원인 규명 (Root Cause Analysis)

장애 현상의 근원지를 색인하기 위해, 연관 엔드포인트에 축적된 디버그 레벨 로그(Log), 시계열 프로토콜 메트릭, 라우터 데몬 콘피그레이션(zenohd.json5) 원본 자산을 통합 수집한다.
특히 인프라 교체 또는 스키마 병합 등 최근 실행된 릴리스 변경 사항(Deployment History)을 우선 점검 대상(First Check)으로 삼는다. 중간 허브 망에 z_sub 커맨드라인 유틸리티를 투입하여 홉 간 패킷 유출(Drop)의 덤프 스냅샷(Dump Snapshot) 형태를 채취하고 가설들을 순차 입증한다.

2.0.4 단계: 해결 (Resolution)

원인이 검증되었다면 패치 로직(Patch Logic)을 반영한 코드를 재빌드하거나 설정 환경 변수(Environment Config)를 동적으로 교체한다.

• 큐 용량 제약(Queue Overlap)으로 인한 패킷 증발이 도출되었다면, 트랜스포트 설정의 shared_memory 버퍼 한계 임계치를 기존 10MB에서 50MB로 증설한다.
• 객체 파괴자 래퍼런스 누수(Reference Leak)로 확인된 클라이언트 오류의 경우, 메모리 명시적 반환(z_close 및 세션 파괴) 구문을 보완한 최신 펌웨어 바이너리를 재컴파일하여 OTA로 배포 패치한다.

2.0.5 단계: 검증 (Verification)

적용된 핫픽스(Hotfix) 사항이 시스템 결함을 항구적으로 제어 완료했는지 보수적으로 실증하는 척도 단계다. 일시적으로 네트워크 트래픽 정체가 해소된 착시(Illusion) 현상에 주의하여 모니터링 세션을 장기간 지속해야 한다. 스크립트 도구를 구동하여 충분한 트래픽 점유 부하 검증을 유지함으로써, 과거와 동일 시간 대비 에러 누적 카운터가 발생하지 않고 연결 활성 토큰(Liveliness Token)이 소실 배출되지 않음을 증명한 뒤 롤백(Rollback) 대기 태세를 해제한다.

3. 재현 환경 구축 및 가설 시뮬레이션 기법

불규칙적인 통신 장애 현상을 현장 프로덕션(Production) 시스템에 직접 접근하여 디버깅 로그를 스캔하는 행위는 관측 위험성(Intrusion Risk)만을 야기한다. 원천 엔지니어링 분석은 오직 개발 로컬 플랫폼이나 샌드박스 망 내부로 문제의 지형도를 동기화하여 완벽한 재현성(Reproducibility)을 끌어낸 조건 하에서만 효력을 발휘한다.

3.0.1 컨테이너 기반(Docker Compose) 위상 복제 구성

클라우드 허브 라우터, 에지 라우터 브리지 단말, 이기종 어댑터 인스턴스를 하나의 개발 PC에 압축하여 복제형 논리 분산 트리(Mock Tree)를 재현해야 한다. docker-compose.yml 스펙을 활용하여 각 통신 단절 계층을 가상 도커 브릿지 포트로 분리함으로써 라우터 결합성 테스트를 격리 실행한다.

version: '3.8'
services:
  cloud-router:
    image: eclipse/zenoh:latest
    command: ["--listen", "tcp/0.0.0.0:7447"]
    ports:
      - "7447:7447"

  fog-router-a:
    image: eclipse/zenoh:latest
    # 연결(connect)을 클라우드 라우터로 직접 향하도록 지정하여 트리 계층(Tree)을 구현.
    command: ["--connect", "tcp/cloud-router:7447", "--listen", "tcp/0.0.0.0:7448"]
    depends_on:
      - cloud-router

이러한 로컬 가상망 구성을 통해 타 시스템의 영향력이 배제된 상태로 라우터 간 홉 트레이스(Hop-Trace) 인과성을 파악할 수 있다.

3.0.2 열혈화 네트워크(Degraded Network) 시뮬레이션 주입

패킷 강하, 지터(Jitter), 롱테일 레이턴시(Long-tail Latency)와 같은 열악한 무선 스펙트럼 상태 조건은 유선 광랜 사무 환경에선 도출되지 않는다. 리눅스 네트워크 트래픽 컨트롤 레이어 도구 유틸리티인 tc(Traffic Control)를 가동하여, 가상 이더넷 인터페이스(eth0)망에 물리 채널의 붕괴율을 수학적 확률 난수로 강제 시뮬레이션(Fault Injection)하라.

## eth0 인터페이스 상 패킷 응답 지연 200ms 부과 및 패킷 유실률 30% 강제 유발 인가 
sudo tc qdisc add dev eth0 root netem delay 200ms loss 30%

극한의 열화 채널을 인가한 뒤 Zenoh 트랜스포트 레이어의 백오프(Backoff) 시도 알고리즘과 TCP 연결 리커버리(Recovery) 상태 코드를 분석 및 정정한다.

4. Zenoh 네트워크 토폴로지 분기에 따른 논리적 구간 격리 (Path Isolation)

데이터 송수신 프로세스의 전송 파이프라인 구간 규모가 확대될수록 데이터의 증발 책임을 규명하기 위한 단위 척도가 중요하다. 분산된 L4~L7 네트워크 릴레이 경유 경로들 중 트래픽 전송 실종 발생 지점을 이분법(Binary Cut) 탐색 로직으로 진단 소거한다.

graph LR
    Sensor[에지 디바이스 P1] -- 1구간 --> Fog[로컬 에지 라우터 R1]
    Fog -- 2구간 --> Firewall[게이트웨이/NAT FW]
    Firewall -- 3구간 --> Cloud[클라우드 허브 라우터 R2]
    Cloud -- 4구간 --> Backend[백엔드 수집기 S1]

4.0.1 전제 1. 토폴로지 릴레이 중간 허브 타겟팅 (에지 라우터 기준)

1번 구간 단말에서 발송된 센서 데이터가 4번 모니터 컴포넌트까지 전파되지 못하는 유실 이벤트를 판별하고자 할 때, 전체 흐름상 가장 접근하기 용이한 중앙 홉 단위인 “에지 라우터 R1“을 1차 검증(Mid-point Inspection) 대상으로 분류한다.
R1 장치의 관리 포트에 진입하여 순수 데몬 CLI 환경으로 z_sub 스크립트 테스트 구문을 점검한다. R1 데몬이 P1 센서로부터 인입된 데이터를 화면 콘솔에 반환하는지 증명한다.

• 정상 출력 도출 시: 1번 구간(에지 기기 \rightarrow 로컬 에지 라우터 간 통신)의 릴레이 기능은 구조적으로 완전 무결함이 100% 입증된다. 디버깅 감시 궤도를 2구간 방화벽 정책 혹은 4구간 모니터 서버 애플리케이션 연결 문제 등 외부 망 영역으로 전이시킨다.
• 무반응 또는 유실 도출 시: 외부 클라우드 통신 이상 분석에 투입할 자원을 완전히 회수하여, 에지 장비인 센서 P1의 전송 코드 실패 혹은 근거리 통신(로컬 스위칭망 브로드캐스트 누락) 결함 한정 디버깅으로 시야를 재한정한다.

4.0.2 전제 2. 디스커버리 및 통신 토폴로지 모드 교차 한정 검증

로컬 와이파이 영역 안에서 연결된 A 단말과 B 단말의 Peer 간 오버레이 직접 데이터 송수신 결함이 보고될 경우, 해당 피어의 모드를 강제로 임시 Client 설정 기반의 단방향 라우팅 체계로 구성하여 클라우드로 핑 체결(z_put -m client -e tcp/cloud:7447)을 도출한다. 클라우드로는 정상적으로 소켓 채널이 뚫렸으나 상호 간 디스커버리가 도출 불능이라면, 이는 곧 네트워크 라우팅 레이어 장비단에서 UDP 기반 멀티캐스트 채널 가로채기(IGMP Snooping Policy Block) 제약을 부과하고 시스템을 격리 중임을 방증하는 강력한 지표 증거로 한정 계산될 수 있다.

5. 증상분류(Symptomatology) 가이드 및 초기 대처 체크리스트 트러블슈팅

분산 에러 양상은 특정 기형적 오류 시그니처(Signature Symptom) 패턴을 거동한다. 비정상 세션 현상 인지 즉각 시, 엔지니어가 객관적으로 수행 검토해야 할 1차 분류 진단 체크리스트를 표기한다.