diff --git a/README.md b/README.md index 3de9b8b..c78a5d5 100644 --- a/README.md +++ b/README.md @@ -40,6 +40,89 @@ $amplitude->init('APIKEY', 'johnny@example.com') // This is a simple example to get you started, see the rest of the readme for more examples ``` +## Getting Started & Troubleshooting + +When you are initially getting your application set up, if you do not see your event show up in Amplitude, you may need to do a little troubleshooting. Normally your indication that "it worked" is when you see your event show up in your Amplitude app for the first time. + +If you never see that first event show up, you can see what Amplitude's response is when the event is logged. This may help find and fix the problem (such as an invalid API key, PHP environment errors, connection problems, etc.) + +Amplitude uses `Psr\Logger` for logging the communication with the Amplitude HTTP API. You can take advantage of this by setting a logger (using `$amlitude->setLogger()`) to help catch any problems. + +### Stand-alone Troubleshooting Script + +Below is a stand-alone script, meant to be copied into a PHP file at the root of your application's document root. Just change the `APIKEY` and if needed, adjust the line that requires the `autoload.php` file for composer. Then visit the script's URL from a browser to see any messages logged. + +```php +".ucfirst($level).": $message
"; + if (!empty($context)) { + echo 'Context:
'.print_r($context,true).''; + } + } +} + +$chatty = new ChattyLogger(); +// Test logging an event +?> + +

Testing Amplitude Log Event Response

+

API Key: ''

+setLogger($chatty); + +// Initialize Amplitude with the API key and a dummy test user ID +$amplitude->init($apikey, 'TEST-USER-ID'); + +$chatty->info('Calling $amplitude->logEvent(\'TEST EVENT\')...'); + +// Log a test event +$amplitude->logEvent('TEST EVENT'); + +$chatty->info('Done logging event'); +``` + +### Troubleshooting Tips + +* The Amplitude library will throw a `LogicException` for any problems caused by errors in the code, for instance if you try to log an event without setting the API key first, or try to log an event without specifying the event type. Make sure your server's error logging is set up to display (or otherwise log) any exceptions that might be thrown so that you can see if there is a coding error causing a problem. +* Make sure PHP error logging is enabled (or display errors is enabled), so you can see any PHP errors that may point to the problem. +* Use the `setLogger(...)` method in amplitude to use your app's logging or your own custom logger like the standalone test script above. As long as it implements the `Psr\Log\LoggerInterface`. + * If no logs are generated: It did not attempt to send an event after the point your app's logger was set, or the event was logged using a different instance that does not have a logger set. + * If you see `Curl error:` logged: then something went wrong when it tried to send the request, the error message and context should help point to the problem. + * If there are no curl errors, it will log a message starting with `Amplitude HTTP API response:`: + * `success` with `httpCode = 200` : Amplitude got the request and the event should have been logged. If you are not seeing it in Amplitude, check again after a few minutes, sometimes Amplitude can lag a little behind. + * Anything Else: The event was not logged successfully, refer to the message and context to help troubleshoot the problem. + # Logging Anonymous Users Since this is a PHP SDK, there are a lot of options for tracking Anonymous users. Since this could be run in CLI mode or as a cron job, this SDK does not handle sessions for you. diff --git a/composer.json b/composer.json index 5081885..8f380d9 100644 --- a/composer.json +++ b/composer.json @@ -16,7 +16,8 @@ } ], "require": { - "php": ">=5.4" + "php": ">=5.4", + "psr/log": "^1.0" }, "require-dev": { "phpunit/phpunit": "4.8.*", diff --git a/src/Amplitude.php b/src/Amplitude.php index e048102..1208807 100644 --- a/src/Amplitude.php +++ b/src/Amplitude.php @@ -1,8 +1,12 @@ apiKey = (string)$apiKey; } + // Initialize logger to be null logger + $this->setLogger(new Log\NullLogger()); } /** @@ -456,7 +478,7 @@ public function getOptOut() * * Requres $this->event and $this->apiKey to be set, otherwise it throws an exception. * - * @return integer|boolean HTTP Status code or boolean false if problem making connection + * @return void * @throws \InternalErrorException If event or api key not set */ protected function sendEvent() @@ -464,19 +486,36 @@ protected function sendEvent() if (empty($this->event) || empty($this->apiKey)) { throw new \InternalErrorException('Event or api key not set, cannot send event'); } + $ch = curl_init(static::AMPLITUDE_API_URL); + if (!$ch) { + // Could be a number of PHP environment problems, log a critical error + $this->logger->critical( + 'Call to curl_init(' . static::AMPLITUDE_API_URL . ') failed, unable to send Amplitude event' + ); + return; + } $postFields = [ 'api_key' => $this->apiKey, 'event' => json_encode($this->event), ]; - $ch = curl_init(static::AMPLITUDE_API_URL); - if (!$ch) { - return false; - } curl_setopt($ch, \CURLOPT_POSTFIELDS, $postFields); - curl_exec($ch); - - $status = curl_getinfo($ch, \CURLINFO_HTTP_CODE); + // Always return instead of outputting response! + curl_setopt($ch, \CURLOPT_RETURNTRANSFER, true); + $response = curl_exec($ch); + $curlErrno = curl_errno($ch); + if ($curlErrno) { + $this->logger->critical( + 'Curl error: ' . curl_error($ch), + compact('curlErrno', 'response', 'postFields') + ); + } else { + $httpCode = curl_getinfo($ch, \CURLINFO_HTTP_CODE); + $this->logger->log( + $httpCode === 200 ? Log\LogLevel::INFO : Log\LogLevel::ERROR, + 'Amplitude HTTP API response: ' . $response, + compact('httpCode', 'response', 'postFields') + ); + } curl_close($ch); - return (int)$status; } }