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

# Send SDK telemetry

> Send native LogBrew telemetry envelopes with logs, issues, trace spans, actions, releases, and environments.

First-party SDKs send native telemetry envelopes to LogBrew. One envelope can
contain multiple telemetry items, but every item shares the same project,
service, release, environment, and optional trace context.

## Required envelope fields

| Field          | Required | Notes                                                                          |
| -------------- | -------- | ------------------------------------------------------------------------------ |
| `project_id`   | Yes      | UUID for the LogBrew project.                                                  |
| `environment`  | Yes      | Use `production`, `staging`, `preview`, or `local`. Blank values are rejected. |
| `release`      | Yes      | Non-empty code version. Blank releases are rejected.                           |
| `service_name` | Yes      | Logical service name, such as `checkout-api`.                                  |
| `sdk_name`     | Yes      | SDK identifier, such as `logbrew-rust`.                                        |
| `sdk_version`  | Yes      | SDK version.                                                                   |
| `items`        | Yes      | One or more telemetry items.                                                   |
| `trace_id`     | No       | Trace ID that connects logs, spans, issues, and actions.                       |

## Item types

<CardGroup cols={2}>
  <Card title="log" icon="file-text">
    `severity`, `message`, `source`, `attributes`, `occurred_at`
  </Card>

  <Card title="trace_span" icon="route">
    `trace_id`, `span_id`, `name`, `operation`, `started_at`, `duration_ms`
  </Card>

  <Card title="issue" icon="bug">
    `severity`, `title`, `message`, `stack_trace`, `fingerprint`,
    `occurred_at`
  </Card>

  <Card title="action" icon="mouse-pointer-click">
    `name`, `distinct_id`, `session_id`, `properties`, `occurred_at`
  </Card>
</CardGroup>

## Severity values

Use `info`, `warning`, `error`, or `critical` for logs and issues. SDKs and
runtimes may send common aliases such as `trace`, `debug`, `warn`, or `fatal`,
but LogBrew normalizes accepted aliases to the canonical values.

## Package-manager installs

Install the SDK package for the runtime that sends telemetry. Use project-scoped
SDK or ingest configuration from LogBrew; do not use account login values as SDK
configuration.

| Runtime       | Install                                                     |
| ------------- | ----------------------------------------------------------- |
| JavaScript    | `npm install @logbrew/sdk`                                  |
| Node.js       | `npm install @logbrew/sdk @logbrew/node`                    |
| 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.4,<0.2"`        |
| Django        | `python3 -m pip install logbrew-django`                     |
| Swift / Apple | Add `https://github.com/LogBrewCo/sdk.git` through SwiftPM. |
| PHP           | `composer require logbrew/sdk:^0.1.1`                       |
| Ruby          | `gem install logbrew-sdk`                                   |
| Go            | `go get github.com/LogBrewCo/sdk/go/logbrew@v0.1.3`         |
| Rust          | `cargo add logbrew`                                         |
| .NET          | `dotnet add package LogBrew --version 0.1.4`                |
| C++ / CMake   | Pin `cpp/logbrew-cpp/v0.2.3` with CMake `FetchContent`.     |

### C++ with CMake

The C++ SDK requires C++17 and CMake 3.16 or newer. CLI v0.1.39 or newer
detects a root `CMakeLists.txt` and prints this non-mutating setup plan with
`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)
```

The core target is dependency-free. To send batches through the optional
libcurl transport, replace the final `FetchContent_MakeAvailable` call and
target link above with:

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

Configure and build the consumer to verify that the pinned release and target
resolve:

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

