|
| 1 | +# Debugging |
| 2 | + |
| 3 | +There are a few features built into the Google Cloud PHP client libraries which can help you debug |
| 4 | +your application. This guide will show you how to log client library requests and responses. |
| 5 | + |
| 6 | +> :warning: |
| 7 | +> |
| 8 | +> These logs are not intended to be used in production and are meant to be used only for quickly |
| 9 | +> debugging a project. The logs consists of basic logging to STDOUT, which may or may not include |
| 10 | +> sensitive information. Make sure that once you are done debugging to disable the debugging flag or |
| 11 | +> configuration used to avoid leaking sensitive user data. This may also include authentication |
| 12 | +> tokens. |
| 13 | +
|
| 14 | +## Log examples |
| 15 | + |
| 16 | +```php |
| 17 | +// debug-logging-example.php |
| 18 | +use Google\Cloud\Translate\V3\Client\TranslationServiceClient; |
| 19 | +use Google\Cloud\Translate\V3\TranslateTextRequest; |
| 20 | + |
| 21 | +$client = new TranslationServiceClient(); |
| 22 | + |
| 23 | +$request = new TranslateTextRequest(); |
| 24 | +$request->setTargetLanguageCode('en-US'); |
| 25 | +$request->setContents(['こんにちは']); |
| 26 | +$request->setParent('projects/php-docs-samples-kokoro'); |
| 27 | + |
| 28 | +// The request and response will be logged to STDOUT when the environment |
| 29 | +// variable GOOGLE_SDK_PHP_LOGGING=true |
| 30 | +$response = $client->translateText($request); |
| 31 | +``` |
| 32 | + |
| 33 | +```sh |
| 34 | +$ GOOGLE_SDK_PHP_LOGGING=true php debug-logging-example.php |
| 35 | +{"timestamp":"2024-12-11T19:40:00+00:00","severity":"DEBUG","processId":44180,"jsonPayload":{"serviceName":"google.cloud.translation.v3.TranslationService","clientConfiguration":[]}} |
| 36 | +{"timestamp":"2024-12-11T19:40:00+00:00","severity":"DEBUG","processId":44180,"requestId":3821560043,"jsonPayload":{"request.method":"POST","request.url":"https://oauth2.googleapis.com/token","request.headers":{"Host":["oauth2.googleapis.com"],"Cache-Control":["no-store"],"Content-Type":["application/x-www-form-urlencoded"],"x-goog-api-client":["gl-php/8.3.14 auth/1.45.0 auth-request-type/at cred-type/u"]},"request.payload":"grant_type=refresh_token&refresh_token=<REFRESH_TOKEN>&client_id=<CLIENT_ID>&client_secret=<CLIENT_SECRET>"}} |
| 37 | +{"timestamp":"2024-12-11T19:40:00+00:00","severity":"DEBUG","processId":44180,"requestId":3821560043,"jsonPayload":{"response.status":200,"response.headers":{"x-google-esf-cloud-client-params":["backend_service_name: \"oauth2.googleapis.com\" backend_fully_qualified_method: \"google.identity.oauth2.OAuth2Service.GetToken\""],"X-Google-Session-Info":["<SESSION_INFO>"],"Date":["Wed, 11 Dec 2024 19:40:00 GMT"],"Pragma":["no-cache"],"Expires":["Mon, 01 Jan 1990 00:00:00 GMT"],"Cache-Control":["no-cache, no-store, max-age=0, must-revalidate"],"Content-Type":["application/json; charset=utf-8"],"X-Google-Security-Signals":["FRAMEWORK=ONE_PLATFORM,ENV=borg,ENV_DEBUG=borg_user:identity-oauth2-proxy;borg_job:prod.identity-oauth2-proxy","FRAMEWORK=HTTPSERVER2,BUILD=GOOGLE3,BUILD_DEBUG=cl:694072944,ENV=borg,ENV_DEBUG=borg_user:identity-oauth2-proxy;borg_job:prod.identity-oauth2-proxy"],"Vary":["X-Origin","Referer","Origin,Accept-Encoding"],"Server":["scaffolding on HTTPServer2"],"X-Google-Netmon-Label":["/bns/dz/borg/dz/bns/identity-oauth2-proxy/prod.identity-oauth2-proxy/4"],"X-XSS-Protection":["0"],"X-Frame-Options":["SAMEORIGIN"],"X-Content-Type-Options":["nosniff"],"X-Google-GFE-Service-Trace":["google-identity-oauth2-oauth2proxyservice-prod"],"X-Google-Backends":["unix:/tmp/esfbackend.1733439890.116447.177528,/bns/dz/borg/dz/bns/identity-oauth2-proxy/prod.identity-oauth2-proxy/4,/bns/ncsfoa/borg/ncsfoa/bns/blue-layer1-gfe-prod-edge/prod.blue-layer1-gfe.sfo03s27/15"],"X-Google-GFE-Request-Trace":["acsfon13:443,/bns/dz/borg/dz/bns/identity-oauth2-proxy/prod.identity-oauth2-proxy/4,acsfon13:443"],"X-Google-DOS-Service-Trace":["main:google-identity-oauth2-oauth2proxyservice-prod,main:GLOBAL_all_non_cloud"],"X-Google-GFE-Handshake-Trace":["GFE: /bns/ncsfoa/borg/ncsfoa/bns/blue-layer1-gfe-prod-edge/prod.blue-layer1-gfe.sfo03s27/15,Mentat oracle: [2002:a05:635e:38e:b0:178:f5eb:ee40]:9801"],"X-Google-Service":["google-identity-oauth2-oauth2proxyservice-prod"],"X-Google-GFE-Response-Code-Details-Trace":["response_code_set_by_backend"],"X-Google-GFE-Response-Body-Transformations":["gunzipped,chunked"],"X-Google-Shellfish-Status":["CA0gBEBG"],"X-Google-GFE-Version":["2.903.2"],"Alt-Svc":["h3=\":443\"; ma=2592000,h3-29=\":443\"; ma=2592000"],"Accept-Ranges":["none"],"Transfer-Encoding":["chunked"]},"response.payload":"{\n \"access_token\": \"<ACCESS_TOKEN>\",\n \"expires_in\": 3599,\n \"scope\": \"https://www.googleapis.com/auth/userinfo.email https://www.googleapis.com/auth/sqlservice.login https://www.googleapis.com/auth/cloud-platform openid\",\n \"token_type\": \"Bearer\",\n \"id_token\": \"<ID_TOKEN>","latencyMillis":114}} |
| 38 | +{"timestamp":"2024-12-11T19:40:00+00:00","severity":"DEBUG","processId":44180,"requestId":4274868307,"jsonPayload":{"request.headers":{"x-goog-api-client":["gl-php/8.3.14 gapic/1.20.0 gax/1.36.0 grpc/1.59.1 rest/1.36.0 pb/+n"],"User-Agent":["gcloud-php-new/1.20.0"],"X-Goog-User-Project":["<YOUR_PROJECT>"],"x-goog-request-params":["parent=projects%2F<YOUR_PROJECT>"]},"request.payload":"{\"contents\":[\"こんにちは\"],\"targetLanguageCode\":\"en-US\",\"parent\":\"projects\\/<YOUR_PROJECT>\"}"}} |
| 39 | +{"timestamp":"2024-12-11T19:40:00+00:00","severity":"DEBUG","processId":44180,"requestId":4274868307,"jsonPayload":{"response.status":0,"response.headers":{"pc-high-bwd-bin":["KgIYJQ"]},"response.payload":"{\"translations\":[{\"translatedText\":\"Hello\",\"detectedLanguageCode\":\"ja\"}]}","latencyMillis":242}} |
| 40 | +``` |
| 41 | + |
| 42 | +<details> |
| 43 | +<summary>Request example log (expanded)</summary> |
| 44 | + |
| 45 | +```json |
| 46 | +{ |
| 47 | + "timestamp": "2024-12-03T15:21:47-05:00", |
| 48 | + "severity": "DEBUG", |
| 49 | + "processId": 44180, |
| 50 | + "requestId": 3821560043, |
| 51 | + "jsonPayload": { |
| 52 | + "request.method": "POST", |
| 53 | + "request.url": "https://translate.googleapis.com/v3/projects/<YOUR_PROJECT", |
| 54 | + "request.headers": { |
| 55 | + "Host": [ |
| 56 | + "translate.googleapis.com" |
| 57 | + ], |
| 58 | + "Content-Type": [ |
| 59 | + "application/json" |
| 60 | + ], |
| 61 | + "x-goog-api-client": [ |
| 62 | + "gl-php/8.2.24 gapic/1.20.0 gax/1.35.0 grpc/1.66.0 rest/1.35.0 pb/+n" |
| 63 | + ], |
| 64 | + "User-Agent": [ |
| 65 | + "gcloud-php-new/1.20.0" |
| 66 | + ], |
| 67 | + "X-Goog-User-Project": [ |
| 68 | + "<YOUR_PROJECT>" |
| 69 | + ], |
| 70 | + "x-goog-request-params": [ |
| 71 | + "parent=projects%2F<YOUR_PROJECT>" |
| 72 | + ], |
| 73 | + "authorization": [ |
| 74 | + "Bearer <YOUR_AUTHORIZATION_TOKEN>" |
| 75 | + ] |
| 76 | + }, |
| 77 | + "request.payload": "{\"contents\":[\"こんにちは\"],\"targetLanguageCode\":\"en-US\",\"parent\":\"projects\\/<YOUR_PROJECT>\"}" |
| 78 | + } |
| 79 | +} |
| 80 | +``` |
| 81 | + |
| 82 | +</details> |
| 83 | +<details> |
| 84 | +<summary>Response example log (expanded)</summary> |
| 85 | + |
| 86 | +```json |
| 87 | +{ |
| 88 | + "timestamp": "2024-12-03T15:21:47-05:00", |
| 89 | + "severity": "DEBUG", |
| 90 | + "processId": 44180, |
| 91 | + "requestId": 3821560043, |
| 92 | + "jsonPayload": { |
| 93 | + "response.headers": { |
| 94 | + "Content-Type": [ |
| 95 | + "application/json; charset=UTF-8" |
| 96 | + ], |
| 97 | + "Vary": [ |
| 98 | + "X-Origin", |
| 99 | + "Referer", |
| 100 | + "Origin,Accept-Encoding" |
| 101 | + ], |
| 102 | + "Date": [ |
| 103 | + "Tue, 03 Dec 2024 20:21:47 GMT" |
| 104 | + ], |
| 105 | + "Server": [ |
| 106 | + "ESF" |
| 107 | + ], |
| 108 | + "Cache-Control": [ |
| 109 | + "private" |
| 110 | + ], |
| 111 | + "X-XSS-Protection": [ |
| 112 | + "0" |
| 113 | + ], |
| 114 | + "X-Frame-Options": [ |
| 115 | + "SAMEORIGIN" |
| 116 | + ], |
| 117 | + "X-Content-Type-Options": [ |
| 118 | + "nosniff" |
| 119 | + ], |
| 120 | + "Accept-Ranges": [ |
| 121 | + "none" |
| 122 | + ], |
| 123 | + "Transfer-Encoding": [ |
| 124 | + "chunked" |
| 125 | + ] |
| 126 | + }, |
| 127 | + "response.payload": "{\"translations\":[{\"translatedText\": \"Hello\",\"detectedLanguageCode\":\"ja\"}]}", |
| 128 | + "latencyMillis": 152 |
| 129 | + } |
| 130 | +} |
| 131 | +``` |
| 132 | + |
| 133 | +</details> |
| 134 | + |
| 135 | +## Configuration |
| 136 | + |
| 137 | +There are a few ways to configure debug logging which we will go through in this document. |
| 138 | + |
| 139 | +### The `GOOGLE_SDK_PHP_LOGGING` environment variable |
| 140 | + |
| 141 | +You can enable logging on all the different clients on your code by using this environment variable |
| 142 | +to `true`. Once this environment variable is set, all the clients used on your code will start |
| 143 | +logging the requests into `STDOUT`. |
| 144 | + |
| 145 | +```php |
| 146 | +putenv('GOOGLE_SDK_PHP_LOGGING=true'); |
| 147 | + |
| 148 | +$client = new TranslationServiceClient(); |
| 149 | +``` |
| 150 | + |
| 151 | +Logs usually come with a request log and a response log the exception being streaming requests |
| 152 | +where depending on the type of streaming it logs each stream packet. This means that if the client |
| 153 | +performs a request to the auth server it will also log that request-response pair before the main |
| 154 | +request. |
| 155 | + |
| 156 | + |
| 157 | +### Passing a PSR-3 compliant logger |
| 158 | + |
| 159 | +The debugging code has been made to comply with the PSR-3 logging interface. With in mind we can |
| 160 | +pass a compatible logger to the client configuration. |
| 161 | + |
| 162 | +```php |
| 163 | +use Monolog\Handler\StreamHandler; |
| 164 | +use Monolog\Level; |
| 165 | +use Monolog\Logger; |
| 166 | + |
| 167 | +$monologLogger = new Logger('sdk client'); |
| 168 | +$monologLogger->pushHandler(new StreamHandler('php://stdout', Level::Debug)); |
| 169 | + |
| 170 | +$client = new TranslationServiceClient([ |
| 171 | + 'logger' => $monologLogger |
| 172 | +]); |
| 173 | +``` |
| 174 | + |
| 175 | +With this you now you will be using Monolog's logger instead of the internal one. This also opens |
| 176 | +the opportunity to extend the capabilities of logging in case that you have specific needs, a PSR-3 |
| 177 | +logger implementation can be passed to manage the logs in any way that are needed. |
| 178 | + |
| 179 | +### Passing `false` to the configuration |
| 180 | + |
| 181 | +The `logger` option on the client configuration options disables any logging for that specific |
| 182 | +client. |
| 183 | + |
| 184 | +```php |
| 185 | +$client = new TranslationServiceClient([ |
| 186 | + 'logger' => false |
| 187 | +]); |
| 188 | +``` |
| 189 | + |
| 190 | +With this you can have different clients and either log in only one or disable individual clients |
| 191 | +from logging to avoid excessive noise. |
| 192 | + |
| 193 | +```php |
| 194 | +putenv('GOOGLE_SDK_PHP_LOGGING=true'); |
| 195 | + |
| 196 | +// The Big Table client will log all the requests |
| 197 | +$client = new BigtableClient(); |
| 198 | + |
| 199 | +// The TranslationServiceClient will not log any requests |
| 200 | +$client = new TranslationServiceClient([ |
| 201 | + 'logger' => false |
| 202 | +]); |
| 203 | +``` |
0 commit comments