11.11 디버깅 트러블슈팅 및 장애 대응 가이드

11.11 디버깅 트러블슈팅 및 장애 대응 가이드

새로운 미들웨어를 팀에 도입하는 것은 엄청난 도박이다. 로봇이 한 번 멈출 때마다 사장님과 매니저는 “거 봐, 원래 쓰던 DDS (FastDDS) 로 돌아가자!” 라고 당신을 압박할 것이다.

이 챕터는 그런 비상 상황에서 Zenoh 탓인지, 네트워크 탓인지, 아니면 동료가 짠 ROS2 코드 버그인지를 3분 안에 발라내어 증명하는 장애 대응 및 면피용 런북이다.

1. ROS2-Zenoh 네트워크 상태 진단 및 디버깅 툴 활용법

ros2 topic echo 를 쳤는데 아무런 데이터가 올라오지 않는다. DDS 라면 멀티캐스트 네트워크를 의심해야 하지만, Zenoh 라면 라우팅 테이블이 꼬였을 확률이 높다.

1.0.1 [Runbook] CLI 스캐너 디버깅 전술

ROS2 툴이 안 먹힌다면, 가장 밑바닥의 Zenoh 네이티브 툴로 전파가 살아있는지 검증해야 한다.

1. 터미널 스니퍼(Sniffer) 가동
로봇 안에서 Zenoh 테스트 클라이언트를 켜서 “ROS2 영역” 전체를 도청해 본다.

## `ros2/rt/**` 는 ROS2 와 연결된 모든 토픽을 의미한다.
z_sub -k "ros2/rt/**"

만약 여기서 /cmd_vel 이진 데이터가 와다다다 쏟아진다면, 네트워크나 통신 미들웨어(rmw_zenoh)의 잘못이 절대 아니다! 데이터를 받기로 한 상대방 ROS2 노드의 Callback 함수가 죽어있는 것이다. 개발팀에게 버그 수정을 요청하라.

2. 통신 브릿지 락온(Lock-on) 검증
로봇의 브릿지가 AWS 라우터에 제대로 코드를 꽂고 있는지 강제로 확인한다.

## AWS 라우터 터미널에서
z_get -k "@/router/*/session"

여기에 로봇의 공인 IP 가 보이지 않는다면 로봇이 위치한 공장의 회사 방화벽 톨게이트가 TCP 7447 포트를 외부로 나가지 못하게 틀어막고 있는 장비 결함이다.

2. 토픽 유실, 서비스 타임아웃 발생 시 로그 분석 체계

로봇에 경로 계산(Service)을 요청했는데 대답이 없다(Timeout). 혹은 이동 명령(Action)이 도중에 멈춘다.
Zenoh 환경에서 가장 많이 일어나는 이 현상의 부검을 시작한다.

2.0.1 [인스펙션] RPC 단절 로그 추적기법

1. 환경 변수 최대 개방 (Log Verbosity 5단계)
에러가 발생하는 콘솔창을 다시 띄울 때 강제로 디버그 모드를 주입한다.

## 브릿지나 라우터를 켤 때 강제로 TRACE 레벨 로깅을 튼다!
RUST_LOG=zenoh=trace zenoh-bridge-dds

화면이 미친 듯이 스크롤 될 것이다. 하지만 여기서 우리가 찾아야 할 키워드는 단 하나, Queryable 이다.

2. 원인 분석: 쿼리어블 증발 현상
RPC(Service / Action) 통신 중에 죽었다면, 로그에 이런 문구가 뜰 것이다.
WARN: No Queryable matching ros2/rq/calculate_path

  • 해석: 클라이언트가 경로 계산 질문을 공중(네트워크)에 던졌는데, 정작 저 멀리에서 경로를 계산해 줘야 할 ROS2 Service Server 노드가 죽어있거나, 네트워크가 끊어져서 대답할 놈(Queryable)이 존재하지 않는다 는 뜻이다. 이 에러가 보이면 주저 없이 로봇 내부의 노드 상태 다이그노스틱(Diagnostics) 탭을 점검해야 한다.