For builds that cannot fetch the SDK monorepo, use the scoped
`logbrew-cpp-0.2.3.tar.gz` asset from the
[C++ 0.2.3 release](https://github.com/LogBrewCo/sdk/releases/tag/cpp/logbrew-cpp/v0.2.3).
The extracted package supports `cmake --install` and
`find_package(LogBrew 0.2.3 CONFIG REQUIRED)`.
See the
[C++ SDK guide](https://github.com/LogBrewCo/sdk/tree/main/cpp/logbrew-cpp)
for typed context, issue evidence, span events and links, metrics, actions,
and HTTP delivery.

Use the `LogBrew` Swift product for telemetry. Add `LogBrewCrash` only for
explicit Apple crash or hang capture. Follow
[Capture Apple crashes and hangs](/guides/apple-crashes-and-hangs) for exact
dSYM upload and hosted symbolication.

For Flask, follow [Set up Flask](/guides/flask) for one-call initialization,
the first hosted request, privacy defaults, worker lifecycle, and CLI readback.

## React Native hosted delivery

Use `@logbrew/react-native` 0.1.7 or newer. Give the app a project-scoped,
write-only ingest key. Expo includes every `EXPO_PUBLIC_*` value in the app
bundle, so never put an account or server credential in that variable.

CLI v0.1.32 or newer can store a new SDK key for an existing project without
creating a duplicate project:

```bash theme={null}
install -d -m 700 "$HOME/.logbrew"
logbrew projects --json
logbrew projects keys create <project_id> \
  --ingest-key-file "$HOME/.logbrew/my-mobile-app.ingest" \
  --label "My mobile app" \
  --kind sdk \
  --json
```

Keep that file out of source control. Use its value as
`EXPO_PUBLIC_LOGBREW_CLIENT_KEY`; do not use the account credential that
authorized the CLI command.

```js theme={null}
import { AppState } from "react-native";
import {
  createAppStateListener,
  createLogBrewReactNativeClient,
  createReactNativeFetchTransport
} from "@logbrew/react-native";

const clientKey = process.env.EXPO_PUBLIC_LOGBREW_CLIENT_KEY;
if (!clientKey) {
  throw new Error("Set EXPO_PUBLIC_LOGBREW_CLIENT_KEY");
}

const client = createLogBrewReactNativeClient({
  clientKey,
  sdkName: "my-mobile-app",
  sdkVersion: "1.0.0",
  transport: createReactNativeFetchTransport()
});

const stopAppStateListener = createAppStateListener(client, AppState, {
  flushOnBackground: true
});

export async function verifyLogBrewSetup() {
  const occurredAt = new Date().toISOString();
  client.log(`evt_react_native_setup_${Date.now()}`, occurredAt, {
    level: "info",
    message: "React Native setup check",
    metadata: {
      environment: __DEV__ ? "development" : "production",
      service: "my-mobile-app"
    }
  });

  const receipt = await client.flush();
  if (receipt.statusCode < 200 || receipt.statusCode >= 300) {
    throw new Error("LogBrew intake did not accept the setup event");
  }
  return {
    status_code: receipt.statusCode,
    attempts: receipt.attempts,
    batches: receipt.batches
  };
}
```

### Keep Expo Debug IDs in production bundles

Use `@logbrew/react-native` 0.1.8 or newer for Expo release bundles. Create the
Expo Metro config through LogBrew so the runtime bundle receives the same final
Debug ID as the Expo source map:

```js theme={null}
// metro.config.js
const {
  getLogBrewExpoConfig
} = require("@logbrew/react-native/metro");

module.exports = getLogBrewExpoConfig(__dirname);
```

If the app uses React Native Worklets bundle mode, apply that transform after
the LogBrew helper:

```js theme={null}
// metro.config.js
const {
  getLogBrewExpoConfig
} = require("@logbrew/react-native/metro");
const {
  getBundleModeMetroConfig
} = require("react-native-worklets/bundleMode");

const config = getLogBrewExpoConfig(__dirname);

module.exports = getBundleModeMetroConfig(config);
```

The helper preserves existing Expo pre-serialization plugins. Do not apply
`withLogBrewMetroConfig()` to an Expo config. That wrapper is for bare React
Native projects. If an Expo project uses it, the production serializer stops
with a message that points to `getLogBrewExpoConfig()` instead of creating a
bundle with mismatched symbolication data.

Supplying the fetch transport enables the core SDK's bounded automatic
delivery, retry, queue, and pause behavior. Do not add a second flush timer.
The AppState listener requests a final flush when the app becomes inactive or
enters the background. Call `stopAppStateListener()` during app teardown.

A successful flush proves that the HTTPS intake accepted the batch. Confirm
event visibility separately with the authenticated CLI:

```bash theme={null}
logbrew read logs --project <project_id> \
  --search "React Native setup check" --since 1h --json
```

`RecordingTransport.alwaysAccept()` is for local inspection. Its synthetic
`202` response does not send a network request and does not prove hosted
delivery.

## JavaScript queue tracing

Node queue integrations are separate npm packages. Install the base LogBrew
JavaScript packages, the integration package, and the queue or broker client
your app already uses.

| Queue or broker    | Install                                                                       |
| ------------------ | ----------------------------------------------------------------------------- |
| 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` |

Use these packages for explicit, app-owned trace correlation around the queue
calls you choose. LogBrew does not own your broker connection, create queues, or
globally patch every client by default.

<Warning>
  Keep queue payloads, arbitrary message headers, broker URLs, and session or
  account bearer values out of SDK configuration. Use project-scoped server
  ingest configuration from LogBrew.
</Warning>

## Example request

Keep the project-scoped ingest value separate from account or browser-session
credentials. These names are local shell variables for the request below:

```bash theme={null}
export LOGBREW_API_URL="https://api.logbrew.co"
export LOGBREW_INGEST_BEARER="paste-project-scoped-ingest-value"
```

```bash theme={null}
curl "$LOGBREW_API_URL/api/telemetry/ingest" \
  -H "Authorization: Bearer $LOGBREW_INGEST_BEARER" \
  -H "Content-Type: application/json" \
  --data @telemetry-envelope.json
```

```json telemetry-envelope.json theme={null}
{
  "project_id": "00000000-0000-0000-0000-000000000000",
  "environment": "production",
  "release": "api@1.2.3",
  "service_name": "checkout-api",
  "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
  "sdk_name": "logbrew-rust",
  "sdk_version": "0.1.0",
  "items": [
    {
      "type": "log",
      "data": {
        "severity": "warning",
        "message": "checkout retry scheduled",
        "source": "runtime",
        "attributes": { "route": "/checkout" },
        "occurred_at": "2026-06-01T12:00:00Z"
      }
    },
    {
      "type": "action",
      "data": {
        "name": "checkout_failed",
        "distinct_id": "user_123",
        "session_id": "session_456",
        "occurred_at": "2026-06-01T12:00:00Z",
        "properties": { "cart_total": 4200 }
      }
    }
  ]
}
```

## Response

The ingest response returns accepted item counts by stream.

```json theme={null}
{
  "issues": 0,
  "logs": 1,
  "trace_spans": 0,
  "actions": 1
}
```

<Tip>
  Put release, environment, and trace ID into SDK setup once. Every later CLI
  investigation becomes easier.
</Tip>