Skip to content

Commit 7202ae2

Browse files
overtrueovertrue
authored
Merge pull request #1 from overtrue/dev
wip
2 parents b293bb5 + 72cf701 commit 7202ae2

File tree

72 files changed

+5451
-2425
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

72 files changed

+5451
-2425
lines changed

‎README.md

Lines changed: 254 additions & 227 deletions
Large diffs are not rendered by default.

‎_register.php

Lines changed: 0 additions & 27 deletions
This file was deleted.

‎composer.json

Lines changed: 2 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -6,10 +6,7 @@
66
"autoload": {
77
"psr-4": {
88
"Overtrue\\LaravelOpenTelemetry\\": "src/"
9-
},
10-
"files": [
11-
"_register.php"
12-
]
9+
}
1310
},
1411
"authors": [
1512
{
@@ -19,21 +16,17 @@
1916
],
2017
"require": {
2118
"php": ">=8.4",
22-
"ext-opentelemetry": "*",
2319
"laravel/framework": "^10.0|^11.0|^12.0",
2420
"open-telemetry/api": "^1.0",
2521
"open-telemetry/sdk": "^1.0",
2622
"open-telemetry/exporter-otlp": "^1.3",
27-
"open-telemetry/opentelemetry-auto-laravel": "^1.2"
23+
"open-telemetry/sem-conv": "^1.32"
2824
},
2925
"require-dev": {
3026
"orchestra/testbench": "^9.0",
3127
"laravel/pint": "^1.15",
3228
"spatie/test-time": "^1.3"
3329
},
34-
"suggest": {
35-
"open-telemetry/opentelemetry-auto-guzzle": "If you want to automatically instrument Guzzle HTTP client requests."
36-
},
3730
"autoload-dev": {
3831
"psr-4": {
3932
"Overtrue\\LaravelOpenTelemetry\\Tests\\": "tests/"

‎config/otel.php

Lines changed: 61 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -3,32 +3,67 @@
33
return [
44

55
/**
6-
* The name of the header that will be used to pass the trace id in the response.
7-
* if set to `null`, the header will not be added to the response.
6+
* Enable or disable OpenTelemetry tracing
7+
* When disabled, no watchers will be registered and no tracing will occur
88
*/
9-
'response_trace_header_name' => env('OTEL_RESPONSE_TRACE_HEADER_NAME', 'X-Trace-Id'),
9+
'enabled' => env('OTEL_ENABLED', true),
10+
11+
/**
12+
* The name of the tracer that will be used to create spans.
13+
* This is useful for identifying the source of the spans.
14+
*/
15+
'tracer_name' => env('OTEL_TRACER_NAME', 'overtrue.laravel-open-telemetry'),
16+
17+
/**
18+
* Middleware Configuration
19+
*/
20+
'middleware' => [
21+
/**
22+
* Trace ID Middleware Configuration
23+
* Used to add X-Trace-Id to response headers
24+
*/
25+
'trace_id' => [
26+
'enabled' => env('OTEL_TRACE_ID_MIDDLEWARE_ENABLED', true),
27+
'global' => env('OTEL_TRACE_ID_MIDDLEWARE_GLOBAL', true),
28+
'header_name' => env('OTEL_TRACE_ID_HEADER_NAME', 'X-Trace-Id'),
29+
],
30+
],
31+
32+
/**
33+
* HTTP Client Configuration
34+
*/
35+
'http_client' => [
36+
/**
37+
* Global Request Middleware Configuration
38+
* Automatically adds OpenTelemetry propagation headers to all HTTP requests
39+
*/
40+
'propagation_middleware' => [
41+
'enabled' => env('OTEL_HTTP_CLIENT_PROPAGATION_ENABLED', true),
42+
],
43+
],
1044

1145
/**
1246
* Watchers Configuration
13-
* Note: Starting from v2.0, we use OpenTelemetry's official auto-instrumentation
14-
* Most tracing functionality is provided by the opentelemetry-auto-laravel package
15-
* This package provides the following additional Watcher functionality:
1647
*
1748
* Available Watcher classes:
49+
* - \Overtrue\LaravelOpenTelemetry\Watchers\CacheWatcher::class
50+
* - \Overtrue\LaravelOpenTelemetry\Watchers\QueryWatcher::class
51+
* - \Overtrue\LaravelOpenTelemetry\Watchers\HttpClientWatcher::class
1852
* - \Overtrue\LaravelOpenTelemetry\Watchers\ExceptionWatcher::class
1953
* - \Overtrue\LaravelOpenTelemetry\Watchers\AuthenticateWatcher::class
2054
* - \Overtrue\LaravelOpenTelemetry\Watchers\EventWatcher::class
2155
* - \Overtrue\LaravelOpenTelemetry\Watchers\QueueWatcher::class
2256
* - \Overtrue\LaravelOpenTelemetry\Watchers\RedisWatcher::class
23-
* - \Overtrue\LaravelOpenTelemetry\Watchers\FrankenPhpWorkerWatcher::class
2457
*/
2558
'watchers' => [
59+
\Overtrue\LaravelOpenTelemetry\Watchers\CacheWatcher::class,
60+
\Overtrue\LaravelOpenTelemetry\Watchers\QueryWatcher::class,
61+
\Overtrue\LaravelOpenTelemetry\Watchers\HttpClientWatcher::class, // 已添加智能重复检测，可以同时使用
2662
\Overtrue\LaravelOpenTelemetry\Watchers\ExceptionWatcher::class,
2763
\Overtrue\LaravelOpenTelemetry\Watchers\AuthenticateWatcher::class,
2864
\Overtrue\LaravelOpenTelemetry\Watchers\EventWatcher::class,
2965
\Overtrue\LaravelOpenTelemetry\Watchers\QueueWatcher::class,
3066
\Overtrue\LaravelOpenTelemetry\Watchers\RedisWatcher::class,
31-
\Overtrue\LaravelOpenTelemetry\Watchers\FrankenPhpWorkerWatcher::class,
3267
],
3368

3469
/**
@@ -54,9 +89,23 @@
5489
* Ignore paths will not be traced. You can use `*` as wildcard.
5590
*/
5691
'ignore_paths' => explode(',', env('OTEL_IGNORE_PATHS', implode(',', [
57-
'horizon*',
58-
'telescope*',
59-
'_debugbar*',
60-
'health*',
92+
'up',
93+
'horizon*', // Laravel Horizon dashboard
94+
'telescope*', // Laravel Telescope dashboard
95+
'_debugbar*', // Laravel Debugbar
96+
'health*', // Health check endpoints
97+
'ping', // Simple ping endpoint
98+
'status', // Status endpoint
99+
'metrics', // Metrics endpoint
100+
'favicon.ico', // Browser favicon requests
101+
'robots.txt', // SEO robots file
102+
'sitemap.xml', // SEO sitemap
103+
'api/health', // API health check
104+
'api/ping', // API ping
105+
'admin/health', // Admin health check
106+
'internal/*', // Internal endpoints
107+
'monitoring/*', // Monitoring endpoints
108+
'_profiler/*', // Symfony profiler (if used)
109+
'.well-known/*', // Well-known URIs (RFC 8615)
61110
]))),
62111
];

‎examples/configuration_guide.php

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
<?php
2+
3+
/**
4+
* Laravel OpenTelemetry Configuration Guide
5+
*
6+
* This file demonstrates how to use the new HTTP client configuration options
7+
*/
8+
9+
// 1. Check if OpenTelemetry is enabled
10+
if (config('otel.enabled', true)) {
11+
echo "OpenTelemetry is enabled\n";
12+
} else {
13+
echo "OpenTelemetry is disabled\n";
14+
}
15+
16+
// 2. Check tracer name
17+
$tracerName = config('otel.tracer_name', 'overtrue.laravel-open-telemetry');
18+
echo "Tracer name: {$tracerName}\n";
19+
20+
// 3. Check middleware configuration
21+
$traceIdEnabled = config('otel.middleware.trace_id.enabled', true);
22+
$traceIdGlobal = config('otel.middleware.trace_id.global', true);
23+
$traceIdHeaderName = config('otel.middleware.trace_id.header_name', 'X-Trace-Id');
24+
25+
echo 'Trace ID Middleware enabled: '.($traceIdEnabled ? 'Yes' : 'No')."\n";
26+
echo 'Trace ID Middleware global: '.($traceIdGlobal ? 'Yes' : 'No')."\n";
27+
echo "Trace ID Header name: {$traceIdHeaderName}\n";
28+
29+
// 4. Check new HTTP client configuration
30+
$httpClientPropagationEnabled = config('otel.http_client.propagation_middleware.enabled', true);
31+
echo 'HTTP Client propagation middleware enabled: '.($httpClientPropagationEnabled ? 'Yes' : 'No')."\n";
32+
33+
// 5. View all available watchers
34+
$watchers = config('otel.watchers', []);
35+
echo "Available watchers:\n";
36+
foreach ($watchers as $watcher) {
37+
echo " - {$watcher}\n";
38+
}
39+
40+
// 6. Environment variable configuration examples
41+
echo "\n=== Environment Variable Examples ===\n";
42+
echo "OTEL_ENABLED=true\n";
43+
echo "OTEL_TRACER_NAME=my-app\n";
44+
echo "OTEL_TRACE_ID_MIDDLEWARE_ENABLED=true\n";
45+
echo "OTEL_TRACE_ID_MIDDLEWARE_GLOBAL=true\n";
46+
echo "OTEL_TRACE_ID_HEADER_NAME=X-Custom-Trace-Id\n";
47+
echo "OTEL_HTTP_CLIENT_PROPAGATION_ENABLED=true\n";
48+
49+
// 7. Demonstrate how to use in code
50+
use Illuminate\Support\Facades\Http;
51+
use Overtrue\LaravelOpenTelemetry\Facades\Measure;
52+
53+
// Fully automatic HTTP request tracing
54+
// No manual code needed - all requests through Http facade are automatically traced with context propagation
55+
$response = Http::get('https://httpbin.org/ip');
56+
57+
// View tracing status
58+
$status = Measure::getStatus();
59+
echo "\n=== Tracing Status ===\n";
60+
echo 'Recording: '.($status['is_recording'] ? 'Yes' : 'No')."\n";
61+
echo 'Current trace ID: '.($status['current_trace_id'] ?? 'None')."\n";
62+
echo 'Active spans count: '.$status['active_spans_count']."\n";
63+
echo 'Tracer provider: '.$status['tracer_provider']['class']."\n";
64+
65+
// 8. How to disable HTTP client propagation middleware
66+
echo "\n=== How to Disable HTTP Client Propagation ===\n";
67+
echo "In your .env file, set:\n";
68+
echo "OTEL_HTTP_CLIENT_PROPAGATION_ENABLED=false\n";
69+
echo "\nOr in config/otel.php:\n";
70+
echo "'http_client' => [\n";
71+
echo " 'propagation_middleware' => [\n";
72+
echo " 'enabled' => false,\n";
73+
echo " ],\n";
74+
echo "],\n";

‎examples/duplicate_tracing_test.php

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
<?php
2+
3+
/**
4+
* Duplicate Tracing Prevention Test
5+
*
6+
* This file demonstrates how HttpClientWatcher intelligently avoids duplicate tracing
7+
* through automatic context propagation using Laravel's globalRequestMiddleware
8+
*/
9+
echo "=== HTTP Client Tracing Solution ===\n\n";
10+
11+
echo "Previous Issue:\n";
12+
echo "HTTP requests could potentially be traced multiple times if different\n";
13+
echo "mechanisms were attempting to instrument the same request.\n\n";
14+
15+
echo "Current Solution:\n";
16+
echo "- HttpClientWatcher creates spans for all HTTP requests\n";
17+
echo "- Laravel's globalRequestMiddleware automatically adds propagation headers\n";
18+
echo "- Smart duplicate detection prevents overlapping instrumentation\n";
19+
echo "- Fully automatic - no manual configuration required\n\n";
20+
21+
echo "How it works:\n";
22+
23+
// Example 1: Automatic tracing (HttpClientWatcher handles everything)
24+
echo "1. Automatic HTTP request tracing:\n";
25+
echo " Http::get('https://httpbin.org/ip')\n";
26+
echo " → HttpClientWatcher creates span\n";
27+
echo " → globalRequestMiddleware adds propagation headers\n";
28+
echo " → Single span created automatically\n\n";
29+
30+
// Example 2: Context propagation in microservices
31+
echo "2. Microservice context propagation:\n";
32+
echo " Http::get('http://service-b/api/users')\n";
33+
echo " → Automatically includes trace context in headers\n";
34+
echo " → Service B can continue the trace seamlessly\n\n";
35+
36+
echo "Key Features:\n";
37+
echo "- No manual withTrace() calls needed\n";
38+
echo "- Automatic propagation headers (traceparent, tracestate, etc.)\n";
39+
echo "- Smart duplicate detection\n";
40+
echo "- Works with all Laravel HTTP client usage patterns\n";
41+
echo "- Zero configuration required\n\n";
42+
43+
echo "Configuration Options:\n";
44+
echo "You can disable automatic propagation if needed:\n";
45+
echo "OTEL_HTTP_CLIENT_PROPAGATION_ENABLED=false\n\n";
46+
echo "Or in config/otel.php:\n";
47+
echo "'http_client' => [\n";
48+
echo " 'propagation_middleware' => ['enabled' => false]\n";
49+
echo "]\n\n";
50+
51+
echo "Best Practices:\n";
52+
echo "1. Let HttpClientWatcher handle all HTTP request tracing automatically\n";
53+
echo "2. Use Measure::trace() for custom business logic spans\n";
54+
echo "3. No need to manually add tracing to HTTP client calls\n";
55+
echo "4. Context propagation happens automatically across services\n\n";
56+
57+
echo "Result:\n";
58+
echo "Every HTTP request is traced exactly once with proper context propagation\n";
59+
echo "between microservices - completely automatically!\n";

0 commit comments

Comments
 (0)