에이전트 워크플로에는
--json을 사용하세요. 자격 증명은 보호된 로컬 설정에 보관하세요. 사람, 도구, 에이전트 사이에는 변수 이름만 전달하세요.시작하기 전에
다음을 준비하세요.- Node.js 18 이상
- LogBrew CLI v0.1.30 이상
jq- Bash 또는 Zsh
- 서버 측 Node.js 앱의 패키지 디렉터리
quickstart-node, 환경 development, 릴리스 quickstart@1을 사용합니다. 이 테스트는 프로덕션과 분리하세요. 다른 런타임은 SDK 연동을 참고하세요.
첫 로그 보내고 읽기
1
계정 상태 확인하기
CLI 사용하기의 명령어로 CLI를 설치하세요. 그다음 계정 상태를 확인하세요.확인: 상태에 인증된 계정 접근 권한이 표시됩니다. 표시되지 않으면 사람이
logbrew login을 한 번 실행합니다. 그다음 logbrew status --json을 다시 실행하세요. 현재 인증이 작동하면 에이전트는 새 로그인을 시작하면 안 됩니다.2
CLI로 프로젝트 1개 만들기
소유자만 접근할 수 있는 디렉터리에 새 파일 경로를 정하세요. CLI는 성공을 보고하기 전에 프로젝트 수집 키를 그 파일에 씁니다. 키나 파일 경로는 절대 출력하지 않습니다.프로젝트를 만들면 계정 상태가 바뀝니다. 대상 파일이 이미 있으면 안 됩니다. 결과가 분명하지 않으면 같은 명령어를 그대로 다시 실행하세요. CLI는 대기 중인 요청 식별 정보를 다시 사용합니다. 다른 시도를 시작할 때만
--abandon-retry를 사용하세요.확인: 출력에 status: "created", 설정 상태 created, 수집 키 종류가 표시됩니다. 프로젝트가 생겼고 키가 저장되었습니다. 이것만으로 텔레메트리가 전송된다는 것을 확인할 수는 없습니다. 프로젝트 및 설정을 참고하세요.3
Node.js SDK 설치하기
4
안전한 SDK 로그 1개 보내기
릴리스와 환경 마커를 자리표시자만 담은 이벤트에 자격 증명, 헤더, 요청 본문, 고객 데이터, 로컬 경로를 넣지 마세요.확인: 스크립트가
info 로그 1개와 함께 보내세요. 키는 이 Node.js 프로세스에서만 설정됩니다. 애플리케이션 식별 정보는 context에 넣습니다.실행할 때마다 새 이벤트 ID가 만들어집니다. 같은 실행 안에서 SDK가 전송을 재시도하면 같은 본문과 같은 ID를 보냅니다. 이미 접수된 이벤트를 재시도에서 다시 보내도 LogBrew는 그 이벤트를 다시 저장하지 않습니다.2xx status_code와 함께 "ok":true를 출력합니다. 재시도했다면 attempts가 1보다 큽니다. 전송 성공이 마지막 확인은 아닙니다.전송에 실패하면 스크립트는 코드 1로 종료하고 {"ok":false,"error":"unauthenticated"} 같은 짧은 JSON 오류를 출력합니다. 요청 본문이나 키는 출력하지 않습니다. 프로젝트 키가 거부되면 unauthenticated가 나옵니다. CLI에 새로 로그인해도 해결되지 않습니다.5
프로젝트 doctor 보고서 읽기
CLI는 이 조회에 저장된 계정 접근 권한을 사용합니다. 프로젝트 수집 키를 쓰지 마세요.확인: 보고서에
status: "ready"가 있습니다. checks의 각 항목도 읽으세요. 종료 코드 0은 모든 검사를 통과했다는 뜻이 아닙니다. 다른 상태라면 next와 doctor 보고서 레퍼런스를 따르세요. 프로젝트가 ready여도 이 테스트 로그가 도착했다는 뜻은 아닙니다.6
테스트 로그 읽기
SDK 배치의 프로젝트, 릴리스, 환경을 사용하세요.확인: 해당 프로젝트, 릴리스, 환경에
LogBrew quickstart check가 나타납니다. 이것은 테스트 로그가 전송되었다는 것만 보여 줍니다.테스트 결과 읽기
예제는 이벤트 3개를 보냅니다. 그중 로그는 1개뿐입니다. 릴리스와 환경 마커는 로그에 컨텍스트를 줍니다.
테스트 로그는
info로 두세요. 찾기 쉽게 하려고 error로 바꾸지 마세요. 대신 프로젝트와 시간 필터를 사용하세요. 심각도 값을 참고하세요.
console.log 줄은 전송 결과를 터미널에 출력합니다. client.log 호출은 로그를 LogBrew로 보냅니다. 첫 전송에 성공하면 다음이 출력됩니다.
--project 필터는 이벤트를 옮기지 않습니다.
예제가 요청 스팬을 만들지 않으므로 이 로그에는 트레이스 컨텍스트가 없습니다. 로그가 실패했다는 뜻은 아닙니다. CLI 조회는 그 시점의 스냅숏입니다. 나중에 들어온 이벤트를 읽으려면 다시 실행하거나, 실시간 스트림을 보려면 logbrew watch logs --json을 사용하세요.
자주 하는 복구 판단
텔레메트리가 여전히 보이지 않으면 첫 텔레메트리 확인을 진행하세요. 그래도 해결되지 않으면 문제 신고하세요. 자격 증명, 원시 텔레메트리, 고객 데이터, 로컬 경로, 소스 코드를 첨부하지 마세요.
애플리케이션에 적용하기
- 앱의 설정 코드에서 클라이언트를 한 번만 만드세요.
- 패키지 파일에서 SDK 버전을 고정하세요. 업그레이드는 프로덕션 밖에서 테스트하세요.
- 기존 시크릿 설정에서 수집 키를 불러오세요. 노출되었을 가능성이 있으면 키를 교체하세요. 수집 키 교체하기를 참고하세요.
- 배포 설정에서 바뀌지 않는 서비스, 환경, 릴리스 이름을 사용하세요. 릴리스를 참고하세요.
- 로그 메시지에는
Report generation completed처럼 작업과 결과를 적으세요. 메시지에 개인적인 값을 넣지 마세요. 요청 전체나 사용자 레코드 전체를 로그에 복사하지 마세요. - 중복 기록을 막으려면 애플리케이션 로그마다 보내는 곳을 하나만 두세요. LogBrew를 추가하기 전에 각 기록을 이미 보내고 있는 연동을 찾으세요.
- 프로덕션에 배포하기 전에 실제 코드 경로로 안전한 이벤트 1개를 보내고 다시 읽으세요. 메시지, 서비스, 릴리스, 환경을 확인하세요. 독립 실행 예제로는 애플리케이션의 코드 경로를 테스트할 수 없습니다.
프로젝트 및 설정
설정 상태를 확인하고 프로젝트 수집 키를 관리하세요.
SDK 연동
런타임에 맞는 SDK 패키지를 고르세요.
이슈 조사하기
이슈 1개의 트레이스와 관련 로그 근거를 따라가세요.
문제 신고
안전하고 비공개인 지원 보고서를 보내세요.