3. ROS2 배포판(Humble, Iron, Jazzy 등)과 Zenoh 버전 간의 호환성 관리

“어제까지 잘 되던 로봇이 apt upgrade 한 번 쳤다고 먹통이 되었습니다!”

패키지 매니저의 지옥(Dependency Hell)에 빠진 것이다. ROS2 코어와 Zenoh 네이티브는 그 진화 속도가 달라서 툭하면 호환성 충돌이 일어난다.

3.0.1 [Runbook] 프로토콜 락(Lock-in) 전술

Zenoh 는 버전 간의 Wire Protocol(네트워크 패킷 생김새) 가 바뀔 때가 있다.
만약 로봇에는 Zenoh 0.7 버전을 깔고, AWS 에는 최신 Zenoh 0.10 을 깔았다면 둘은 서로가 외계인 인 줄 알고 아예 악수(Handshake)조차 하지 않는다.

1. 바이너리 버전 고정 (Pinning)
apt 환경설정이나 도커 파일(Dockerfile) 작성 시, 절대 latest 나 태그 없는 버전을 쓰지 마라.
로봇 군집과 관제 서버는 무조건 소수점 두 번째 자리까지 똑같은 버전을 강제해야 한다.

## ❌ 절대 금지
RUN apt install zenoh-bridge-dds 

## ✅ 올바른 런북
RUN apt install zenoh-bridge-dds=0.10.1~beta-*

2. ROS2 RMW 플러그인 호환성 확인
rmw_zenoh 소스를 수동으로 빌드할 때, 브랜치를 맞추지 않으면 C++ 코드가 에러를 뿜는다.

  • 우분투 22.04 (ROS2 Humble) -> rmw_zenoh 도 humble 브랜치를 clone 해야 한다.
  • 우분투 24.04 (ROS2 Jazzy) -> 이 버전부터는 아예 기본 탑재(Tier 1) 논의가 있으므로 OS 의 공식 ros-jazzy-rmw-zenoh-cpp 패키지를 그대로 믿고 써도 좋다.

4. rmw_zenoh 및 브릿지 운용 시 자주 발생하는 오류 코드와 해결책

스택 오버플로우나 깃허브 이슈(Issue) 창을 뒤지는 시간을 1시간에서 10초로 단축해 주는 마지막 인덱스다.

4.0.1 [인스펙션] 사망 선고(Error Code) 해석기

1. [ERROR] Failed to discover Zenoh router

  • 증상: rmw_zenoh 로 구동 중인 ROS2 노드가 켜지자마자 꺼지거나 멈춰있다.
  • 원인: 로봇 안에 zenohd (로컬 라우터) 데몬을 백그라운드로 안 켜두었다! Node 는 라우터 없이 절대로 다른 Node 와 대화할 수 없으니, systemctl enable zenohd 로 데몬을 항상 살려놔라.

2. [WARN] Received oversized message (8388608 bytes), dropping.

  • 증상: 카메라 영상이 안 들어온다.
  • 원인: 한 번에 8MB 가 넘는 PointCloud 정크를 브릿지 안으로 던졌다.
  • 타개책: 브릿지 코어가 터지기 전에 스스로 방어한 것이다. 11.6 장으로 돌아가서 QoS 를 BEST_EFFORT 로 바꾸거나 PointCloud 해상도를 절반으로 날려라.

3. [ERROR] Binding address already in use: tcp/0.0.0.0:7447

  • 증상: 브릿지를 켰는데 거부당한다.
  • 원인: 이 로봇 안에 멍청한 엔지니어가 zenohd 랑 zenoh-bridge-dds -l ... 를 동시에 띄워서 두 프로세스가 똑같이 7447 포트를 열려고 머리채를 잡고 싸우는 중이다. 포트를 충돌 나지 않게 바꾸거나, 브릿지만 살려둬라.

모든 소프트웨어 에러는 거짓말을 하지 않는다. 인프라 구조를 오해한 아키텍트의 오만함만이 원인일 뿐이다.