The HTTP Client instrumentation traces outgoing HTTP requests made with Laravel’s Http facade (backed by Guzzle). By default, all requests are traced automatically. You can switch to manual mode to trace only selected requests.
Configuration
In config/opentelemetry.php:
use Keepsuit\LaravelOpenTelemetry\Instrumentation;
'instrumentation' => [
Instrumentation\HttpClientInstrumentation::class => [
'enabled' => env('OTEL_INSTRUMENTATION_HTTP_CLIENT', true),
'manual' => false,
'allowed_headers' => [],
'sensitive_headers' => [],
'sensitive_query_parameters' => [],
],
],
Configuration Options
| Option | Type | Description |
|---|
manual | bool | When true, only requests explicitly calling ->withTrace() are traced. Default: false. |
allowed_headers | string[] | Request/response headers to capture and attach as span attributes. |
sensitive_headers | string[] | Headers containing sensitive data whose values are redacted in the trace. |
sensitive_query_parameters | string[] | Query string parameters whose values are redacted in the trace. |
Manual Mode
When manual is set to true, the Guzzle middleware is not applied globally. You must explicitly opt in per request using the withTrace() macro:
Http::withTrace()->get('https://api.example.com/products');
->withTrace() will not produce spans.
Route Name Resolver
HTTP client spans use the HTTP method as the span name by default (e.g. GET), because the low-cardinality URL template cannot be detected automatically. You can provide a custom resolver to produce meaningful span names based on the request URL.
Register the resolver in a service provider:
use Keepsuit\LaravelOpenTelemetry\Instrumentation\HttpClientInstrumentation;
use Psr\Http\Message\RequestInterface;
public function boot(): void
{
HttpClientInstrumentation::setRouteNameResolver(function (RequestInterface $request): ?string {
return match (true) {
str_starts_with($request->getUri()->getPath(), '/products/') => '/products/{id}',
default => null,
};
});
}
null to fall back to the default HTTP method name.
Use the route name resolver to produce low-cardinality span names that avoid creating a new series per unique URL segment (such as IDs).
Metrics
| Metric | Type | Unit | Description |
|---|
http.client.request.duration | Histogram | seconds | Duration of outgoing HTTP requests. |
Disabling
Set the environment variable to false to disable this instrumentation:
OTEL_INSTRUMENTATION_HTTP_CLIENT=false
HttpClientInstrumentation::class from the instrumentation array in config/opentelemetry.php. 