> ## Documentation Index
> Fetch the complete documentation index at: https://docs.logbrew.co/llms.txt
> Use this file to discover all available pages before exploring further.

# 애플리케이션 텔레메트리를 위한 SDK 연동

> 런타임에 맞는 LogBrew SDK를 고르고 수집 키를 설정하세요. 애플리케이션 텔레메트리를 보내고 프로젝트에서 테스트 이벤트를 찾으세요.

런타임에 맞는 LogBrew SDK 패키지를 설치하세요. SDK는 이벤트를 정해진 형식으로 만들어 전송합니다. 각 패키지 가이드에는 이벤트 유형, 제한, 재시도 동작이 나와 있습니다.

연동할 때마다 다음 단계를 진행하세요.

1. 런타임에 맞는 SDK 패키지를 설치하세요.
2. 프로젝트 범위 수집 키를 소스 제어 밖에 보관하세요.
3. 바뀌지 않는 서비스, 환경, 릴리스 값을 설정하세요.
4. 애플리케이션에서 안전한 테스트 이벤트 1개를 보내세요.
5. 전송 결과를 확인하세요. 그다음 LogBrew에서 이벤트를 찾으세요.

배치가 접수되었다면 LogBrew API에 도착한 것입니다. 그래도 필터 때문에 이벤트가 보이지 않을 수 있습니다. 올바른 프로젝트와 기간을 선택하세요. 그다음 서비스, 환경, 릴리스, 시그널 유형을 맞추세요.

수집을 켜기 전에 [승인된 필드를 고르고 테스트하세요](/ko/guides/safe-capture). **분석**에 데이터를 채우려면 [제품 이벤트 수집](/ko/guides/product-events)을 따르세요.

## <span id="item-types">시그널과 공유 컨텍스트</span>

처음 5개 카드는 시그널입니다. 릴리스와 환경은 이 시그널의 컨텍스트입니다. 별도의 이벤트 유형이 아닙니다.

<CardGroup cols={2}>
  <Card title="log" icon="file-text">
    심각도, 출처, 시각, 안전한 컨텍스트가 있는 구조화된 메시지입니다.
  </Card>

  <Card title="trace_span" icon="route">
    시간을 잰 작업 1개입니다. 트레이스 ID와 스팬 ID로 트레이스에 연결됩니다.
  </Card>

  <Card title="issue" icon="bug">
    수집된 실패와 그 심각도, 앱이 보낸 오류 세부 정보입니다.
  </Card>

  <Card title="action" icon="mouse-pointer-click">
    앱에서 일어난 액션입니다. 선택적으로 주체, 세션, 안전한 속성을 담습니다.
  </Card>

  <Card title="metric" icon="chart-line">
    이름, 종류, 값, 단위, temporality가 있는 숫자 측정값 1개입니다.
  </Card>

  <Card title="release 및 environment" icon="tags">
    같은 SDK 범위에서 이후 이벤트에 붙는 코드 버전과 환경입니다.
  </Card>
</CardGroup>

## 심각도 값

로그와 이슈에는 `info`, `warning`, `error`, `critical`을 사용하세요. SDK와 런타임은 `trace`, `debug`, `warn`, `fatal` 같은 별칭을 보낼 수 있습니다. LogBrew는 허용된 별칭을 표준 값으로 정규화합니다.

## 패키지 관리자로 설치하기

텔레메트리를 보내는 런타임에 맞는 SDK 패키지를 설치하세요. LogBrew에서 받은 프로젝트 범위 SDK 설정 또는 수집 설정을 사용하세요. 계정 로그인 값을 SDK 설정으로 쓰지 마세요.

