Weave Code
Tracing Laravel Laravel Package
vinelab/tracing-laravel
Laravel integration for distributed tracing with Vinelab Tracing. Automatically traces incoming HTTP requests and application flow, helping you add request-scoped spans and propagate trace context across services with minimal configuration.
Distributed tracing (OpenTracing) for Laravel made easy
Frequently asked questions about Tracing Laravel
- How do I install and configure vinelab/tracing-laravel in a Laravel app?
- Install it with Composer, publish its config, set the environment variables, and bind a concrete OpenTracing tracer implementation in the container. The package is an adapter between Laravel and your tracer, not a complete observability backend, so plan to deploy and operate Jaeger, Zipkin, or another compatible backend yourself. Expect the tracer binding to be the main configuration effort.
- Which tracing backends work with vinelab/tracing-laravel?
- It works with any OpenTracing-compatible tracer you bind, such as Jaeger, Zipkin, LightStep, or a custom implementation. Because the PHP OpenTracing ecosystem is thin and largely stale, confirm that a maintained client or exporter exists for your chosen backend before adopting it. The package does not include the backend or exporter.
- Does vinelab/tracing-laravel support OpenTelemetry or OTLP?
- No, it does not natively speak OpenTelemetry or OTLP because it is built on the deprecated OpenTracing API. You can bridge OpenTracing to OpenTelemetry, but that adds a translation layer that will itself become unsupported. For new work, use OpenTelemetry PHP instrumentation directly.
- Which Laravel and PHP versions does vinelab/tracing-laravel support?
- Check the package composer.json against your target Laravel LTS and PHP minor versions before committing. The last release was November 2023 and upstream activity is limited, so new Laravel or PHP versions may not be allowed or supported. Version constraints are the most likely day-one blocker.
- Is vinelab/tracing-laravel maintained and safe for production?
- Treat it as a bridge rather than a long-term destination. Maturity signals are weak: low stars, low activity, single-maintainer risk, and a dependency on archived OpenTracing APIs. If you adopt it, encapsulate it behind an internal Tracer and Span interface and set a dated exit criterion for migrating to OpenTelemetry.
- How does vinelab/tracing-laravel trace incoming HTTP requests and propagate context?
- A global middleware opens a root span around the Laravel request lifecycle, and supporting instrumentation can wrap DB queries, Redis calls, and outgoing HTTP. You add request-scoped spans through the tracing API and propagate trace context across services using the headers your tracer expects. Configuration is minimal once the tracer is bound, but middleware ordering affects the context captured.
- Will tracing failures break my Laravel checkout or payment flow?
- Tracing must fail open, meaning an unavailable collector or exporter should never fail a checkout or payment. The package is a thin adapter, but your tracer and exporter behavior determine whether errors propagate, so test timeouts, sampling, and exporter outages explicitly. Isolate span creation and reporting so tracing exceptions cannot break business flows.
- Where should tracing middleware run relative to auth, tenancy, and request ID middleware?
- Run the tracing middleware after request-ID and tenant-resolution middleware but before authorization. That lets root spans carry tenant and route context without capturing credentials or making authorization decisions depend on tracing. Middleware ordering conflicts with tenancy, auth, and request-ID middleware are a common integration blocker.
- Does vinelab/tracing-laravel capture PII or secrets in span tags?
- Yes, default SQL and request tagging can capture PII, secrets, or sensitive headers if you do not review it. Define a tag redaction standard and disable or scrub SQL statements, authorization headers, user identifiers, and query parameters before production. Span tag hygiene is a compliance risk, not just a performance concern.
- Can I use vinelab/tracing-laravel with Laravel Octane and queue workers?
- You must test it under Laravel Octane and queue workers because long-lived processes expose span lifecycle bugs that do not appear in php-fpm. Ensure spans are finished and context is reset per request or job to avoid memory leaks and cross-request contamination. Queue and console coverage may require extra instrumentation beyond the HTTP middleware.
Weaver
How can I help you explore Laravel packages today?