| <?php | |
| /** | |
| * Copyright 2007 Google Inc. | |
| * | |
| * Licensed under the Apache License, Version 2.0 (the "License"); | |
| * you may not use this file except in compliance with the License. | |
| * You may obtain a copy of the License at | |
| * | |
| * http://www.apache.org/licenses/LICENSE-2.0 | |
| * | |
| * Unless required by applicable law or agreed to in writing, software | |
| * distributed under the License is distributed on an "AS IS" BASIS, | |
| * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | |
| * See the License for the specific language governing permissions and | |
| * limitations under the License. | |
| */ | |
| /** | |
| */ | |
| namespace google\appengine\api\log; | |
| use google\appengine\LogReadRequest; | |
| use google\appengine\LogReadResponse; | |
| use google\appengine\LogServiceError\ErrorCode; | |
| use google\appengine\runtime\ApiProxy; | |
| use google\appengine\runtime\ApplicationError; | |
| use google\appengine\util\StringUtil; | |
| /** | |
| * The LogService allows an application to query for request and application | |
| * logs. Application logs are added to a the current request log by calling | |
| * @link http://php.net/manual/en/function.syslog.php syslog(int $priority, | |
| * string $message). The $priority used when creating the application log is | |
| * translated into a different scale of severity used by the LogService. | |
| * | |
| * Application logs have a level in order of increasing severity: | |
| * <table> | |
| * <tr><th>syslog $priority</th><th>GAE severity</th></tr> | |
| * <tr><td>LOG_DEBUG</td><td>LogService::LEVEL_DEBUG</td></tr> | |
| * <tr><td>LOG_INFO</td><td>LogService::LEVEL_INFO</td></tr> | |
| * <tr><td>LOG_NOTICE</td><td>LogService::LEVEL_INFO</td></tr> | |
| * <tr><td>LOG_WARNING</td><td>LogService::LEVEL_WARNING</td></tr> | |
| * <tr><td>LOG_ERR</td><td>LogService::LEVEL_ERROR</td></tr> | |
| * <tr><td>LOG_CRIT</td><td>LogService::LEVEL_CRITICAL</td></tr> | |
| * <tr><td>LOG_ALERT</td><td>LogService::LEVEL_CRITICAL</td></tr> | |
| * <tr><td>LOG_EMERG</td><td>LogService::LEVEL_CRITICAL</td></tr> | |
| * <table> | |
| * | |
| * When fetching application logs or filtering request logs by severity use the | |
| * values in the right hand column. | |
| */ | |
| final class LogService { | |
| use ApiProxyAccess; | |
| /** | |
| * Constants for application log levels. | |
| */ | |
| const LEVEL_DEBUG = 0; | |
| const LEVEL_INFO = 1; | |
| const LEVEL_WARNING = 2; | |
| const LEVEL_ERROR = 3; | |
| const LEVEL_CRITICAL = 4; | |
| /** | |
| * The maximum number of request logs returned in each batch. | |
| */ | |
| const MAX_BATCH_SIZE = 1000; | |
| // Map syslog priority levels to appengine severity levels. | |
| private static $syslog_priority_map = array( | |
| LOG_EMERG => self::LEVEL_CRITICAL, | |
| LOG_ALERT => self::LEVEL_CRITICAL, | |
| LOG_CRIT => self::LEVEL_CRITICAL, | |
| LOG_ERR => self::LEVEL_ERROR, | |
| LOG_WARNING => self::LEVEL_WARNING, | |
| LOG_NOTICE => self::LEVEL_INFO, | |
| LOG_INFO => self::LEVEL_INFO, | |
| LOG_DEBUG => self::LEVEL_DEBUG); | |
| // Validation patterns copied from google/appengine/api/logservice/logservice.py | |
| private static $MAJOR_VERSION_ID_REGEX = | |
| '/^(?:(?:((?!-)[a-z\d\-]{1,63}):)?)((?!-)[a-z\d\-]{1,100})$/'; | |
| private static $REQUEST_ID_REGEX = '/^[\da-fA-F]+$/'; | |
| /** | |
| * Get request logs matching the given options in reverse chronological | |
| * order of request end time. | |
| * | |
| * @param array $options Optional associateive arrary of filters and | |
| * modifiers from following: | |
| * | |
| * <ul> | |
| * <li>'start_time': <code>DateTime or numeric</code> The earliest | |
| * completion time or last-update time for request logs. If the value is | |
| * numeric it represents microseconds since Unix epoch.</li> | |
| * <li>'end_time': <code>DateTime or numeric</code> The latest completion | |
| * time or last-update time for request logs. If the value is numeric it | |
| * represents microseconds since Unix epoch.</li> | |
| * <li>'offset': <code>string</code> The url-safe offset value from a | |
| * <code>RequestLog</code> to continue iterating after.</li> | |
| * <li>'minimum_log_level': <code>integer</code> Only return request logs | |
| * containing at least one application log of this severity or higher. | |
| * Works even if include_app_logs is not <code>true</code></li> | |
| * <li>'include_incomplete': <code>boolean</code> Should incomplete request | |
| * logs be included. The default is <code>false</code> - only completed | |
| * logs are returned</li> | |
| * <li>'include_app_logs': <code>boolean</code> Should application logs be | |
| * returned. The default is <code>false</code> - application logs are not | |
| * returned with their containing request logs.</li> | |
| * <li>'versions': <code>array</code> The versions of the default module | |
| * for which to fetch request logs. Only one of 'versions' and | |
| * 'module_versions' can be used.</li> | |
| * <li>'module_versions': <code>arrary/code> An associative array of module | |
| * names to versions for which to fetch request logs. Each module name may | |
| * be mapped to either a single <code>string</code> version or an <code> | |
| * array</code> of versions.</li> | |
| * <li>'batch_size': <code>integer</code> The number of request logs to | |
| * pre-fetch while iterating.</li> | |
| * </ul> | |
| * | |
| * @return Iterator The matching <code>RequestLog</code> items. | |
| */ | |
| public static function fetch(array $options = []) { | |
| $request = new LogReadRequest(); | |
| $request->setAppId(getenv('APPLICATION_ID')); | |
| // Required options default values - overridden by options below. | |
| $batch_size = 20; | |
| $include_app_logs = false; | |
| $include_incomplete = false; | |
| foreach ($options as $key => $value) { | |
| switch ($key) { | |
| case 'start_time': | |
| if (is_numeric($value)) { | |
| $usec = (double) $value; | |
| } else if ($value instanceof \DateTime) { | |
| $usec = self::dateTimeToUsecs($value); | |
| } else { | |
| self::optionTypeException($key, $value, 'DateTime or numeric'); | |
| } | |
| $request->setStartTime($usec); | |
| break; | |
| case 'end_time': | |
| if (is_numeric($value)) { | |
| $usec = (double) $value; | |
| } else if ($value instanceof \DateTime) { | |
| $usec = self::dateTimeToUsecs($value); | |
| } else { | |
| self::optionTypeException($key, $value, 'DateTime or numeric'); | |
| } | |
| $request->setEndTime($usec); | |
| break; | |
| case 'offset': | |
| if (!is_string($value)) { | |
| self::optionTypeException($key, $value, 'string'); | |
| } | |
| $decoded = StringUtil::base64UrlDecode($value); | |
| $request->mutableOffset()->parseFromString($decoded); | |
| break; | |
| case 'minimum_log_level': | |
| if (!is_int($value)) { | |
| self::optionTypeException($key, $value, 'integer'); | |
| } | |
| if ($value > self::LEVEL_CRITICAL || | |
| $value < self::LEVEL_DEBUG) { | |
| throw new \InvalidArgumentException( | |
| "Option 'minimum_log_level' must be from " . | |
| self::LEVEL_DEBUG . " to " . | |
| self::LEVEL_CRITICAL); | |
| } | |
| $request->setMinimumLogLevel($value); | |
| break; | |
| case 'include_incomplete': | |
| if (!is_bool($value)) { | |
| self::optionTypeException($key, $value, 'boolean'); | |
| } | |
| $include_incomplete = $value; | |
| break; | |
| case 'include_app_logs': | |
| if (!is_bool($value)) { | |
| self::optionTypeException($key, $value, 'boolean'); | |
| } | |
| $include_app_logs = $value; | |
| break; | |
| case 'module_versions': | |
| if (!is_array($value)) { | |
| self::optionTypeException($key, $value, 'array'); | |
| } | |
| if (isset($options['versions'])) { | |
| throw new \InvalidArgumentException( | |
| "Only one of 'versions' or " . | |
| "'module_versions' may be set"); | |
| } | |
| foreach ($value as $module => $versions) { | |
| if (!is_string($module)) { | |
| throw new \InvalidArgumentException( | |
| 'Server must be a string but was ' . | |
| self::typeOrClass($module)); | |
| } | |
| // Versions can be a single string or an array of strings. | |
| if (is_array($versions)) { | |
| foreach ($versions as $version) { | |
| if (!is_string($version)) { | |
| throw new \InvalidArgumentException( | |
| 'Server version must be a string but was ' . | |
| self::typeOrClass($version)); | |
| } | |
| $module_version = $request->addModuleVersion(); | |
| if ($module !== 'default') { | |
| $module_version->setModuleId($module); | |
| } | |
| $module_version->setVersionId($version); | |
| } | |
| } else if (is_string($versions)) { | |
| $module_version = $request->addModuleVersion(); | |
| $module_version->setModuleId($module); | |
| $module_version->setVersionId($versions); | |
| } else { | |
| throw new \InvalidArgumentException( | |
| 'Server version must be a string or array but was ' . | |
| self::typeOrClass($versions)); | |
| } | |
| } | |
| break; | |
| case 'versions': | |
| if (!is_array($value)) { | |
| self::optionTypeException($key, $value, 'array'); | |
| } | |
| if (isset($options['module_versions'])) { | |
| throw new \InvalidArgumentException( | |
| "Only one of 'versions' or " . | |
| "'module_versions' may be set"); | |
| } | |
| foreach ($value as $version) { | |
| if (!is_string($version)) { | |
| throw new \InvalidArgumentException( | |
| 'Version must be a string but was ' . | |
| self::typeOrClass($version)); | |
| } | |
| if (!preg_match(self::$MAJOR_VERSION_ID_REGEX, $version)) { | |
| throw new \InvalidArgumentException( | |
| "Invalid version id " . htmlspecialchars($version)); | |
| } | |
| $request->addModuleVersion()->setVersionId($version); | |
| } | |
| break; | |
| case 'batch_size': | |
| if (!is_int($value)) { | |
| self::optionTypeException($key, $value, 'integer'); | |
| } | |
| if ($value > self::MAX_BATCH_SIZE || $value < 1) { | |
| throw new \InvalidArgumentException( | |
| 'Batch size must be > 0 and <= ' . self::MAX_BATCH_SIZE); | |
| } | |
| $batch_size = $value; | |
| break; | |
| default: | |
| throw new \InvalidArgumentException( | |
| "Invalid option " . htmlspecialchars($key)); | |
| } | |
| } | |
| // Set required options. | |
| $request->setIncludeIncomplete($include_incomplete); | |
| $request->setIncludeAppLogs($include_app_logs); | |
| $request->setCount($batch_size); | |
| // Set version to the current version if none set explicitly. | |
| if ($request->getModuleVersionSize() === 0) { | |
| self::setDefaultModuleVersion($request); | |
| } | |
| return new RequestLogIterator($request); | |
| } | |
| private static function setDefaultModuleVersion($request) { | |
| $mv = $request->addModuleVersion(); | |
| $current_module = getenv('CURRENT_MODULE_ID'); | |
| if ($current_module !== 'default') { | |
| $mv->setModuleId($current_module); | |
| } | |
| $current_version = getenv('CURRENT_VERSION_ID'); | |
| $whole_version = explode('.', $current_version)[0]; | |
| $mv->setVersionId($whole_version); | |
| } | |
| /** | |
| * Get request logs for the given request log ids and optionally include the | |
| * application logs addded during each request. Request log ids that are not | |
| * found are ignored so the returned array may have fewer items than | |
| * <code>$request_ids</code>. | |
| * | |
| * @param mixed $request_ids A string request id or an array of string request | |
| * ids obtained from <code>RequestLog::getRequestId()</code>. | |
| * @param boolean $include_app_logs Should applicaiton logs be included in the | |
| * fetched request logs. Defaults to true - application logs are included. | |
| * | |
| * @return RequestLog[] The request logs for ids that were found. | |
| */ | |
| public static function fetchById($request_ids, $include_app_logs = true) { | |
| $request = new LogReadRequest(); | |
| $request->setAppId(getenv('APPLICATION_ID')); | |
| if (!is_bool($include_app_logs)) { | |
| throw new \InvalidArgumentException( | |
| 'Parameter $include_app_logs must be boolean but was ' . | |
| typeOrClass($include_app_logs)); | |
| } | |
| $request->setIncludeAppLogs($include_app_logs); | |
| self::setDefaultModuleVersion($request); | |
| if (is_string($request_ids)) { | |
| if (!preg_match(self::$REQUEST_ID_REGEX, $request_ids)) { | |
| throw new \InvalidArgumentException( | |
| "Invalid request id " . htmlspecialchars($request_ids)); | |
| } | |
| $request->addRequestId($request_ids); | |
| } else if (is_array($request_ids)) { | |
| foreach ($request_ids as $id) { | |
| if (!is_string($id)) { | |
| throw new \InvalidArgumentException( | |
| 'Request id must be a string but was ' . | |
| self::typeOrClass($id)); | |
| } | |
| if (!preg_match(self::$REQUEST_ID_REGEX, $id)) { | |
| throw new \InvalidArgumentException( | |
| "Invalid request id " . htmlspecialchars($id)); | |
| } | |
| $request->addRequestId($id); | |
| } | |
| } else { | |
| throw new \InvalidArgumentException( | |
| 'Expected a string or an array of strings but was '. | |
| self::typeOrClass($value)); | |
| } | |
| $response = self::readLogs($request); | |
| $result = []; | |
| foreach ($response->getLogList() as $log) { | |
| $result[] = new RequestLog($log); | |
| } | |
| return $result; | |
| } | |
| /** | |
| * Translates a PHP <syslog>syslog<syslog> priority level into a Google App | |
| * Engine severity level. Useful when filtering logs by minimum severity | |
| * level given the syslog level. | |
| * | |
| * @param integer $syslog_level The priority level passed to | |
| * <code>syslog</code>. | |
| * @return integer The app engine severity level. | |
| */ | |
| public static function getAppEngineLogLevel($syslog_level) { | |
| return self::$syslog_priority_map[$syslog_level]; | |
| } | |
| private static function optionTypeException($key, $value, $expected) { | |
| throw new \InvalidArgumentException( | |
| htmlspecialchars("Option $key must be type $expected but was ") . | |
| self::typeOrClass($value)); | |
| } | |
| /** | |
| * @return string The type or class name if type is object. | |
| */ | |
| private static function typeOrClass($value) { | |
| if (is_object($value)) { | |
| return get_class($value); | |
| } else { | |
| return gettype($value); | |
| } | |
| } | |
| private static function dateTimeToUsecs($datetime) { | |
| // DateTime is accurate to seconds, StartTime to micro seconds. | |
| // The time stamp may only represent a date up to 2038 due to 32 bit ints. | |
| return (double) $datetime->getTimeStamp() * 1e6; | |
| } | |
| /** | |
| * The GAE PECL extension calls this directly instead of the built-in syslog. | |
| */ | |
| private static function syslog($priority, $message) { | |
| $log_level = self::getAppEngineLogLevel($priority); | |
| self::log($log_level, $message); | |
| if (function_exists('_gae_syslog')) { | |
| _gae_syslog($log_level, $message); | |
| } | |
| } | |
| } | |
| /** | |
| * @internal | |
| */ | |
| trait ApiProxyAccess { | |
| /** | |
| * @param LogReadRequest $request The protocol buffer request to fetch. | |
| * | |
| * @return LogReadResponse The response including RequestLogs. | |
| */ | |
| private static function readLogs(LogReadRequest $request) { | |
| $response = new LogReadResponse(); | |
| try { | |
| ApiProxy::makeSyncCall('logservice', 'Read', $request, $response); | |
| } catch (ApplicationError $e) { | |
| throw self::applicationErrorToException($e); | |
| } | |
| return $response; | |
| } | |
| private static function applicationErrorToException(ApplicationError $error) { | |
| switch($error->getApplicationError()) { | |
| case ErrorCode::INVALID_REQUEST: | |
| return new LogException('Invalid Request'); | |
| case ErrorCode::STORAGE_ERROR: | |
| return new LogException('Storage Error'); | |
| default: | |
| return new LogException( | |
| 'Error Code: ' . $error->getApplicationError()); | |
| } | |
| } | |
| } |