Weave Code
Cloud Trace Laravel Package
google/cloud-trace
Official Google Cloud Trace client for PHP. Capture and report distributed traces from your applications to Google Cloud, helping you analyze request latency, find bottlenecks, and debug performance across services. Supports OpenCensus and easy integration.
Google Cloud Trace for PHP provides a client for sending distributed trace data to Google Cloud Trace, helping you understand latency and request flow in PHP applications. It exposes a simple TraceClient API for creating and annotating spans, plus an OpenCensus exporter for integrating with existing instrumentation.
- Create, annotate, and batch spans
- Report trace data to Cloud Trace
- OpenCensus exporter integration
- Supports attributes, annotations, time events, and links
- Uses Application Default Credentials for authentication
Frequently asked questions about Cloud Trace
- What is google/cloud-trace used for in a Laravel app?
- google/cloud-trace is a framework-agnostic PHP client for Google Cloud Trace. In Laravel it can act as a low-level span emitter behind a service provider and middleware so you can record request latency and export traces to GCP. It does not provide Laravel auto-instrumentation or full APM by itself.
- How do I install google/cloud-trace in Laravel?
- Run composer require google/cloud-trace, then bind the TraceClient as a singleton in a service provider. Add configuration and environment flags, and wrap it behind an internal tracer interface so you can disable it or swap backends later. Plan to validate gRPC, protobuf, and google/gax dependency constraints in your app.
- Does google/cloud-trace automatically instrument Laravel Eloquent, queues, and HTTP calls?
- No. It does not automatically instrument Eloquent, Redis, queues, Blade, Laravel events, or the HTTP client. You must add custom middleware, listeners, and Guzzle or Laravel HTTP client hooks if you need span coverage beyond a root request span.
- Which Laravel and PHP versions are supported by google/cloud-trace?
- The package is framework-agnostic, so Laravel compatibility depends on its PHP and google/gax, grpc, and protobuf constraints rather than Laravel auto-discovery. Verify current Packagist metadata for PHP 8.2, PHP 8.3, Laravel 11, and Laravel 12 before committing. Dependency conflicts with ext-grpc or protobuf are possible.
- Is google/cloud-trace actively maintained?
- Community validation is very low: the context cites 23 stars and zero dependents, with few Laravel recipes. The listed release date is future-dated, so verify Packagist and upstream metadata before relying on it. It may also be legacy relative to OpenTelemetry-based Google Cloud tracing.
- How do I authenticate google/cloud-trace in production?
- Use Application Default Credentials or GCP workload identity with the roles/cloudtrace.agent role. Avoid long-lived service account key files in production. Provide a no-op fallback when tracing is disabled or credentials are missing.
- How do I propagate X-Cloud-Trace-Context or W3C traceparent with google/cloud-trace in Laravel middleware?
- You need custom middleware. Start a root span, parse inbound X-Cloud-Trace-Context or W3C traceparent, attach route and status attributes, then end the span. Also propagate the trace context to logs via a Monolog processor and to outbound HTTP calls through Guzzle or Laravel HTTP client middleware.
- Is google/cloud-trace a good alternative to OpenTelemetry or a full APM?
- It is not a full APM replacement and is weaker than OpenTelemetry for framework-wide coverage. If OpenTelemetry is your platform standard, use OpenTelemetry PHP with a Google Cloud exporter instead. Choose google/cloud-trace only for a time-boxed GCP-native request-tracing pilot behind an internal tracer interface.
- What are the production risks of using google/cloud-trace in Laravel?
- Expect custom instrumentation effort, sampling and quota management, PII leakage risk, overhead, and vendor lock-in. The package will not deliver end-to-end APM without extra work for queues, scheduled jobs, slow queries, and outbound calls. Budget 3 to 5 engineer days for a request-tracing MVP and weeks for broader Laravel coverage.
- How do I test or disable google/cloud-trace locally and in CI?
- Disable tracing in local and test environments with environment flags and bind a no-op tracer. In CI, mock the TraceClient or use a fake exporter so tests do not require GCP credentials or network access. Validate staging with workload identity before enabling production sampling.
Weaver
How can I help you explore Laravel packages today?