docs: add troubleshooting guide - #2040
Conversation
- Document evidence-backed setup and export diagnostics - Link the FAQ from the repository README - Rollback: revert this commit Risk-Level: low AI-Agent: codex Assisted-by: Codex
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #2040 +/- ##
============================================
- Coverage 68.14% 68.06% -0.08%
Complexity 3083 3083
============================================
Files 459 459
Lines 9031 9031
============================================
- Hits 6154 6147 -7
- Misses 2877 2884 +7
Flags with carried forward coverage won't be shown. Click here to find out more. Continue to review full report in Codecov by Harness.
🚀 New features to boost your workflow:
|
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: ce94470819
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| OTEL_PHP_AUTOLOAD_ENABLED=true \ | ||
| OTEL_TRACES_EXPORTER=console \ | ||
| OTEL_METRICS_EXPORTER=none \ | ||
| OTEL_LOGS_EXPORTER=none \ |
There was a problem hiding this comment.
When the process already has OTEL_CONFIG_FILE set, SdkAutoloader::autoload() selects fileBasedInitializer() and does not use OTEL_TRACES_EXPORTER, so this diagnostic command may continue exporting according to the file instead of to the console. This is especially likely for users troubleshooting the file-based setup described later in this guide and defeats the intended isolation test; explicitly unset OTEL_CONFIG_FILE for this command or explain that the exporter must be changed in the configuration file.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
That's a good point, and is worth pointing out in a troubleshooting guide
|
|
||
| ## Where do SDK errors appear? | ||
|
|
||
| SDK warnings and exporter errors are written to PHP's `error_log` by default. |
There was a problem hiding this comment.
When an application has registered a logger through LoggerHolder::set(), LogWriterFactory::create() selects Psr3LogWriter for the default destination, so warnings and exporter errors are sent to that PSR-3 logger rather than PHP's error_log. The unconditional statement can therefore send affected users to the wrong logs; state that error_log is only the fallback when no PSR-3 logger is registered.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
I think "by default" covers this, and the next section clarifies further.
| OTEL_PHP_AUTOLOAD_ENABLED=true \ | ||
| OTEL_TRACES_EXPORTER=console \ | ||
| OTEL_METRICS_EXPORTER=none \ | ||
| OTEL_LOGS_EXPORTER=none \ |
There was a problem hiding this comment.
That's a good point, and is worth pointing out in a troubleshooting guide
| require __DIR__ . '/vendor/autoload.php'; | ||
| ``` | ||
|
|
||
| If a framework loads its `.env` file after Composer autoloading, those values may |
There was a problem hiding this comment.
Something that comes up with Laravel when it starts its own webserver is that only certain env vars are passed through (@ChrisLightfootWild I think could explain it better), but that would be worth generalizing...ie, check what the env values are closer to when they are used
|
|
||
| ## Where do SDK errors appear? | ||
|
|
||
| SDK warnings and exporter errors are written to PHP's `error_log` by default. |
There was a problem hiding this comment.
I think "by default" covers this, and the next section clarifies further.
- Unset OTEL_CONFIG_FILE in the console-exporter diagnostic command.\n- Ensure the check is not overridden by file-based configuration.\n- Rollback: revert this commit to restore the prior diagnostic command. Risk-Level: low AI-Agent: gpt-5.6-sol
2 participants
Summary
Add a troubleshooting and FAQ guide for common OpenTelemetry PHP setup and export problems, and link it from the main README.
The guide covers Composer and autoload timing, no-op providers, extension and instrumentation checks, CLI versus PHP-FPM configuration, OTLP transports, file configuration, short-lived process shutdown, SDK logging, and safe diagnostics.
Fixes #1321
Validation
git diff --check.make helpcould not run in the fresh checkout because the required local.envfile is absent.