> ## 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.

# Integracja SDK do telemetrii aplikacji

> Wybierz SDK LogBrew dla swojego środowiska uruchomieniowego. Skonfiguruj klucz wysyłania. Wyślij telemetrię i znajdź zdarzenie testowe w projekcie.

Zainstaluj pakiet SDK LogBrew dla swojego środowiska uruchomieniowego. SDK
formatuje zdarzenia i je dostarcza. Przewodnik pakietu opisuje jego typy
zdarzeń, limity i sposób ponawiania.

Wykonaj te kroki dla każdej integracji:

1. Zainstaluj pakiet SDK dla swojego środowiska uruchomieniowego.
2. Przechowuj klucz wysyłania przypisany do projektu poza systemem kontroli
   wersji.
3. Ustaw stałe wartości usługi, środowiska i wydania.
4. Wyślij z aplikacji jedno bezpieczne zdarzenie testowe.
5. Odczytaj wynik dostarczenia. Następnie znajdź zdarzenie w LogBrew.

Przyjęta paczka dotarła do API LogBrew. Filtry nadal mogą ukrywać jej
zdarzenia. Wybierz właściwy projekt i zakres czasu. Następnie dopasuj usługę,
środowisko, wydanie i typ sygnału.

Zanim włączysz rejestrowanie, [wybierz i przetestuj zatwierdzone pola](/pl/guides/safe-capture).
Aby zasilić danymi widok „Analityka”, wykonaj kroki z przewodnika
[Rejestrowanie zdarzeń produktowych](/pl/guides/product-events).

## <span id="item-types">Sygnały i wspólny kontekst</span>

Pierwszych pięć kart opisuje sygnały. Wydanie i środowisko to kontekst tych sygnałów.
Nie są osobnym typem zdarzenia.

<CardGroup cols={2}>
  <Card title="log" icon="file-text">
    Ustrukturyzowany komunikat z poziomem ważności, źródłem, czasem i
    bezpiecznym kontekstem.
  </Card>

  <Card title="trace_span" icon="route">
    Jedna mierzona operacja powiązana ze swoim śladem przez ID śladu i spanu.
  </Card>

  <Card title="issue" icon="bug">
    Zarejestrowany błąd, jego poziom ważności i szczegóły błędu wysłane przez
    aplikację.
  </Card>

  <Card title="action" icon="mouse-pointer-click">
    Akcja w twojej aplikacji z opcjonalnym podmiotem, sesją i bezpiecznymi
    właściwościami.
  </Card>

  <Card title="metric" icon="chart-line">
    Jeden pomiar liczbowy z nazwą, rodzajem, wartością, jednostką i
    temporalnością.
  </Card>

  <Card title="release i environment" icon="tags">
    Wersja kodu i środowisko dołączane do późniejszych zdarzeń w tym samym
    zakresie SDK.
  </Card>
</CardGroup>

## Wartości ważności

Dla logów i problemów używaj `info`, `warning`, `error` lub `critical`.
Zestawy SDK i środowiska uruchomieniowe mogą wysyłać aliasy, takie jak
`trace`, `debug`, `warn` lub `fatal`. LogBrew zamienia przyjęte aliasy na
wartości kanoniczne.

## Instalacja przez menedżer pakietów

Zainstaluj pakiet SDK dla środowiska uruchomieniowego, które wysyła
telemetrię. Użyj konfiguracji SDK lub konfiguracji wysyłania z LogBrew
przypisanej do projektu. Nie używaj danych logowania do konta jako
konfiguracji SDK.

| Środowisko uruchomieniowe | Instalacja |
| - | - |
| JavaScript | `npm install @logbrew/sdk` |
| Przeglądarka | `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](/pl/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 | Dodaj `https://github.com/LogBrewCo/sdk.git` przez SwiftPM. |
| 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 | Dodaj `co.logbrew:logbrew-sdk:0.1.10` z Maven Central. |
| .NET | `dotnet add package LogBrew --version 0.1.7` |
| ASP.NET Core | `dotnet add package LogBrew.AspNetCore --version 0.1.2` |
| C++ / CMake | Przypnij `cpp/logbrew-cpp/v0.2.3` za pomocą `FetchContent` w CMake. |

