Download the PHP package logbrew/sdk without Composer

LogBrew SDKs

LogBrew SDKs help applications send logs, errors, traces, releases, environments, actions, and explicit metrics to LogBrew with small, dependency-light clients.

This repository contains the public SDK packages, framework integrations, event contract, examples, and shared guidance used to keep the developer experience consistent across ecosystems.

What You Can Capture

• Releases and environments for deployment context.
• Issues and handled errors with a bounded parent-first exception graph, typed mechanism and handled state, explicit message/stack evidence states, structured frames, breadcrumbs, and optional application-reported diagnostic evidence without raw stack text by default.
• Logs from direct calls or app-owned logger integrations.
• Spans and W3C traceparent context for request tracing.
• Actions for important user or system events.
• Explicit metrics when your application already knows the measurement name, stable purpose, value, unit, kind, and temporality.
• A shared, versioned context for privacy-bounded resource, deployment, trace, session, opaque subject, and low-cardinality tag correlation across every signal.

User-facing severity categories are info, warning, error, and critical. SDKs keep accepting common runtime aliases where they are idiomatic, such as trace, debug, warn, and fatal, but queued payloads normalize those aliases to the canonical categories before they are sent. See the LogBrew severity contract for the full mapping.

Packages

Install only the package your application needs. The package names below are registry-specific entry points, not a bundle to install together:

• Use the core package for your runtime first, such as @logbrew/sdk, logbrew-sdk, LogBrew, or co.logbrew:logbrew-sdk.
• Add framework packages only when your app uses that framework, such as @logbrew/react, @logbrew/express, logbrew-fastapi, logbrew-flask, or logbrew-django.
• Frontend and mobile packages use public clientKey setup. Server packages should use server-side keys from app configuration.
• A change to one ecosystem package should not require developers in other ecosystems to update unless their package also changed.
• Apple app setup should start from the Swift/SwiftPM path. Objective-C remains available as an advanced source/header variant for mixed or Objective-C-only apps, not a separate first-step platform choice.
• Product setup pickers should show user-facing runtime/platform families instead of helper package names; see the SDK setup picker guidance.

