Skip to content

Commit 382525e

Browse files
intuibaseintuibase
committed
Curl auto instrumentation distributed tracing headers propagation, request and response headers capturing (#1420)
1 parent 27a188b commit 382525e

File tree

6 files changed

+583
-66
lines changed

6 files changed

+583
-66
lines changed

‎src/Instrumentation/Curl/README.md‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,14 +14,51 @@ install and configure the extension and SDK.
1414

1515
## Overview
1616
Auto-instrumentation hooks are registered via composer, and client kind spans will automatically be created when calling `curl_exec` or `curl_multi_exec` functions.
17+
Additionally, distributed tracing is supported by setting the `traceparent` header.
1718

1819
## Limitations
1920
The curl_multi instrumentation is not resilient to shortcomings in the application and requires proper implementation. If the application does not call the curl_multi_info_read function, the instrumentation will be unable to measure the execution time for individual requests-time will be aggregated for all transfers. Similarly, error detection will be impacted, as the error code information will be missing in this case. In case of encountered issues, it is recommended to review the application code and adjust it to match example #1 provided in [curl_multi_exec documentation](https://www.php.net/manual/en/function.curl-multi-exec.php).
2021

22+
To ensure the stability of the monitored application, capturing request headers sent to the server works only if the application does not use the `CURLOPT_VERBOSE` option.
23+
2124
## Configuration
2225

26+
### Disabling curl instrumentation
27+
2328
The extension can be disabled via [runtime configuration](https://opentelemetry.io/docs/instrumentation/php/sdk/#configuration):
2429

2530
```shell
2631
OTEL_PHP_DISABLED_INSTRUMENTATIONS=curl
2732
```
33+
34+
### Request and response headers captuing
35+
36+
Curl auto-instrumentation enables capturing headers from both requests and responses. This feature is disabled by default and be enabled through environment variables or array directives in the `php.ini` configuration file.
37+
38+
To enable response header capture from the server, specify the required headers as shown in the example below. In this case, the "Content-Type" and "Server" headers will be captured. These options values are case-insensitive:
39+
40+
#### Environment variables configuration
41+
42+
```bash
43+
OTEL_PHP_INSTRUMENTATION_HTTP_RESPONSE_HEADERS=content-type,server
44+
OTEL_PHP_INSTRUMENTATION_HTTP_REQUEST_HEADERS=host,accept
45+
```
46+
47+
#### php.ini configuration
48+
49+
```ini
50+
OTEL_PHP_INSTRUMENTATION_HTTP_RESPONSE_HEADERS=content-type,server
51+
; or
52+
otel.instrumentation.http.response_headers[]=content-type
53+
otel.instrumentation.http.response_headers[]=server
54+
```
55+
56+
57+
Similarly, to capture headers sent in a request to the server, use the following configuration:
58+
59+
```ini
60+
OTEL_PHP_INSTRUMENTATION_HTTP_REQUEST_HEADERS=host,accept
61+
; or
62+
otel.instrumentation.http.request_headers[]=host
63+
otel.instrumentation.http.request_headers[]=accept
64+
```

‎src/Instrumentation/Curl/src/CurlHandleMetadata.php‎

Lines changed: 139 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,139 @@
1+
<?php
2+
3+
declare(strict_types=1);
4+
5+
namespace OpenTelemetry\Contrib\Instrumentation\Curl;
6+
7+
use CurlHandle;
8+
use OpenTelemetry\SemConv\TraceAttributes;
9+
10+
class CurlHandleMetadata
11+
{
12+
private array $attributes = [];
13+
14+
private array $headers = [];
15+
16+
private array $headersToPropagate = [];
17+
18+
private mixed $originalHeaderFunction = null;
19+
private array $responseHeaders = [];
20+
21+
private bool $verboseEnabled = false;
22+
23+
public function __construct()
24+
{
25+
$this->attributes = [TraceAttributes::HTTP_REQUEST_METHOD => 'GET'];
26+
$this->headers = [];
27+
$headersToPropagate = [];
28+
}
29+
30+
public function isVerboseEnabled(): bool
31+
{
32+
return $this->verboseEnabled;
33+
}
34+
public function getAttributes(): array
35+
{
36+
return $this->attributes;
37+
}
38+
39+
public function setAttribute(string $key, mixed $value)
40+
{
41+
$this->attributes[$key] = $value;
42+
}
43+
44+
public function setHeaderToPropagate(string $key, $value): CurlHandleMetadata
45+
{
46+
$this->headersToPropagate[] = $key . ': ' . $value;
47+
48+
return $this;
49+
}
50+
51+
public function getRequestHeadersToSend(): ?array
52+
{
53+
if (count($this->headersToPropagate) == 0) {
54+
return null;
55+
}
56+
$headers = array_merge($this->headersToPropagate, $this->headers);
57+
$this->headersToPropagate = [];
58+
59+
return $headers;
60+
}
61+
62+
public function getCapturedResponseHeaders(): array
63+
{
64+
return $this->responseHeaders;
65+
}
66+
67+
public function getResponseHeaderCaptureFunction()
68+
{
69+
$this->responseHeaders = [];
70+
$func = function (CurlHandle $handle, string $headerLine): int {
71+
72+
$header = trim($headerLine, "\n\r");
73+
if (strlen($header) > 0) {
74+
if (strpos($header, ': ') !== false) {
75+
/** @psalm-suppress PossiblyUndefinedArrayOffset */
76+
list($key, $value) = explode(': ', $header, 2);
77+
$this->responseHeaders[strtolower($key)] = $value;
78+
}
79+
}
80+
81+
if ($this->originalHeaderFunction) {
82+
return call_user_func($this->originalHeaderFunction, $handle, $headerLine);
83+
}
84+
85+
return strlen($headerLine);
86+
};
87+
88+
return \Closure::bind($func, $this, self::class);
89+
}
90+
91+
public function updateFromCurlOption(int $option, mixed $value)
92+
{
93+
switch ($option) {
94+
case CURLOPT_CUSTOMREQUEST:
95+
$this->setAttribute(TraceAttributes::HTTP_REQUEST_METHOD, $value);
96+
97+
break;
98+
case CURLOPT_HTTPGET:
99+
// Based on https://github.com/curl/curl/blob/curl-7_73_0/lib/setopt.c#L841
100+
$this->setAttribute(TraceAttributes::HTTP_REQUEST_METHOD, 'GET');
101+
102+
break;
103+
case CURLOPT_POST:
104+
$this->setAttribute(TraceAttributes::HTTP_REQUEST_METHOD, ($value == 1 ? 'POST' : 'GET'));
105+
106+
break;
107+
case CURLOPT_POSTFIELDS:
108+
// Based on https://github.com/curl/curl/blob/curl-7_73_0/lib/setopt.c#L269
109+
$this->setAttribute(TraceAttributes::HTTP_REQUEST_METHOD, 'POST');
110+
111+
break;
112+
case CURLOPT_PUT:
113+
$this->setAttribute(TraceAttributes::HTTP_REQUEST_METHOD, ($value == 1 ? 'PUT' : 'GET'));
114+
115+
break;
116+
case CURLOPT_NOBODY:
117+
// Based on https://github.com/curl/curl/blob/curl-7_73_0/lib/setopt.c#L269
118+
$this->setAttribute(TraceAttributes::HTTP_REQUEST_METHOD, ($value == 1 ? 'HEAD' : 'GET'));
119+
120+
break;
121+
case CURLOPT_URL:
122+
// $this->setAttribute(TraceAttributes::URL_FULL, self::redactUrlString($value));
123+
break;
124+
case CURLOPT_USERAGENT:
125+
$this->setAttribute(TraceAttributes::USER_AGENT_ORIGINAL, $value);
126+
127+
break;
128+
case CURLOPT_HTTPHEADER:
129+
$this->headers = $value;
130+
131+
break;
132+
case CURLOPT_HEADERFUNCTION:
133+
$this->originalHeaderFunction = $value;
134+
// no break
135+
case CURLOPT_VERBOSE:
136+
$this->verboseEnabled = false;
137+
}
138+
}
139+
}

0 commit comments

Comments
 (0)