### Śledzenie żądań w Node.js

Do korelacji śladów, w których spanem głównym jest żądanie, użyj
`@logbrew/sdk` 0.1.16 lub nowszego i `@logbrew/node` 0.1.11 lub nowszego.

Express wymaga `@logbrew/express` 0.1.5 lub nowszego. Fastify i NestJS
wymagają swojego pakietu LogBrew w wersji 0.1.6 lub nowszej.

Te integracje tworzą lub kontynuują jeden span żądania. Nazwa spanu to
dopasowany szablon trasy. Logi, problemy, akcje i metryki w ramach żądania
dziedziczą jego kontekst śladu i spanu. Nowszy pakiet nie dodaje kontekstu do
zdarzeń wysłanych przed aktualizacją.

Domyślna integracja żądań nie rejestruje treści żądań ani odpowiedzi, ciągów
zapytań, dowolnych nagłówków ani surowych wartości `traceparent`.

### ASP.NET Core

CLI w wersji 0.1.55 lub nowszej wykrywa projekty .NET 10, które używają
`Microsoft.NET.Sdk.Web`. Wyświetl podgląd planu konfiguracji z katalogu
głównego projektu. To polecenie nie zmienia twoich plików:

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

Plan dla opublikowanej wersji instaluje integrację z hostem:

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

Ustaw `LOGBREW_SERVER_API_KEY`, `LOGBREW_SERVICE_NAME`,
`LOGBREW_ENVIRONMENT` i `LOGBREW_RELEASE` poza systemem kontroli wersji.
Zarejestruj LogBrew w hoście i umieść jego middleware po routingu:

```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();
```