Node queue integrations are published as separate npm packages. For BullMQ, KafkaJS, RabbitMQ/amqplib, and Amazon SQS, install the matching @logbrew/* integration alongside @logbrew/sdk, @logbrew/node, and the broker or client library your app already uses.

Node framework adapters also require the Node delivery package. Use the exact stack for the framework your app already owns:

Quick Start

JavaScript:

The JavaScript core and framework clients merge this bounded context into every event. Session and subject identifiers are explicit, app-owned, and opaque; LogBrew does not automatically collect profile fields or personal data. See the @logbrew/sdk shared telemetry context guide for the complete shape and privacy rules.

RecordingTransport is local-only: its synthetic HTTP 202 makes no network request and does not indicate hosted delivery or event visibility. Use the released runtime package's HTTP transport and then read the event through the authenticated CLI or API for end-to-end confirmation.

Python:

Framework applications should use the released adapter so request lifecycle, trace context, and exception capture are installed once: logbrew-flask for Flask, logbrew-fastapi for FastAPI, or logbrew-django for Django. Each adapter installs a compatible core dependency; do not reconstruct framework middleware from the core example.

The Python core and framework clients merge this bounded context into every event. The core client also adds conservative Python runtime, operating-system, and architecture context by default, with an explicit opt-out. Session and subject identifiers remain explicit, app-owned, and opaque. See the logbrew-sdk shared telemetry context guide for the complete shape and privacy rules.

Python DB-API spans are explicit and app-owned. Trace the connect callable your app already controls, then keep using normal cursor methods:

The wrapper records operation labels such as SELECT, FETCHALL, and COMMIT, duration, row counts when the driver exposes them, trace/span correlation, and type-only failures. It does not capture SQL values, bind parameters, result rows, connection strings, baggage, tracestate, stacks, or exception messages.

PHP:

Each package README has ecosystem-specific install commands, logger integration examples, framework setup, copyable examples, and transport details. If your app does not use a framework integration, skip that package.

Automatic issue helpers preserve native cause, context, aggregate, and suppressed relationships when their runtime exposes them. The root remains compatible with the existing exception and stackFrames fields; every missing, redacted, or truncated message/stack state is explicit and no SDK invents historical evidence. See the exception-chain evidence contract.

Metrics

Metrics are explicit: core SDKs do not automatically collect runtime, framework, database, or host metrics. Opt-in framework request helpers may emit a bounded request-duration metric. Their purpose is to aggregate behavior over time—rates, latency distributions, saturation, and release-to-release change—while logs/actions describe discrete facts and traces explain individual executions.

Use metric helpers when your application already has a bounded measurement:

• counter and histogram values use delta or cumulative temporality and must be non-negative.
• gauge values use instant temporality and may go up or down.
• Add an optional stable description that explains what the measurement means. SDKs trim it, limit it to 1024 Unicode scalar values, and reject unsafe control characters. Do not put identifiers, personal data, request values, or other changing content in it.
• Metadata should be primitive and low-cardinality, such as region, route template, operation, status class, queue, or worker name. Keep service and deployment identity in typed context.
• Do not use event, trace, session, user, raw URL, or other high-cardinality values as metric dimensions. Typed context may still link one metric event to an investigation without making those values aggregation keys.

Product Analytics Capture

Product analytics reuses explicit action events and existing page-view telemetry. Product-action helpers across the supported SDK families attach a reserved versioned interaction classification; browser page-view helpers attach page_view, and React Native plus Kotlin/Android screen helpers attach screen_view. These annotations do not install automatic click capture or collect user-entered values. Use explicit opaque subject and session IDs in the shared telemetry context when user- or session-level analysis is required.

See the product analytics capture contract for the exact fields, privacy rules, and compatibility behavior.

Trace Context

SDK trace helpers follow W3C traceparent conventions where supported. They validate IDs, reject all-zero trace/span IDs, preserve sampled flags, and avoid global HTTP client patching by default.

Framework integrations that capture inbound requests omit query strings from automatic request/error metadata by default. Frontend and mobile integrations use clientKey wording for public keys and only send tracing headers to configured targets.

Agent-Readable Sessions

LogBrew is designed for structured analysis across many app sessions, not only one-at-a-time inspection. Capture important product steps as action events, connect frontend and backend work with traceparent, keep session/subject identity in the versioned typed context, and use low-cardinality dimensions such as routeTemplate, funnel, step, feature, and region.

For browser and mobile apps, prefer explicit action helpers for clicks, form submits, route changes, funnel steps, and retry decisions that your app already understands. Avoid raw selectors, full URLs, user-entered text, screenshots, and visual replay data unless your team has a clear privacy policy and opt-in path.

If you use an AI coding assistant, ask it to wire LogBrew into your app's logger, request lifecycle, and important product actions so agents can analyze timelines made of logs, issues, spans, actions, and metrics. The assistant should keep keys in app configuration and avoid query strings, stack text, and high-cardinality metadata unless your team opts in.

Privacy Defaults

LogBrew SDKs favor conservative defaults:

• No query strings or URL hashes in automatic request metadata by default.
• No raw stack text unless explicitly enabled.
• The Node delivery client adds only Node version, OS type/release, and architecture as automatic shared context. It supports an explicit opt-out and does not infer host, user, service, application, or cloud identity.
• The Python client adds only Python implementation/version, OS name/release, and architecture as automatic shared context. It supports an explicit opt-out and does not infer user, service, application, session, or cloud identity.
• The Rust client adds only Rust runtime name, target OS family, and architecture as automatic shared context. It supports an explicit opt-out and does not probe hostnames, process details, environment variables, local accounts or paths, network/cloud identity, CPU details, or memory details.
• The Objective-C source client adds only its runtime name, Apple operating-system name/version, architecture, and populated application bundle name/version/build. It supports an explicit opt-out and does not infer account, host, network, unique-device, session, subject, or tag identity.
• The browser client adds only low-entropy browser brand/significant version, platform, and mobile/desktop family when User-Agent Client Hints expose them; otherwise it reports the generic browser runtime. It never reads the legacy user-agent string or requests high-entropy hints, and supports an explicit opt-out.
• Automatic Pino metadata excludes credentials, cookies, bodies, payloads, query text, raw URLs, propagation headers, local file paths, and stack text by default.
• No document title or user agent in browser metadata unless explicitly enabled.
• No global logger, console, fetch, or framework behavior changes unless the integration explicitly documents that opt-in behavior.
• App-owned transports, loggers, and framework versions remain under application control.

Local Payload Preview

Every core SDK supports local JSON preview or recording transports so you can inspect the queued batch before sending anything to LogBrew. This is useful while deciding which logs, spans, issues, releases, actions, environments, or explicit metrics your application should send.

The canonical schema is fixtures/.

Maintainer References

• docs/sdk-readiness-checklist.md describes public SDK quality expectations.
• docs/github-actions.md describes the repository Actions layout.
• docs/product-analytics-contract.md defines the versioned page-view, screen-view, and interaction vocabulary.
• Package READMEs contain ecosystem-specific examples and install commands.