Packages & installation

Use this page as the single entry point for every client library, script, and mirror repo that ships from the Bilge monorepo. Each row links to the canonical README (full API and configuration) and to the relevant HTTP docs where applicable.

Supported SDKs

First-class stacks are covered by our end-to-end ingest checks on every release, and problems with them are fixed first. Beta stacks use the same ingest endpoints and should work, but get less testing; if something breaks, tell us at support and we'll fix it. With a Sentry SDK, Bilge stores errors and session (release-health) data; transactions, replays and attachments are accepted and ignored for now, so use bilgesh/tracing or the Ingest API for tracing.

Choose your integration (quick path)

1. Laravel or PHP (errors, traces, logs, metrics, RUM, profiling) — Install bilgesh/tracing via Composer (see Installing bilgesh/tracing below). Deep reference: Ingest API, Protocol overview, Monitoring modes.
2. Rails — Copy packages/bilge-rails/lib/bilge_framework.rb into your app. Follow packages/bilge-rails/README.md in the monorepo (or your split mirror). Not a gem; same ingest contract as step 1. Summary: Framework integrations.
3. WordPress — Copy packages/bilge-wordpress/ into wp-content/plugins/bilge/ (see packages/bilge-wordpress/README.md). Enable under Plugins, configure Settings → Bilge with base URL + project API key. Split mirror: SPLIT_BILGE_WORDPRESS_REPO.
4. Terminal automation (projects, grouped errors, triage) — Install bilgesh/cli (composer require --dev bilgesh/cli or global). Uses Sanctum API tokens (Profile → API tokens) against /api/v1/*. See packages/bilge-cli/README.md and bilge list.
5. AI agents (Cursor, Claude Desktop, MCP clients) — Same personal access token as step 4. Connect to POST /mcp/bilge (JSON-RPC): 17 tools, docs resources, triage prompts. Full setup: MCP server.
6. Browser: uncaught JS errors — Host public/js/bilge.js from your Bilge app (or the split mirror for public/js) and add the script tag with data-ingest-url and data-api-key. Details: root README.md section JavaScript (frontend errors).
7. Browser: Web Vitals / SPA (RUM) — Use packages/bilge-tracing/resources/rum/bilge-rum.js (same project API key; performance ingest must be enabled). See packages/bilge-tracing/README.md § Real User Monitoring.
8. REST without SDK — API token (Profile → API tokens) or project API key per REST API (v1); OpenAPI: v1.yaml.
9. Raw HTTPS only — Any client that can POST JSON: Ingest API.
10. High-volume edge ingest (operators) — Deploy packages/bilge-ingest-edge/ on Cloudflare Workers. Full runbook: Edge ingest (Cloudflare).

Installing bilgesh/tracing

Laravel

From your Laravel app root (directory containing artisan):

composer require bilgesh/tracing
php artisan bilge:install

composer require updates composer.json / composer.lock and installs the package under vendor/. bilge:install prompts for a DSN (https://PROJECT_API_KEY@your-bilge-host.example.com) and appends BILGE_DSN plus BILGE_LARAVEL=true to .env (unless you use --no-quick). Alternatively set BILGE_API_KEY and BILGE_URL if everyone uses the same Bilge host.

Then: clear or rebuild config cache if you use config:cache; optionally php artisan vendor:publish --tag=bilge-tracing-config; register bilgeTracing.continueTrace (and performance middleware when needed) on your routes. Laravel auto-discovers the package service provider.

Step-by-step narrative: Framework integrations — Laravel.

Other PHP projects (not Laravel)

From your project root (where your composer.json lives):

composer require bilgesh/tracing

There is no Laravel provider: configure Tracer::instance()->configure([...]) with api_key and base_uri during bootstrap, and wire PSR-15 middleware, Guzzle, Monolog, or manual Tracing:: calls as needed. See packages/bilge-tracing/README.md sections Install → Other PHP projects, Propagation, and Guzzle 7.

Monorepo layout & mirror splits

These paths exist in the main Bilge repository. Maintainers can git subtree split each prefix to an empty GitHub mirror.

The main app installs bilgesh/tracing and bilgesh/cli from Packagist (same as customer apps). Sources still live at packages/bilge-tracing and packages/bilge-cli. Container builds copy only composer.json / composer.lock first, so these must not be Composer path repositories.

Where to read next