Lighthouse Graphql Hive Laravel Package

Getting Started

composer require stayallive/lighthouse-graphql-hive
php artisan vendor:publish --tag=lighthouse-graphql-hive-config

Grab a reporting/ingest token from your Hive project (Settings → Access Tokens), then configure the environment:

HIVE_TOKEN=...
HIVE_ENDPOINT=https://api.graphql-hive.com
HIVE_REPORTING_ENABLED=true
HIVE_SAMPLE_RATE=1
HIVE_CLIENT_NAME="${APP_NAME}"
HIVE_CLIENT_VERSION=1.0.0

Lighthouse must have tracing enabled and pointed at the Hive driver. Edit config/lighthouse.php:

'tracing' => [
    'enabled' => env('LIGHTHOUSE_TRACING_ENABLED', true),
    // Use the exact tracer class documented in the package README —
    // Lighthouse v5 and v6 expose different tracing contracts.
    'driver' => Stayallive\LighthouseGraphQLHive\Tracing\HiveTracer::class,
],

First use case: execute a named query against /graphql, then open Hive → Operations. You should see the operation name, latency, error rate, and client name/version. If it's silent, check storage/logs for the Hive client and confirm a schema version is published in that Hive target.

Where to look first:

• config/lighthouse-graphql-hive.php — endpoint, token, sampling, client metadata.
• config/lighthouse.php — tracing block; this is the switch that actually turns reporting on/off.
• Hive dashboard: Operations (per-operation latency/errors), Schema (version drift/checks), Insights (usage trends).

Implementation Patterns

• Per-environment config. Give prod, staging, and local distinct tokens (or disable locally via HIVE_REPORTING_ENABLED=false). Never reuse a prod ingest token in CI or feature branches — bad operations will pollute prod metrics.
• Sampling for scale. Set HIVE_SAMPLE_RATE=0.1 on high-traffic APIs; Hive extrapolates counts and percentiles. Avoid sampling to zero in production — you lose the signal you installed the package for.
• Release correlation. Populate HIVE_CLIENT_VERSION from a build/commit env var so Hive can tie error spikes to deploys. Set HIVE_CLIENT_NAME per service if you run multiple GraphQL apps.
• Schema publishing is a separate concern. This package reports runtime usage; schema versions are published via the hive CLI in CI (or graphql-hive/php for OTel-native flows). Wire CI to publish on schema changes so reported operations aren't orphaned.
• Self-hosted Hive. Override HIVE_ENDPOINT to your instance; ensure egress from web and Octane workers, and TLS is trusted.
• Extension via container binding. Replace or decorate the reporter in a service provider to add tenant IDs or custom labels before the payload leaves the app — much easier than forking.
• Local workflow. Keep reporting disabled locally and rely on Lighthouse's built-in tracing or a local OTel exporter for debugging; flip Hive on in deployed environments only.

Gotchas and Tips

• Tracing instrumentation cost. Lighthouse tracing instruments every resolver. Benchmark before enabling across a hot endpoint; use sampling to cap spend and CPU.
• Double sampling. If you also configure OpenTelemetry sampling (or plug Hive through graphql-hive/php), the rates compound and your dashboard silently under-reports. Pick one sampling layer.
• Token confusion. Hive uses distinct tokens for registry (publish), CDN (artifacts), and reporting (ingest). The wrong token gives opaque 401s from the client. Use the reporting token here.
• Version compatibility. The Lighthouse tracing contract changed between v5 and v6. Match the driver FQCN to your Lighthouse major, and pin the package version in composer.json to avoid surprise breakage on composer update.
• Config caching. After editing .env or config/lighthouse.php, run php artisan config:cache (or config:clear) — stale caches are the #1 cause of "reports suddenly stopped."
• Anonymous operations. Unnamed queries surface as generic entries in Hive. Force client-side operation naming (query Foo { ... }) so per-operation metrics are actionable.
• Error visibility. Only errors surfaced in the GraphQL response reach Hive. Exceptions swallowed inside custom resolvers won't appear.
• Flush timing. Reports are dispatched in the terminating phase. Environments that skip terminate (some test harnesses, misconfigured FPM/Octane setups) will silently drop data. Disable reporting in phpunit.xml.
• Debugging transport. Point HIVE_ENDPOINT at a logging proxy or attach a Guzzle middleware to inspect the outbound payload; Hive returns structured JSON errors for malformed requests.
• Version drift. If CI publishes schemas on one cadence and code deploys on another, HIVE_CLIENT_VERSION is your only way to correlate which build produced which operations during an incident.