- 런타임에 맞는 SDK 패키지를 설치하세요.
- 프로젝트 범위 수집 키를 소스 제어 밖에 보관하세요.
- 바뀌지 않는 서비스, 환경, 릴리스 값을 설정하세요.
- 애플리케이션에서 안전한 테스트 이벤트 1개를 보내세요.
- 전송 결과를 확인하세요. 그다음 LogBrew에서 이벤트를 찾으세요.
시그널과 공유 컨텍스트
처음 5개 카드는 시그널입니다. 릴리스와 환경은 이 시그널의 컨텍스트입니다. 별도의 이벤트 유형이 아닙니다.log
심각도, 출처, 시각, 안전한 컨텍스트가 있는 구조화된 메시지입니다.
trace_span
시간을 잰 작업 1개입니다. 트레이스 ID와 스팬 ID로 트레이스에 연결됩니다.
issue
수집된 실패와 그 심각도, 앱이 보낸 오류 세부 정보입니다.
action
앱에서 일어난 액션입니다. 선택적으로 주체, 세션, 안전한 속성을 담습니다.
metric
이름, 종류, 값, 단위, temporality가 있는 숫자 측정값 1개입니다.
release 및 environment
같은 SDK 범위에서 이후 이벤트에 붙는 코드 버전과 환경입니다.
심각도 값
로그와 이슈에는info, warning, error, critical을 사용하세요. SDK와 런타임은 trace, debug, warn, fatal 같은 별칭을 보낼 수 있습니다. LogBrew는 허용된 별칭을 표준 값으로 정규화합니다.
패키지 관리자로 설치하기
텔레메트리를 보내는 런타임에 맞는 SDK 패키지를 설치하세요. LogBrew에서 받은 프로젝트 범위 SDK 설정 또는 수집 설정을 사용하세요. 계정 로그인 값을 SDK 설정으로 쓰지 마세요.Node.js 요청 트레이싱
요청 루트 트레이스 연관 관계를 쓰려면@logbrew/sdk 0.1.16 이상과 @logbrew/node 0.1.11 이상을 사용하세요.
Express에는 @logbrew/express 0.1.5 이상이 필요합니다. Fastify와 NestJS에는 각 LogBrew 패키지 0.1.6 이상이 필요합니다.
이 연동은 요청 스팬 1개를 만들거나 이어 갑니다. 스팬 이름에는 일치한 라우트 템플릿을 씁니다. 요청 안에서 생긴 로그, 이슈, 액션, 메트릭은 그 요청의 트레이스와 스팬 컨텍스트를 이어받습니다. 패키지를 새 버전으로 올려도 업그레이드 전에 보낸 이벤트에는 컨텍스트가 추가되지 않습니다.
기본 요청 연동은 요청이나 응답 본문, 쿼리 문자열, 임의의 헤더, 원본 traceparent 값을 수집하지 않습니다.
ASP.NET Core
CLI v0.1.55 이상은Microsoft.NET.Sdk.Web을 쓰는 .NET 10 프로젝트를 감지합니다. 프로젝트 루트에서 설정 계획을 미리 보세요. 이 명령어는 파일을 바꾸지 않습니다.
LOGBREW_SERVER_API_KEY, LOGBREW_SERVICE_NAME, LOGBREW_ENVIRONMENT, LOGBREW_RELEASE를 소스 제어 밖에서 설정하세요. 호스트에 LogBrew를 등록하고, 미들웨어는 라우팅 뒤에 두세요.
LOGBREW_SERVER_API_KEY가 없으면 두 등록 호출은 아무것도 하지 않으며 안전합니다. ASP.NET Core NuGet 패키지에서 배포된 호스트 연동을 확인할 수 있습니다. 공개 패키지 가이드는 호스트 라이프사이클, 요청 수집, 이슈 수집, 개인정보 보호 제한, 복구를 다룹니다.
Maven 또는 Gradle로 Java 연동하기
CLI v0.1.54 이상은pom.xml, build.gradle, build.gradle.kts를 감지합니다. 프로젝트 루트에서 설정 계획을 미리 보세요. 이 명령어는 파일을 바꾸지 않습니다.
LogBrewClient 빈을 노출할 수 있습니다. 이 빈은 선택 사항인 요청, 예외, HTTP 클라이언트, JDBC, 캐시 연동을 켭니다.
Spring Kafka 수집은 logbrew.kafka.enabled=true로 명시적으로 켜야 합니다. 애플리케이션에 이미 있는 Spring Kafka 의존성과 클라이언트 빈을 사용합니다.
Maven Central의 Java SDK 아티팩트에서 배포된 패키지를 확인할 수 있습니다. 공개 가이드는 제한이 있는 HTTP 전송, 종료, 로깅, Spring 설정, Kafka 연관 관계, 개인정보 보호 제한을 다룹니다.
CMake로 C++ 연동하기
C++ SDK에는 C++17과 CMake 3.16 이상이 필요합니다. CLI v0.1.39 이상은 루트의CMakeLists.txt를 감지합니다. 파일을 바꾸지 않고 이 설정 계획을 미리 보려면 logbrew setup --json을 실행하세요.
FetchContent_MakeAvailable 호출과 타깃 링크를 다음으로 바꾸세요.
logbrew-cpp-0.2.3.tar.gz 에셋을 사용하세요. 압축을 푼 패키지는 cmake --install과 find_package(LogBrew 0.2.3 CONFIG REQUIRED)를 지원합니다. 패키지 가이드는 타입이 있는 컨텍스트, 이슈 근거, 스팬 이벤트, 메트릭, 액션, HTTP 전송을 다룹니다.
JavaScript 소스맵
Vite 빌드는 JavaScript 소스맵을 따르세요. 플러그인, 아티팩트 키, 업로드 확인, 원본 소스 위치가 표시되는 새 이슈를 다룹니다.Apple, Flask, React Native
텔레메트리에는LogBrew Swift 제품을 사용하세요. LogBrewCrash는 Apple 크래시나 멈춤을 수집할 때만 추가하세요. dSYM 업로드와 호스팅 심볼리케이션은 Apple 크래시와 멈춤 가이드를 따르세요.
Flask는 Flask 가이드를 따르세요.
React Native와 Expo는 React Native를 따르세요. 프로젝트 키, 안전한 테스트 로그, 전송 오류, 프로덕션 소스맵을 위한 Expo Metro 설정을 다룹니다.
JavaScript 큐 트레이싱
Node 큐 연동은 별도의 npm 패키지입니다. LogBrew JavaScript 기본 패키지, 연동 패키지, 앱이 이미 쓰는 큐 또는 브로커 클라이언트를 설치하세요.
이 패키지는 직접 고른 큐 호출 주변에서 앱이 명시적으로 트레이스 연관 관계를 관리할 때 사용하세요. LogBrew는 브로커 연결을 소유하지 않고, 큐를 만들지 않으며, 기본적으로 모든 클라이언트를 전역으로 패치하지 않습니다.
네이티브 엔벨로프 직접 보내기
POST /api/telemetry/ingest는 공개 LogBrew SDK가 지원하지 않는 커스텀 클라이언트에서만 사용하세요. 공개 SDK는 자체 배치 형식을 씁니다. 이 엔드포인트는 그 형식을 받지 않습니다.
네이티브 엔벨로프 1개에 항목을 1개에서 512개까지 보내세요. 엔벨로프 1개에 든 모든 항목은 프로젝트, 서비스, 릴리스, 환경, 선택 사항인 트레이스 컨텍스트를 공유합니다.
항목 필드
각 항목에는type과 data 객체가 있습니다. 로그 항목은 level을 씁니다. 이슈 항목은 severity를 씁니다. 둘 다 심각도 값에 나온 값을 받습니다.
클라이언트가 재시도할 수 있다면 항목마다
id를 보내세요. 이미 접수된 항목을 재시도에서 같은 id와 내용으로 다시 보내면, LogBrew는 그 항목을 다시 저장하지 않습니다. 응답은 그 항목을 already_accepted에 셉니다.
요청 예시
아래 JSON을telemetry-envelope.json으로 저장하세요. 예시 프로젝트 ID를 수집 키의 정확한 프로젝트 ID로 바꾸세요. 타임스탬프는 테스트 이벤트의 현재 UTC 시각으로 설정하세요. 서비스와 릴리스 값은 직접 정한 값을 쓰세요.
telemetry-envelope.json
LOGBREW_INGEST_BEARER에 넣으세요. 이 값을 출력하거나 계정 자격 증명을 쓰지 마세요. 다음 명령어는 파일을 한 번 보냅니다. curl 7.76.0 이상이 필요합니다.
--fail-with-body는 오류 본문을 그대로 남기고, HTTP 오류일 때 0이 아닌 종료 상태를 반환합니다. 네트워크 실패나 시간 초과만으로는 LogBrew가 요청을 접수했는지 알 수 없습니다. 항목에 id 값이 있을 때만 같은 파일을 다시 보내세요. id 값 없이 다시 보내면 항목이 2번 저장될 수 있습니다.
응답
요청에 성공하면200과 함께 스트림별 새 항목 수가 반환됩니다. already_accepted는 이전 요청에서 이미 전달된 항목 수입니다.
오류
유효하지 않거나 해지된 수집 키는401을 반환합니다. 다른 프로젝트의 키도 401을 반환합니다.
422와 코드 validation_failed를 반환합니다. error 필드는 어긴 규칙을 알려 줍니다. next 필드는 요청을 고치는 방법을 알려 줍니다. 예를 들어 "items": []는 다음을 반환합니다.
422와 오류 native telemetry envelope exceeds the item limit을 반환합니다. 512개 이하 항목으로 배치를 나누세요. 각 배치에 프로젝트와 공유 컨텍스트를 그대로 넣으세요.
사용량 한도, 속도 제한, 서비스 장애는 API 오류에서 반환된 code를 따르세요.
