WorkBuddy와 Tencent Cloud CLS를 활용한 자연어 로그 트러블슈팅 (Troubleshooting)

알람이 발생하면 엔지니어들은 종종 동일한 워크플로우를 반복합니다. 콘솔을 열고, 리전(Region)을 선택하고, 로그 토픽(Log Topic)을 찾고, CQL 또는 SQL을 작성하고, 시간 범위를 조정하고, 결과를 검토하고, 에러를 그룹화한 다음 주변 컨텍스트(Context)를 확인하는 과정입니다.

기존의 Tencent Cloud CLS 아티클은 다른 인터페이스를 보여줍니다. WorkBuddy를 Tencent Cloud CLS 어시스턴트와 함께 사용하여 자연어 트러블슈팅 요청을 로그 검색, 통계 분석, 컨텍스트 조회 및 수집 파이프라인(Collection Pipeline) 진단으로 전환하는 방식입니다.

이 포스트는 해당 워크플로우를 실무적인 SRE 런북(Runbook)으로 재작성합니다.

이 어시스턴트가 대체하고자 하는 것

자연어 로그 트러블슈팅은 관측 가능성(Observability)의 기본 원칙을 대체하려는 것이 아닙니다. 반복적인 장애 대응(Incident-response) 단계를 단축하는 것이 목적입니다.

엔지니어의 목표	자연어 요청	원문 아티클의 기반 기능
에러 로그 검색	4월 15일 오후 6시, ap-guangzhou 리전의 default-topic 토픽에서 에러 로그 쿼리	SearchLog를 호출하고 level:ERROR와 같은 CQL 사용
...

시나리오 1: 약 30초 만에 에러 로그 검색하기

원문 아티클의 기본 요청은 다음과 같습니다:

4월 15일 오후 6시, ap-guangzhou 리전의 default-topic 토픽에서 에러 로그를 쿼리해줘.

어시스턴트는 CLS의 SearchLog API를 호출하고 CQL을 사용하여 에러 로그를 검색합니다:

level:ERROR

예시 결과에는 시간, 서비스, 메시지, 에러 또는 상태 코드(Status Code), 관련 정보, 지연 시간(Latency) 및 소스 머신(Source Machine)이 포함됩니다. 스크린샷은 payment-service에서의 결제 콜백 실패 및 api-gateway에서의 업스트림 서비스 사용 불가능과 같은 문제를 보여줍니다.

더 구체적인 요청을 통해 결과를 좁힐 수 있습니다:

지난 30분 동안 payment-service에서 발생한 타임아웃 (timeout) 에러만 보여줘.

statusCode가 500인 모든 요청을 찾아서 시간을 기준으로 내림차순 정렬해줘.

이는 알림 (alert) 발생 후의 초기 대응, 빠른 아침 점검, 그리고 과거 장애 (incident) 검토에 유용합니다.

시나리오 2: 에러 분포 분석 (analyze error distribution)

에러 목록은 무엇이 일어났는지를 알려줍니다. 트러블슈팅 (troubleshooting) 과정에서 다음 질문은 보통 다음과 같습니다: 어떤 서비스에서 가장 많은 에러가 발생하는가, 어떤 에러 코드가 지배적인가, 그리고 시간이 지남에 따라 트렌드가 어떻게 변하는가?

원문 기사에서는 다음 요청을 사용합니다:

각 에러 유형을 카운트하고 결과를 서비스별로 그룹화해줘.

예시는 payment-service, api-gateway, order-service, user-service와 같은 서비스별로 로그 수를 그룹화합니다. 또한 주요 문제가 payment-service에서 api-gateway 경로에 집중되어 있다는 점을 요약해 줍니다.

일반적인 분석 요청은 다음과 같습니다:

분석 목표	요청 예시
에러 카테고리	에러 코드별로 그룹화하고 상위 10개를 보여줘
...

시나리오 3: 로그 컨텍스트 조사 (inspect log context)

단일 로그 라인이 전체 장애 체인 (failure chain)을 설명하는 경우는 드뭅니다. 원문 기사에서는 다음 요청을 사용합니다:

이 DB_CONNECTION_TIMEOUT 로그 주변의 컨텍스트를 확장해줘, 앞뒤로 2개씩.

어시스턴트는 DescribeLogContext를 호출하여 대상 로그의 전후 로그를 반환합니다.

예시에서 컨텍스트는 다음과 같은 내용을 보여줍니다:

• order-service가 주문을 처리하는 데 5.2초가 걸렸으며 두 번 재시도(retry)했습니다.
• payment-service가 30초 결제 콜백 타임아웃 (payment callback timeout)에 도달했습니다.
• api-gateway가 결국 연쇄적인 (cascading) 502 에러를 반환했습니다.

이는 에러를 이벤트 시퀀스 (event sequence)로 되돌려 놓으며, 이는 단순히 대상 라인만을 읽는 것보다 보통 더 유용합니다.

시나리오 4: 수집 파이프라인 (collection pipeline) 진단

때로는 문제가 로그 내부에 있지 않을 수도 있습니다. 문제는 로그가 누락되었다는 점입니다.

원본 기사에서는 다음과 같은 요청을 사용합니다:

이 토픽(topic)에 대한 머신 그룹(machine group)과 수집 설정(collection configuration)을 확인해 줘.

