Weave Code
Xray Laravel Laravel Package
napp/xray-laravel
Napp Xray gives Laravel developers an in-app dashboard for inspecting their application's structure, browsing routes, models, and classes, and quickly debugging how everything fits together without digging through files.
AWS X-Ray for Laravel applications.
Frequently asked questions about Xray Laravel
- How do I install napp/xray-laravel in a Laravel application?
- Install it with Composer using composer require napp/xray-laravel. The package relies on Laravel package auto-discovery, so the service provider and global middleware registration happen without manual wiring, and the config file is publishable when you need to tune sampling or instrumentation. It also ships an in-app dashboard for browsing routes, models and classes. The code install is cheap; the real prerequisite is a reachable X-Ray daemon, which is infrastructure work rather than a Laravel task.
- What AWS infrastructure and IAM permissions does this package require?
- X-Ray needs a daemon reachable over UDP port 2000, which means an ECS sidecar, an EKS DaemonSet, or the EC2 agent, since the SDK ships segment documents to that local endpoint. IAM needs xray:PutTraceSegments and xray:PutTelemetryRecords, plus xray:GetSamplingRules and xray:GetSamplingTargets if you use remote sampling. Treat this as a platform-team dependency and sequence it before the Laravel-side integration work.
- Which Laravel and PHP versions does napp/xray-laravel support?
- Check the composer.json constraints and the Packagist release history for the exact Laravel and PHP matrix before committing, because the supported majors are not guaranteed to match your target versions. Installation follows conventional package auto-discovery, so the mechanics are identical across supported releases. If you run the newest Laravel major, confirm an explicit constraint rather than assuming compatibility.
- Does napp/xray-laravel work with Laravel Octane?
- This needs to be answered with a load test, not with documentation. Under Octane the decisive detail is whether trace state is request-scoped or held in a singleton on a long-lived worker, since leaked state corrupts traces across requests. Run concurrent requests through an Octane worker and confirm segments stay isolated and the trace context is reset in the request lifecycle.
- Can I disable tracing in local development or during a production incident?
- Look for an enabled flag in the published config and confirm it can be driven by an environment variable so tracing can be turned off without a deploy. Because the package sits on the request hot path through global middleware, framework event subscribers and an HTTP client wrapper, a fast kill switch is a hard production requirement. Verify it in staging by flipping the flag and confirming no segments are emitted and no listeners still execute.
- What happens if the X-Ray daemon is unreachable or slow?
- The SDK sends UDP datagrams, so a missing daemon should mean dropped traces rather than failed requests, but verify this instead of assuming it. Test the failure mode by stopping the sidecar under load and watching latency, error rates and logs. If the package blocks, retries or throws on the request path, its failure characteristics become your application's failure characteristics.
- Does the package record SQL statements and bindings that could leak PII?
- The database listener is the highest-risk surface: if statements are recorded with bindings interpolated, literal emails, tokens and card fragments land in a third-party telemetry store. Before production, inspect the emitted segment documents and determine whether you get raw SQL, parameterized SQL, or nothing at all, and check for a documented sanitization or redaction path. The absence of one should be treated as a blocker for regulated data.
- Does it propagate trace context through queues, SQS and SNS?
- The key question is whether the X-Amzn-Trace-Id header is carried through SQS and SNS payloads and whether the queue worker resumes the parent trace instead of starting an orphan. Verify it by dispatching a job from a traced request and checking the service map joins the two. Without propagation, async work appears as disconnected traces and your latency picture is wrong.
- Will instrumenting every database query blow up segment size or tracing cost?
- Each query typically becomes its own subsegment, and segment documents are capped at 64KB, so an endpoint with an N+1 problem can produce a truncated or rejected trace precisely where you most wanted diagnostics. Cost also scales with subsegment volume rather than request count. Use sampling rules and targeted instrumentation, and load-test a heavy endpoint to confirm traces survive intact.
- Is the package well maintained, and can we fork it if it stalls?
- It is MIT licensed, so forking and patching is legally straightforward, and for an additive observability package with an off switch that is an acceptable fallback. The realistic concern is bus factor: a small star count and single-maintainer release cadence mean you should budget for possibly carrying a fork, and removal touches middleware registration, a service provider, config, queue listeners and container bindings, so plan a day rather than an hour. That trade-off is fine for tracing but would not be acceptable for auth or payments, and it is worth weighing against OpenTelemetry plus an ADOT Collector if vendor-neutral instrumentation is on your roadmap.
Weaver
How can I help you explore Laravel packages today?