| 런타임 | 설치 |
| - | - |
| JavaScript | `npm install @logbrew/sdk` |
| 브라우저 | `npm install @logbrew/sdk @logbrew/browser` |
| Node.js | `npm install @logbrew/sdk @logbrew/node` |
| Express | `npm install @logbrew/sdk @logbrew/node @logbrew/express` |
| Fastify | `npm install @logbrew/sdk @logbrew/node @logbrew/fastify` |
| NestJS | `npm install @logbrew/sdk @logbrew/node @logbrew/nestjs` |
| React | `npm install @logbrew/sdk @logbrew/browser @logbrew/react` |
| Next.js | `npm install @logbrew/sdk @logbrew/node @logbrew/next` |
| Angular | `npm install @logbrew/sdk @logbrew/angular` |
| Vue | `npm install @logbrew/sdk @logbrew/vue` |
| Svelte | `npm install @logbrew/sdk @logbrew/browser @logbrew/svelte` |
| [React Native](/ko/guides/react-native) | `npm install @logbrew/sdk @logbrew/react-native` |
| Python | `python3 -m pip install logbrew-sdk` |
| FastAPI | `python3 -m pip install logbrew-fastapi` |
| Flask | `python3 -m pip install "logbrew-flask>=0.1.5,<0.2"` |
| Django | `python3 -m pip install logbrew-django` |
| Swift / Apple | SwiftPM으로 `https://github.com/LogBrewCo/sdk.git`을 추가하세요. |
| PHP | `composer require logbrew/sdk:^0.1.1` |
| Ruby | `gem install logbrew-sdk` |
| Go | `go get github.com/LogBrewCo/sdk/go/logbrew@latest` |
| Rust | `cargo add logbrew` |
| Java / Spring | Maven Central에서 `co.logbrew:logbrew-sdk:0.1.10`를 추가하세요. |
| .NET | `dotnet add package LogBrew --version 0.1.7` |
| ASP.NET Core | `dotnet add package LogBrew.AspNetCore --version 0.1.2` |
| C++ / CMake | CMake `FetchContent`로 `cpp/logbrew-cpp/v0.2.3`을 고정하세요. |

### 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 프로젝트를 감지합니다. 프로젝트 루트에서 설정 계획을 미리 보세요. 이 명령어는 파일을 바꾸지 않습니다.

```bash theme={null}
logbrew setup --json
```

계획은 배포된 호스트 연동 패키지를 설치합니다.

```bash theme={null}
dotnet add package LogBrew.AspNetCore --version 0.1.2
```

`LOGBREW_SERVER_API_KEY`, `LOGBREW_SERVICE_NAME`, `LOGBREW_ENVIRONMENT`, `LOGBREW_RELEASE`를 소스 제어 밖에서 설정하세요. 호스트에 LogBrew를 등록하고, 미들웨어는 라우팅 뒤에 두세요.

```csharp theme={null}
using LogBrew;

var builder = WebApplication.CreateBuilder(args);
builder.AddLogBrew();

var app = builder.Build();
app.UseRouting();
app.UseLogBrew();
app.MapGet("/", () => "ok");
app.Run();
```