그러면 어시스턴트는 다음과 같은 여러 확인 작업을 수행합니다:

API	목적
DescribeMachineGroups	머신 그룹 조회
...

진단 예시에는 다음 내용이 포함됩니다:

• 토픽 (Topic): default-topic
• 수집 설정 (Collection configs): 2개
• 로그 경로 (Log paths): /data/log/**/1.log, /data/log/**/2.log
• 로그 유형 (Log types): JSON 로그 및 미니멀리스트 (minimalist) 로그
• 머신 그룹 (Machine group): default-machine-group
• 에이전트 버전 (Agent version): 3.6.0
• 상태 (Status): 오프라인 (offline)
• 권장 확인 사항 (Suggested checks): loglistener 프로세스, CLS 서버 측으로의 네트워크 연결성, 그리고 /var/log/loglistener/loglistener.log에 있는 로컬 로그

이는 로그가 도착하지 않거나, 수집 설정이 적용되지 않거나, 머신 그룹 바인딩 (machine group bindings)이 의심스러울 때 사용하는 올바른 워크플로우 (workflow)입니다.

자연어 로그 검색을 더 안정적으로 만드는 네 가지 입력 요소

원본 기사는 유용한 네 가지 패턴을 제공합니다:

입력 (Input)	의미 (Meaning)	예시 (Example)
리전 (Region)	클라우드 리전 이름 또는 코드	ap-guangzhou
...

완전한 요청은 다음과 같을 수 있습니다:

ap-guangzhou 리전에서, 지난 한 시간 동안 payment-topic의 에러 로그를 확인하고, 각 에러 유형의 개수를 세어 줘.

어시스턴트는 다음과 같이 모호한 요청에서 시작할 수도 있습니다:

광저우(Guangzhou)에 있는 로그 토픽에 최근 에러가 보고되었는지 확인해 줘.

원본 기사에 따르면, 어시스턴트는 누락된 컨텍스트 (context)를 채울 수 있습니다. 예를 들어, 최근 에러를 확인하기 전에 해당 리전의 토픽 목록을 먼저 나열하는 방식입니다.

설정 워크플로우 (Setup workflow)

먼저, WorkBuddy를 열고 Skills로 이동하여 Tencent Cloud CLS 어시스턴트를 검색한 뒤 설치합니다.

둘째, Tencent Cloud 자격 증명 (Credentials)을 설정합니다. 원문 기사에서는 macOS 및 Linux Zsh 예시를 제공합니다:

echo 'export TENCENTCLOUD_SECRET_ID="your-secret-id"' >> ~/.zshrc
echo 'export TENCENTCLOUD_SECRET_KEY="your-secret-key"' >> ~/.zshrc
source ~/.zshrc

셋째, 간단한 요청으로 테스트합니다:

Show my log topics in the Guangzhou region.

토픽 목록이 나타나면, 어시스턴트가 로그 트러블슈팅 (Troubleshooting) 작업을 수행할 준비가 된 것입니다.

실무 FAQ (Practical FAQ)

자연어 트러블슈팅 (Natural-language troubleshooting)을 사용하면 컨텍스트 (Context)가 필요 없나요?

아니요. 원문 기사에서는 최소한 리전 (Region), 오브젝트 (Object), 시간 범위 (Time range), 그리고 작업 (Task)을 제공할 것을 권장합니다. 입력 정보가 더 완전할수록 어시스턴트가 더 정확한 검색이나 진단 (Diagnosis)을 생성하는 데 도움이 됩니다.

로그가 누락되었을 때는 무엇을 물어봐야 하나요?

수집 경로 (Collection path)부터 시작하세요. 어시스턴트에게 토픽의 머신 그룹 (Machine group), 에이전트 상태 (Agent status), 수집 설정 (Collection configuration), 그리고 바인딩 관계 (Binding relationship)를 확인하도록 요청하십시오.

이 기능이 어떤 수동 작업들을 대체할 수 있나요?

리전 전환, 토픽 선택, 쿼리 구문 (Query syntax) 작성, 시간 범위 변경, 컨텍스트 확인, 수집 설정 검사 등 반복적인 콘솔 (Console) 작업을 줄일 수 있습니다.

SRE 팀에게 주는 주요 가치는 무엇인가요?

가치는 속도입니다. 원문 기사는 의도 (Intent)를 API 기반의 검색, 분석, 컨텍스트 조회, 그리고 수집 진단으로 전환함으로써, 일반적인 트러블슈팅 루프 (Troubleshooting loop)를 30분에서 3분으로 단축하는 개선 효과를 강조합니다.

최종 요약 (Final takeaway)

자연어 로그 트러블슈팅 (Natural-language log troubleshooting)은 신뢰할 수 있는 플랫폼 API (Platform APIs)에 직접 매핑될 때 가장 효과적으로 작동합니다. 이번 Tencent Cloud CLS 및 WorkBuddy 워크플로우에서 어시스턴트가 유용한 이유는 사용자의 의도를 SearchLog, SQL 스타일의 분석 (SQL-style analysis), DescribeLogContext, 머신 그룹 확인 (Machine group checks), 에이전트 상태 확인 (Agent status checks), 그리고 수집 설정 검사 (Collection configuration inspection)와 연결해주기 때문입니다.