Bez `LOGBREW_SERVER_API_KEY` oba wywołania rejestrujące bezpiecznie nic nie
robią.
[Pakiet NuGet ASP.NET Core](https://www.nuget.org/packages/LogBrew.AspNetCore/0.1.2)
wskazuje opublikowaną integrację z hostem. Jego publiczny przewodnik opisuje
cykl życia hosta, rejestrowanie żądań, rejestrowanie problemów, ograniczenia
prywatności i odzyskiwanie po błędach.

### Java: Maven lub Gradle

CLI w wersji 0.1.54 lub nowszej wykrywa `pom.xml`, `build.gradle` i
`build.gradle.kts`. Wyświetl podgląd planu konfiguracji z katalogu głównego
projektu. To polecenie nie zmienia twoich plików:

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

W Mavenie dodaj opublikowany pakiet:

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

W Gradle Kotlin DSL dodaj ten sam artefakt z Maven Central:

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

Użyj Javy 11 lub nowszej.

Aplikacje Spring Boot 3 i 4 mogą udostępnić własny bean `LogBrewClient`.
Włącza on opcjonalne integracje żądań, wyjątków, klienta HTTP, JDBC i pamięci
podręcznej.

Rejestrowanie Spring Kafka trzeba jawnie włączyć ustawieniem
`logbrew.kafka.enabled=true`. Korzysta ono z istniejącej w aplikacji
zależności Spring Kafka i beana klienta.

[Artefakt Java SDK w Maven Central](https://central.sonatype.com/artifact/co.logbrew/logbrew-sdk/0.1.10)
wskazuje opublikowany pakiet. Jego publiczny przewodnik opisuje dostarczanie
przez HTTP z limitami, zamykanie, logowanie, konfigurację Springa, korelację
Kafka i ograniczenia prywatności.

### C++ z CMake

SDK dla C++ wymaga C++17 i CMake 3.16 lub nowszego. CLI w wersji 0.1.39 lub
nowszej wykrywa `CMakeLists.txt` w katalogu głównym. Uruchom
`logbrew setup --json`, aby wyświetlić podgląd tego planu konfiguracji bez
zmieniania plików:

```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)
```

Główny target nie ma zależności. Aby wysyłać paczki przez opcjonalny
transport libcurl, zastąp końcowe wywołanie `FetchContent_MakeAvailable` i
powyższe linkowanie targetu tym kodem:

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

Skonfiguruj aplikację. Następnie zbuduj ją, aby przetestować wybraną wersję
SDK:

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

Jeśli build nie może pobrać monorepo SDK, użyj osobnego pliku
`logbrew-cpp-0.2.3.tar.gz` z
[wydania C++ 0.2.3](https://github.com/LogBrewCo/sdk/releases/tag/cpp/logbrew-cpp/v0.2.3).
Rozpakowany pakiet obsługuje `cmake --install` i
`find_package(LogBrew 0.2.3 CONFIG REQUIRED)`. Jego przewodnik opisuje
typowany kontekst, dowody problemów, zdarzenia spanów, metryki, akcje i
dostarczanie przez HTTP.

### Mapy źródeł JavaScript

Dla buildów Vite wykonaj kroki z przewodnika
[Mapy źródeł JavaScript](/pl/guides/source-maps). Opisuje on
wtyczkę, klucz artefaktów, sprawdzanie przesyłania i nowy problem z
oryginalnymi lokalizacjami w kodzie źródłowym.

### Apple, Flask i React Native

Do telemetrii użyj produktu Swift `LogBrew`. Dodaj `LogBrewCrash` tylko do
rejestrowania awarii lub zawieszeń na platformach Apple. Przesyłanie plików
dSYM i hostowaną symbolizację opisuje przewodnik
[Awarie i zawieszenia Apple](/pl/guides/apple-crashes-and-hangs).

Dla Flaska wykonaj kroki z przewodnika [Flask](/pl/guides/flask).

Dla React Native i Expo wykonaj kroki z przewodnika
[React Native](/pl/guides/react-native). Opisuje on klucz projektu, bezpieczny
log testowy, błędy dostarczania i konfigurację Expo Metro dla produkcyjnych
map źródeł (source maps).

## <span id="javascript-queue-tracing">Śledzenie kolejek w JavaScript</span>

Integracje kolejek dla Node to osobne pakiety npm. Zainstaluj podstawowe
pakiety JavaScript LogBrew, pakiet integracji i klienta kolejki lub brokera,
którego twoja aplikacja już używa.

| Kolejka lub broker | Instalacja |
| - | - |
| 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` |

Używaj tych pakietów do jawnej korelacji śladów wokół wybranych wywołań
kolejki. Tę korelację kontroluje aplikacja. LogBrew nie zarządza połączeniem z
brokerem, nie tworzy kolejek i domyślnie nie modyfikuje globalnie każdego
klienta.

<Warning>
  Nie umieszczaj w konfiguracji SDK treści wiadomości z kolejki, dowolnych
  nagłówków wiadomości, adresów URL brokerów ani tokenów sesji lub konta
  (bearer). Użyj serwerowej konfiguracji wysyłania z LogBrew przypisanej do
  projektu.
</Warning>

## <span id="required-envelope-fields">Bezpośrednie wysyłanie natywnej koperty</span>

`POST /api/telemetry/ingest` jest tylko dla własnych klientów, dla których nie
ma publicznego SDK LogBrew. Publiczne zestawy SDK używają własnego formatu
paczek. Ten endpoint nie przyjmuje tego formatu.

W jednej natywnej kopercie wyślij od 1 do 512 elementów. Wszystkie elementy w
jednej kopercie mają wspólny projekt, usługę, wydanie, środowisko i
opcjonalny kontekst śladu.

| Pole | Wymagane | Uwagi |
| - | - | - |
| `project_id` | Tak | UUID projektu LogBrew. Musi pasować do projektu klucza wysyłania. |
| `environment` | Tak | Środowisko wdrożenia. Najwyżej 64 znaki, bez białych znaków, `/` i `\`. Wartość `None` jest odrzucana. |
| `release` | Tak | Wersja kodu. Najwyżej 200 znaków, bez `/`, `\`, tabulatorów i znaków nowego wiersza. Nie może mieć wartości `.` ani `..`. |
| `service_name` | Tak | Logiczna nazwa usługi, na przykład `checkout-api`. Nie może być pusta. |
| `sdk_name` | Tak | Identyfikator SDK lub własnego klienta. |
| `sdk_version` | Tak | Wersja SDK lub własnego klienta. |
| `items` | Tak | Od 1 do 512 elementów `log`, `trace_span`, `issue` lub `action`. |
| `trace_id` | Nie | ID śladu wspólne dla skorelowanych elementów koperty. Wymagane, gdy element ma `span_id`. |

### Pola elementów

Każdy element ma `type` i obiekt `data`. Element logu używa `level`. Element
problemu używa `severity`. Oba przyjmują wartości opisane w sekcji
[Wartości ważności](/pl/concepts/telemetry#severity-values).

| Pole elementu | Dotyczy | Uwagi |
| - | - | - |
| `id` | Wszystkich elementów | Opcjonalne ID zdarzenia nadane przez klienta. Od 1 do 200 znaków, unikalne w kopercie. |
| `span_id` | `log`, `issue`, `action` | Opcjonalne. 16 znaków szesnastkowych, nie same zera. Koperta musi mieć `trace_id`. |
| `name` | `action` | Wymagane. Najwyżej 64 bajty UTF-8. Nie może zaczynać się od `$` ani zaczynać lub kończyć białym znakiem. Nie może też zawierać znaków sterujących ani niewidocznych znaków formatowania. |

Jeśli twój klient może ponawiać wysyłkę, wysyłaj `id` z każdym elementem. Gdy
ponowienie wyśle przyjęty już element z tym samym `id` i tą samą treścią,
LogBrew nie zapisze go drugi raz. Odpowiedź policzy ten element w
`already_accepted`.

### Przykładowe żądanie

Zapisz poniższy JSON jako `telemetry-envelope.json`. Zastąp przykładowe ID
projektu dokładnym ID projektu twojego klucza wysyłania. Ustaw znaczniki czasu
na bieżący czas UTC zdarzenia testowego. Użyj własnych wartości usługi i
wydania.

```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 }
      }
    }
  ]
}
```

Wczytaj wartość klucza wysyłania projektu do `LOGBREW_INGEST_BEARER` z
chronionej konfiguracji. Nie wypisuj jej i nie używaj poświadczenia konta.
Poniższe polecenie wysyła plik jeden raz. Wymaga curl 7.76.0 lub nowszego:

```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'
```

Odczytaj status HTTP i treść odpowiedzi. `--fail-with-body` zachowuje treść
błędu i przy błędach HTTP zwraca niezerowy kod wyjścia. Błąd sieci lub
przekroczenie limitu czasu nie mówi, czy LogBrew przyjął żądanie. Wyślij ten
sam plik ponownie tylko wtedy, gdy jego elementy mają wartości `id`. Bez
wartości `id` drugie wysłanie może zapisać elementy dwa razy.

### Odpowiedź

Udane żądanie zwraca `200` z liczbą nowych elementów w każdym strumieniu.
`already_accepted` liczy elementy, które dostarczyło już wcześniejsze żądanie.

```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"
  }
}
```

### Błędy

Nieprawidłowy lub unieważniony klucz wysyłania zwraca `401`. Klucz innego
projektu też zwraca `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"
  }
}
```

Użyj klucza wysyłania przypisanego do projektu. Nie zastępuj go
poświadczeniem konta. Klucz artefaktów nie może wysyłać telemetrii.

Koperta, która narusza regułę pola, zwraca `422` z kodem `validation_failed`.
Pole `error` wskazuje regułę. Pole `next` mówi, jak poprawić żądanie. Na
przykład `"items": []` zwraca:

```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"
  }
}
```

Nie wysyłaj koperty, gdy nie ma zdarzeń. Koperta z więcej niż 512 elementami
zwraca `422` z błędem `native telemetry envelope exceeds the item limit`.
Podziel ją na paczki po najwyżej 512 elementów. W każdej paczce zachowaj
projekt i wspólny kontekst.

W przypadku limitów wykorzystania, limitów żądań i błędów usługi postępuj
zgodnie ze zwróconym `code` opisanym na stronie [Błędy API](/pl/reference/api-errors).

<Tip>
  Ustaw wydanie i środowisko w konfiguracji SDK. Dla każdej operacji twórz lub
  kontynuuj kontekst śladu. Nie używaj jednego ID śladu do niezwiązanych ze
  sobą zadań.
</Tip>


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