`LOGBREW_SERVER_API_KEY`가 없으면 두 등록 호출은 아무것도 하지 않으며 안전합니다. [ASP.NET Core NuGet 패키지](https://www.nuget.org/packages/LogBrew.AspNetCore/0.1.2)에서 배포된 호스트 연동을 확인할 수 있습니다. 공개 패키지 가이드는 호스트 라이프사이클, 요청 수집, 이슈 수집, 개인정보 보호 제한, 복구를 다룹니다.

### Maven 또는 Gradle로 Java 연동하기

CLI v0.1.54 이상은 `pom.xml`, `build.gradle`, `build.gradle.kts`를 감지합니다. 프로젝트 루트에서 설정 계획을 미리 보세요. 이 명령어는 파일을 바꾸지 않습니다.

```bash theme={null}
logbrew setup --json
```

Maven에서는 배포된 패키지를 추가하세요.

```xml theme={null}
<dependency>
  <groupId>co.logbrew</groupId>
  <artifactId>logbrew-sdk</artifactId>
  <version>0.1.10</version>
</dependency>
```

Gradle Kotlin DSL에서는 같은 Maven Central 아티팩트를 추가하세요.

```kotlin theme={null}
implementation("co.logbrew:logbrew-sdk:0.1.10")
```

Java 11 이상을 사용하세요.

Spring Boot 3과 4 애플리케이션은 앱이 소유한 `LogBrewClient` 빈을 노출할 수 있습니다. 이 빈은 선택 사항인 요청, 예외, HTTP 클라이언트, JDBC, 캐시 연동을 켭니다.

Spring Kafka 수집은 `logbrew.kafka.enabled=true`로 명시적으로 켜야 합니다. 애플리케이션에 이미 있는 Spring Kafka 의존성과 클라이언트 빈을 사용합니다.

[Maven Central의 Java SDK 아티팩트](https://central.sonatype.com/artifact/co.logbrew/logbrew-sdk/0.1.10)에서 배포된 패키지를 확인할 수 있습니다. 공개 가이드는 제한이 있는 HTTP 전송, 종료, 로깅, Spring 설정, Kafka 연관 관계, 개인정보 보호 제한을 다룹니다.

### CMake로 C++ 연동하기

C++ SDK에는 C++17과 CMake 3.16 이상이 필요합니다. CLI v0.1.39 이상은 루트의 `CMakeLists.txt`를 감지합니다. 파일을 바꾸지 않고 이 설정 계획을 미리 보려면 `logbrew setup --json`을 실행하세요.

```cmake theme={null}
include(FetchContent)
FetchContent_Declare(
  logbrew
  GIT_REPOSITORY https://github.com/LogBrewCo/sdk.git
  GIT_TAG cpp/logbrew-cpp/v0.2.3
  GIT_SHALLOW TRUE
  SOURCE_SUBDIR cpp/logbrew-cpp
)
FetchContent_MakeAvailable(logbrew)

target_link_libraries(your_app PRIVATE LogBrew::LogBrew)
```

코어 타깃에는 의존성이 없습니다. 선택 사항인 libcurl 전송으로 배치를 보내려면 위의 마지막 `FetchContent_MakeAvailable` 호출과 타깃 링크를 다음으로 바꾸세요.

```cmake theme={null}
set(LOGBREW_BUILD_HTTP_TRANSPORT ON CACHE BOOL "" FORCE)
FetchContent_MakeAvailable(logbrew)
target_link_libraries(your_app PRIVATE LogBrew::HttpTransport)
```

애플리케이션을 구성하세요. 그다음 빌드해서 선택한 SDK 버전을 테스트하세요.

```bash theme={null}
cmake -S . -B build &&
cmake --build build
```

SDK 모노레포를 가져올 수 없는 빌드라면 [C++ 0.2.3 릴리스](https://github.com/LogBrewCo/sdk/releases/tag/cpp/logbrew-cpp/v0.2.3)의 `logbrew-cpp-0.2.3.tar.gz` 에셋을 사용하세요. 압축을 푼 패키지는 `cmake --install`과 `find_package(LogBrew 0.2.3 CONFIG REQUIRED)`를 지원합니다. 패키지 가이드는 타입이 있는 컨텍스트, 이슈 근거, 스팬 이벤트, 메트릭, 액션, HTTP 전송을 다룹니다.

### JavaScript 소스맵

Vite 빌드는 [JavaScript 소스맵](/ko/guides/source-maps)을 따르세요. 플러그인, 아티팩트 키, 업로드 확인, 원본 소스 위치가 표시되는 새 이슈를 다룹니다.

### Apple, Flask, React Native

텔레메트리에는 `LogBrew` Swift 제품을 사용하세요. `LogBrewCrash`는 Apple 크래시나 멈춤을 수집할 때만 추가하세요. dSYM 업로드와 호스팅 심볼리케이션은 [Apple 크래시와 멈춤](/ko/guides/apple-crashes-and-hangs) 가이드를 따르세요.

Flask는 [Flask](/ko/guides/flask) 가이드를 따르세요.

React Native와 Expo는 [React Native](/ko/guides/react-native)를 따르세요. 프로젝트 키, 안전한 테스트 로그, 전송 오류, 프로덕션 소스맵을 위한 Expo Metro 설정을 다룹니다.

## <span id="javascript-queue-tracing">JavaScript 큐 트레이싱</span>

Node 큐 연동은 별도의 npm 패키지입니다. LogBrew JavaScript 기본 패키지, 연동 패키지, 앱이 이미 쓰는 큐 또는 브로커 클라이언트를 설치하세요.

| 큐 또는 브로커 | 설치 |
| - | - |
| BullMQ | `npm install @logbrew/sdk @logbrew/node @logbrew/bullmq bullmq` |
| KafkaJS | `npm install @logbrew/sdk @logbrew/node @logbrew/kafkajs kafkajs` |
| RabbitMQ / amqplib | `npm install @logbrew/sdk @logbrew/node @logbrew/amqplib amqplib` |
| Amazon SQS | `npm install @logbrew/sdk @logbrew/node @logbrew/aws-sqs @aws-sdk/client-sqs` |

이 패키지는 직접 고른 큐 호출 주변에서 앱이 명시적으로 트레이스 연관 관계를 관리할 때 사용하세요. LogBrew는 브로커 연결을 소유하지 않고, 큐를 만들지 않으며, 기본적으로 모든 클라이언트를 전역으로 패치하지 않습니다.

<Warning>
  큐 페이로드, 임의의 메시지 헤더, 브로커 URL, 세션 또는 계정 bearer 값을 SDK 설정에 넣지 마세요. LogBrew에서 받은 프로젝트 범위 서버 수집 설정을 사용하세요.
</Warning>

## <span id="required-envelope-fields">네이티브 엔벨로프 직접 보내기</span>

`POST /api/telemetry/ingest`는 공개 LogBrew SDK가 지원하지 않는 커스텀 클라이언트에서만 사용하세요. 공개 SDK는 자체 배치 형식을 씁니다. 이 엔드포인트는 그 형식을 받지 않습니다.

네이티브 엔벨로프 1개에 항목을 1개에서 512개까지 보내세요. 엔벨로프 1개에 든 모든 항목은 프로젝트, 서비스, 릴리스, 환경, 선택 사항인 트레이스 컨텍스트를 공유합니다.

| 필드 | 필수 | 참고 |
| - | - | - |
| `project_id` | 예 | LogBrew 프로젝트의 UUID입니다. 수집 키의 프로젝트와 일치해야 합니다. |
| `environment` | 예 | 배포 환경입니다. 64자 이하이며 공백, `/`, `\`를 넣을 수 없습니다. `None` 값은 거부됩니다. |
| `release` | 예 | 코드 버전입니다. 200자 이하이며 `/`, `\`, 탭, 줄바꿈을 넣을 수 없습니다. `.`이나 `..`일 수 없습니다. |
| `service_name` | 예 | `checkout-api` 같은 논리적 서비스 이름입니다. 비워 둘 수 없습니다. |
| `sdk_name` | 예 | SDK 또는 커스텀 클라이언트 식별자입니다. |
| `sdk_version` | 예 | SDK 또는 커스텀 클라이언트 버전입니다. |
| `items` | 예 | `log`, `trace_span`, `issue`, `action` 항목 1개에서 512개입니다. |
| `trace_id` | 아니요 | 연관된 엔벨로프 항목이 공유하는 트레이스 ID입니다. 항목에 `span_id`가 있으면 필수입니다. |

### 항목 필드

각 항목에는 `type`과 `data` 객체가 있습니다. 로그 항목은 `level`을 씁니다. 이슈 항목은 `severity`를 씁니다. 둘 다 [심각도 값](/ko/concepts/telemetry#severity-values)에 나온 값을 받습니다.

| 항목 필드 | 적용 대상 | 참고 |
| - | - | - |
| `id` | 모든 항목 | 선택 사항인 클라이언트 이벤트 ID입니다. 1자에서 200자이며 엔벨로프 안에서 고유해야 합니다. |
| `span_id` | `log`, `issue`, `action` | 선택 사항입니다. 16진수 16자이며 모두 0일 수 없습니다. 엔벨로프에 `trace_id`가 있어야 합니다. |
| `name` | `action` | 필수입니다. UTF-8 기준 64바이트 이하입니다. `$`로 시작하거나, 공백으로 시작하거나 끝나거나, 제어 문자나 보이지 않는 서식 문자를 포함할 수 없습니다. |

클라이언트가 재시도할 수 있다면 항목마다 `id`를 보내세요. 이미 접수된 항목을 재시도에서 같은 `id`와 내용으로 다시 보내면, LogBrew는 그 항목을 다시 저장하지 않습니다. 응답은 그 항목을 `already_accepted`에 셉니다.

### 요청 예시

아래 JSON을 `telemetry-envelope.json`으로 저장하세요. 예시 프로젝트 ID를 수집 키의 정확한 프로젝트 ID로 바꾸세요. 타임스탬프는 테스트 이벤트의 현재 UTC 시각으로 설정하세요. 서비스와 릴리스 값은 직접 정한 값을 쓰세요.

```json telemetry-envelope.json theme={null}
{
  "project_id": "11111111-1111-4111-8111-111111111111",
  "environment": "production",
  "release": "api@1.2.3",
  "service_name": "checkout-api",
  "sdk_name": "custom-native-client",
  "sdk_version": "1.0.0",
  "items": [
    {
      "type": "log",
      "data": {
        "id": "evt_example_log_0001",
        "level": "warning",
        "message": "checkout retry scheduled",
        "source": "runtime",
        "attributes": { "route": "/checkout" },
        "occurred_at": "2026-06-01T12:00:00Z"
      }
    },
    {
      "type": "action",
      "data": {
        "id": "evt_example_action_0001",
        "name": "checkout_failed",
        "distinct_id": "user_123",
        "session_id": "session_456",
        "occurred_at": "2026-06-01T12:00:00Z",
        "properties": { "cart_total": 4200 }
      }
    }
  ]
}
```

보호된 설정을 통해 프로젝트 범위 수집 값을 `LOGBREW_INGEST_BEARER`에 넣으세요. 이 값을 출력하거나 계정 자격 증명을 쓰지 마세요. 다음 명령어는 파일을 한 번 보냅니다. curl 7.76.0 이상이 필요합니다.

```bash theme={null}
: "${LOGBREW_INGEST_BEARER:?load the project-scoped ingest key}" &&
curl --fail-with-body --silent --show-error \
  "https://api.logbrew.co/api/telemetry/ingest" \
  -H "Authorization: Bearer $LOGBREW_INGEST_BEARER" \
  -H "Content-Type: application/json" \
  --data-binary @telemetry-envelope.json \
  --write-out '\nHTTP %{http_code}\n'
```

HTTP 상태와 본문을 읽으세요. `--fail-with-body`는 오류 본문을 그대로 남기고, HTTP 오류일 때 0이 아닌 종료 상태를 반환합니다. 네트워크 실패나 시간 초과만으로는 LogBrew가 요청을 접수했는지 알 수 없습니다. 항목에 `id` 값이 있을 때만 같은 파일을 다시 보내세요. `id` 값 없이 다시 보내면 항목이 2번 저장될 수 있습니다.

### 응답

요청에 성공하면 `200`과 함께 스트림별 새 항목 수가 반환됩니다. `already_accepted`는 이전 요청에서 이미 전달된 항목 수입니다.

```json theme={null}
{
  "issues": 0,
  "logs": 1,
  "trace_spans": 0,
  "actions": 1,
  "already_accepted": 0,
  "next": "review accepted telemetry in logs, issues, traces, actions, or live feed",
  "next_action": {
    "code": "review_ingested_telemetry",
    "target": "telemetry_reads"
  }
}
```

### 오류

유효하지 않거나 해지된 수집 키는 `401`을 반환합니다. 다른 프로젝트의 키도 `401`을 반환합니다.

```json theme={null}
{
  "error": "Invalid ingest key",
  "code": "ingest_key_invalid",
  "next": "create a project-scoped ingest key, then retry ingestion with that key",
  "next_action": {
    "code": "configure_ingest_key",
    "target": "project_ingest_key"
  }
}
```

프로젝트 범위 수집 키를 사용하세요. 계정 자격 증명으로 대신하지 마세요. 아티팩트 키로는 텔레메트리를 보낼 수 없습니다.

필드 규칙을 어긴 엔벨로프는 `422`와 코드 `validation_failed`를 반환합니다. `error` 필드는 어긴 규칙을 알려 줍니다. `next` 필드는 요청을 고치는 방법을 알려 줍니다. 예를 들어 `"items": []`는 다음을 반환합니다.

```json theme={null}
{
  "error": "native telemetry envelope cannot be empty",
  "code": "validation_failed",
  "next": "send at least one native telemetry item",
  "next_action": {
    "code": "fix_request",
    "target": "request"
  }
}
```

이벤트가 없으면 엔벨로프를 보내지 마세요. 항목이 512개를 넘는 엔벨로프는 `422`와 오류 `native telemetry envelope exceeds the item limit`을 반환합니다. 512개 이하 항목으로 배치를 나누세요. 각 배치에 프로젝트와 공유 컨텍스트를 그대로 넣으세요.

사용량 한도, 속도 제한, 서비스 장애는 [API 오류](/ko/reference/api-errors)에서 반환된 `code`를 따르세요.

<Tip>
  SDK 설정에서 릴리스와 환경을 설정하세요. 작업마다 트레이스 컨텍스트를 만들거나 이어 가세요. 관련 없는 작업에 트레이스 ID 하나를 다시 쓰지 마세요.
</Tip>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.