세션에서 Agent 버그 리포트를 수집하고 전송하기¶
Agent가 예상과 다르게 응답하거나, 도구가 멈추거나, 연결이 불안정하거나, 진단용 로그가 부족하면 문제가 발생한 세션에서 직접 버그 보고서를 생성할 수 있습니다. 보고서는 현재 세션과 Agent 런타임 상태를 수집하며, config.toml(이전 설치에서는 agent.env)의 민감한 값 할당만 마스킹합니다. 운영 또는 지원 담당자가 분석할 수 있도록 ZIP을 업로드합니다.
시작하기 전에, Agent가 온라인 상태인지 확인하고 문제가 발생한 원래의 세션을 열어야 합니다. 버그 리포트는 현재 세션만을 수집하며, 다른 세션의 채팅 내용은 자동으로 포함되지 않습니다.
보고서를 직접 수집하고 지원 부서로 전송합니다.¶
보고서를 지원 인원에게 전달해야 하는 경우, 초기 요청 시 수신자 주소와 증상 내용을 반드시 포함시켜야 합니다.
Collect a Bug Report for the current Session and send the download link to tec-support@guance.com. Symptom: the page keeps showing that the Agent is thinking after a tool finishes.
Agent은 다음과 같은 단계를 수행합니다:
- 현재 세션의 버그 보고서를 수집하고 업로드합니다. 민감한 값 할당을 마스킹하는 대상은
config.toml(이전 설치에서는agent.env)뿐입니다. - ZIP 파일의 임시 다운로드 링크를 얻습니다.
- 지정된 이메일 주소로 파일명, 링크, 유효 기간을 전송합니다.
이 방식은 세션에서 ZIP 파일을 다운로드한 후, 이를 이메일 첨부 파일로 수동으로 업로드하는 것을 피합니다. 이메일에는 임시 다운로드 링크가 포함되어 있으며, ZIP 파일은 포함되어 있지 않습니다. 수신자는 링크가 만료되기 전에 보고서를 다운로드해야 합니다.
보내기 전에 수신자의 주소를 확인하시고, 진단 데이터를 처리할 권한이 있는 사람에게만 보고서를 전송하시기 바랍니다.
현재 세션에 대한 버그 리포트를 수집합니다.¶
이 메시지를 세션으로 전송하세요:
여러분은 같은 메시지에 이러한 증상을 포함시킬 수 있습니다.
Collect a Bug Report for the current Session. Symptom: the page keeps showing that the Agent is thinking after a tool finishes.
Agent는 보고서를 수집하고 config.toml(이전 설치에서는 agent.env)의 민감한 값 할당만 마스킹한 다음, 보고서를 패키징하고 업로드합니다. 이 과정은 일반적으로 2분 이내에 완료됩니다. CPU Profile을 활성화하면 샘플링 시간이 추가로 필요할 수 있습니다.
업로드가 성공적으로 이루어진 후, ZIP 파일과 다운로드 정보가 세션에 표시됩니다. 30일 동안 플랫폼에서 보고서가 보관되며, 임시 다운로드 링크는 기본적으로 7일 동안 유효합니다. 링크가 만료되기 전에 보고서를 다운로드하거나 전송해야 합니다.
표준 권한 모드에서 수집을 승인합니다.¶
표준 승인 모드에서는 진단 데이터를 읽기 전에 승인 정보를 표시합니다. 승인 정보에는 수집 범위, 데이터 범주, 그리고 CPU Profile가 포함되어 있는지 여부가 나와 있습니다.
범위가 적절한지 확인한 후 승인하세요. 승인을 거부하거나 요청을 취소하거나 이전 실행을 중지하는 새 메시지를 보내면 Agent는 보고서를 수집하거나 업로드하지 않습니다.
YOLO/Full Access 모드는 승인 대화상자를 표시하지 않습니다. Agent은 보고서를 직접 수집하고 업로드하며, 플랫폼은 여전히 도구 호출에 대한 권한 감사 데이터를 기록합니다.
이메일로 기존의 버그 리포트를 보내기¶
만약 초기 요청으로만 보고서가 생성된다면, 같은 세션에서 계속 진행하세요:
이메일의 내용에는 ZIP 파일의 이름, 유효 기간, 임시 다운로드 링크가 포함되어 있습니다. ZIP 파일은 첨부 파일로 제공되지 않습니다. 수신자는 링크가 만료되기 전에 보고서를 다운로드해야 합니다.
보고서에 포함된 데이터를 관리합니다.¶
기본적으로, 이 보고서에는 다음과 같은 내용이 포함됩니다:
- 세션 내에서 발생한 원본 사용자 메시지들은 수집 시작 시점까지 그대로 유지되며, 내용은 변경되지 않습니다.
- 도구 관련 이벤트, 다른 채팅 기록, 그리고 효과적인 맥락 등을 고려하여, 기존 예산 내에서 원래의 콘텐츠를 구현합니다.
- 최근의 Agent 로그 및 실행 시간 메트릭스.
- 프로세스, 컨테이너, 네트워크 프로브 및 빌드 정보.
- 원본 환경 변수와 설정, 그리고 민감한 값 할당이 마스킹된
config.toml(이전 설치에서는agent.env). - Profile, Skill, Schema, 그리고 MCP 동기화 관련 진단 요약 정보입니다.
- 크기가 제한된 goroutine 덤프와 힙 프로파일.
로그 수집은 파일별 또는 전체 크기에 따른 잘라내기를 하지 않습니다. log_since_hours(기본 24시간)로 최근 수정된 파일을 선택하고, 각 파일을 열었을 때의 크기까지 읽어 내용을 대체하지 않고 압축합니다. 이후 추가된 내용은 수집 범위를 늘리지 않습니다. 순환으로 삭제된 로그는 복구할 수 없으며 메모리에만 있는 링 버퍼 로그는 partial로 표시됩니다. Agent는 최대 1 GiB(1,073,741,824바이트)의 ZIP을 허용하고 임시 파일에서 스트리밍합니다. 더 큰 ZIP은 로그를 버리지 않고 명확히 실패합니다. Beak v0.13.0은 여전히 파일당 업로드를 32 MiB로 제한하므로 더 큰 보고서는 업로드에 실패합니다. Agent의 제한이 서버 제한을 늘리지는 않습니다. 큰 보고서를 지원하려면 후속 서버 업데이트가 필요합니다. 이메일은 다운로드 링크를 공유하므로 첨부 파일 크기 제한을 받지 않습니다.
session/user-messages.jsonl은 메시지 ID, 발신자, 타임스탬프, 본문 및 기존 멀티모달 콘텐츠와 첨부 파일 참조를 보존합니다. 도구 이벤트나 일반 텍스트의 잘라내기 한도를 공유하지 않으며 압축된 요약이 원본 메시지를 대체하지 않습니다. session/chat.jsonl과 session/events.jsonl은 크기가 제한된 보조 진단 데이터입니다.
이 보고서는 사용자 메시지와 Beak의 기록을 조정합니다. session/user-messages-coverage.json과 매니페스트의 user_messages에는 종료 기간, 메시지 수, 알려진 시간 범위, 완전성 등이 기록됩니다. 오프라인 상태에서의 작업, 지원되지 않는 기록 API, 또는 복구 불가능한 기록은 읽을 수 있는 메시지를 유지하며, partial에는 그 이유가 기록됩니다. 업로드 제한을 초과하는 ZIP 파일은 사용자 메시지를 삭제하는 대신 명시적으로 실패 처리됩니다.
첨부 파일은 해당 파일의 내용을 다운로드하지 않고도 기존의 참조 정보와 메타데이터를 그대로 유지합니다. 메시지 내에 이미 존재하는 다중 모달 체계도 여전히 포함됩니다. 이 보고서는 다른 세션에서 나온 채팅 내용이나 Skill, Schema, MCP 패키지, 작업 디렉터리 파일 등을 활용하지 않습니다. 사용자 메시지 내보내기는 추가적인 LLM 요청 기록이 필요 없으며, 전체 제공자의 요청이나 시스템 팁이 포함된다는 의미도 없습니다.
CPU 사용량을 진단하기 위해, CPU Profile을 명시적으로 요청해야 합니다:
CPU Profile은 기본적으로 수집하지 않습니다. 1–30초를 지정할 수 있습니다. 샘플링은 Agent에 약간의 부하를 추가하므로 CPU 문제를 조사할 때만 활성화하세요.
또한 특정 카테고리를 명시적으로 제외할 수도 있습니다:
Collect a Bug Report for the current Session without environment variables or configuration snapshots.
보호된 방식으로 진단 보고서를 처리하기¶
Agent v0.16.0의 원본 내용이 포함된 depth 1/2 보고서를 obscli bug-report view로 보려면 obscli v0.16.0 이상을 사용하세요. 이전 뷰어는 이 보고서를 거부합니다. 새 뷰어는 기존의 마스킹된 보고서와 depth 3 보고서도 지원합니다.
Agent는 보고서의 config.toml(이전 설치에서는 agent.env)에 있는 민감한 값 할당만 마스킹합니다. 다른 환경 변수, 설정, 로그, 세션 콘텐츠 및 LLM 증거는 자격 증명을 검색하거나 문자열을 대체하지 않고 원본을 유지합니다. 버그 보고서에는 키, 토큰 및 개인 정보가 포함될 수 있습니다. 민감한 진단 데이터로 취급하세요.
보고서를 다운로드한 후:
- 오직 책임감 있는 인원만을 대상으로, 통제된 채널을 통해만 공유해야 합니다.
- 공개된 티켓, 공개된 코드 저장소, 또는 공개된 파일 공유 서비스에 업로드하지 마세요.
- 문제를 해결한 후 더 이상 필요하지 않은 로컬 사본들을 삭제합니다.
- 만약 세션에 수동으로 붙인 비밀번호, 토큰 또는 개인 정보가 포함되어 있다면, 전송하기 전에 수신자에게 알리고 조직의 데이터 처리 정책을 준수해야 합니다.
컬렉션의 문제 해결 또는 업로드 실패 시¶
승인이 아직 남아 있습니다.¶
표준 승인 모드는 만료되기 전에 승인이 필요합니다. 승인이 만료된 경우, 수집 요청을 다시 보내주세요.
만약 Agent가 YOLO/Full Access로 설정되어 있음에도 불구하고 승인을 요청하거나 approval_id is required for diagnostic assets를 보고하는 경우, Beak와 Agent도 최신 버전으로 업데이트한 후 다시 시도해 주세요.
또 다른 보고서가 이미 진행 중입니다.¶
각 Agent은 한 번에 하나의 버그 리포트만 수집할 수 있습니다. 현재 작업이 완료될 때까지 기다린 후 다시 시도하세요. 여러 세션에서 동시에 수집 작업을 시작하지 마세요.
보고서 상태는 부분적인 것입니다.¶
partial는 하나 이상의 진단 소스가 사용할 수 없었거나, 시간 초과되었거나, 보안 검사로 인해 제거된 것을 의미합니다. 나머지 콘텐츠는 여전히 업로드된 상태입니다. 누락된 항목에 대해서는 보고서를 확인해 보세요. 필수적인 콘텐츠가 누락된 경우, Agent 권한, 로그 파일, 네트워크 상태를 확인한 후 다시 다운로드하시기 바랍니다.
업로드 결과 창의 기한이 초과되었습니다.¶
이 오류는 Agent 버전이 수집과 업로드에 하나의 제한 시간을 공유할 때 발생할 수 있습니다. Agent를 최신 버전으로 업데이트하고 다시 시도하세요. 문제가 계속되면 Agent에서 Beak으로의 연결을 확인하고 Agent 로그 보기에 따라 최근 오류를 확인하세요.
진단 자산이 사용할 수 없습니다.¶
만약 페이지에 따르면 해당 서비스가 진단 자산을 지원하지 않는다고 보고된다면, Beak와 Agent가 호환 가능한 버전으로 업그레이드되었는지 확인하세요. 업그레이드 후에는 Agent를 다시 재시작하고, 원래의 세션에서 다시 수집 작업을 시작하세요.
이메일에는 다운로드 링크가 포함되어 있지 않습니다.¶
먼저, 세션에서 버그 리포트가 성공적으로 생성되었는지 확인하세요. 또한, 임시 다운로드 링크가 만료되지 않았는지도 확인해야 합니다. Agent에게 생성된 리포트를 다시 전송해달라고 요청하세요. 만약 이메일에 여전히 링크가 없다면, Agent를 업데이트하고 이메일 기능이 올바르게 구성되어 있는지 확인해야 합니다.
LLM 진단 데이터 기록¶
모델에게 전달되는 정확한 컨텍스트를 조사하기 위해, 이 값을 Agent의 config.toml에 명시적으로 설정해야 합니다(이전 버전의 설치 환경에서는 agent.env를 사용했습니다).
Agent를 다시 시작하세요. 이 옵션은 config.toml(이전 설치에서는 agent.env)에서만 읽습니다. 프로세스 환경에만 설정해도 기록이 활성화되지는 않습니다. 기본값은 0입니다.
| 深度 | 기록 및 전송된 콘텐츠 |
|---|---|
0 |
기존의 버그 리포트 콘텐츠는 추가적인 LLM 본문 기록 없이 존재합니다. |
1 |
각 세션의 세션, 라운드, 통화, 재시도, 목적, 시간 및 상태 정보입니다. |
2 |
세션 내에서 최근에 완료된 통화의 요청 및 응답 메타데이터를 포함한 정보를 전부 저장합니다. 이 정보는 원본 콘텐츠를 유지하며 내보낼 수 있습니다. |
3 |
첫 번째 호출부터 각 세션에 대한 원시 요청, 스트리밍된 응답, 파싱된 모델 결과, 그리고 도구 데이터를 포함합니다. |
온라인 수집 과정에서는 chat_depth=1 또는 chat_depth=2를 요청할 수 있으며, 기존의 승인 및 업로드 프로세스가 필요합니다. 기본값은 0입니다. 온라인 도구는 3 깊이를 거부합니다. 기록된 깊이보다 높은 깊이를 요청하면 requested_depth_not_recorded가 반환되며, ZIP 파일이 생성되지 않습니다. 설정을 증가시켜도 이전의 호출을 복구할 수 없습니다. 이 설정은 오래된 또는 부분적으로 기록된 세션의 커버리지를 보여줍니다.
로컬로 내보내기¶
이 명령을 Agent 호스트에서 실행하세요:
obs-agent --config /etc/obs-agent/config.toml --bug-report --depth=2 --bug-report-output /var/lib/obs-agent/reports/support.zip
명령은 로컬에 ZIP을 생성하고 status, 절대 경로인 path, size_bytes, sha256을 포함한 JSON 객체 하나를 표준 출력에 표시합니다. 부모 디렉터리가 있어야 하며 기존 파일은 덮어쓰지 않습니다. 보고서를 업로드하지 않으며 Agent 실행 중에도 사용할 수 있습니다.
통제된 로컬 품질 평가를 하려면 기록 깊이를 3으로 설정한 후 실행하세요.
obs-agent --config /etc/obs-agent/config.toml --bug-report --depth=3 --bug-report-output /var/lib/obs-agent/reports/support-UNREDACTED.zip
깊이 3 보고서는 매우 민감한 파일입니다. 마스킹되지 않은 업무 텍스트, 시스템 프롬프트, 추론, 도구 인수와 결과 및 모델에 실제로 전송한 인라인 멀티모달 데이터가 포함됩니다. 표준 오류 출력, 매니페스트 및 LLM 인덱스에 UNREDACTED로 표시됩니다. 출력 디렉터리 접근을 제한하고 보관, 전송 및 폐기를 통제하세요.
깊이 2는 기록된 요청과 응답의 원본을 유지합니다. 자격 증명 문자열이 있어도 내보내기를 막지 않습니다. ZIP 구조, JSON 유효성 및 기록 완전성 검사는 계속 적용됩니다. 전송 인증 헤더는 별도로 기록하지 않습니다. 별도 파일인 config.toml(이전 설치에서는 agent.env)의 민감한 값 할당만 마스킹합니다. env.json, config.json, 일반 로그, 런타임 메타데이터 및 기록된 LLM 콘텐츠는 원래 값을 유지합니다. 기록 파일은 0600 모드를 사용하며 세션 삭제 알림이 Agent에 도달하면 삭제됩니다. 깊이 3에는 호출 수, 본문 크기 또는 ZIP 크기 제한이 없습니다. 충분한 디스크 공간을 확보하세요.
수집을 시작할 때 Agent를 일시 중지하지 않고 스냅샷을 생성합니다. 진행 중인 호출은 이미 기록된 데이터를 유지하며 in_progress로 표시됩니다. 전체 기록 세션에 설명할 수 없는 공백이 있으면 불완전한 증거를 완전한 것처럼 제시하지 않고 recording_gap을 반환합니다.