diff --git a/docs/environment/logs.mdx b/docs/environment/logs.mdx index 36c25eff5..550339e8c 100644 --- a/docs/environment/logs.mdx +++ b/docs/environment/logs.mdx @@ -5,6 +5,7 @@ description: "Learn how to write and read PHP logs on AWS Lambda using Bref." import { Tabs } from 'nextra/components'; import Image from 'next/image'; import brefCloudLogs from '../cloud/logs.png'; +import brefCloudTraceLogs from '../monitoring/cloud-trace-logs.png'; # Logs @@ -115,3 +116,45 @@ AWS Lambda has a built-in mechanism to forward logs written to `stderr` (or `std ``` + +### Logs of a single request + +Every Lambda invocation (an HTTP request, a queue job, a console command…) has a **request ID**. Lambda writes it in its `START`, `END` and `REPORT` lines, and the `Bref\Monolog\CloudWatchFormatter` formatter starts every log line with it: + +``` +8f507cfc-8b35-4e7e-9f26-f2a3a6e7e1a2 ERROR Payment failed {"message":"Payment failed","level":"ERROR",...} +``` + +Search for a request ID to see everything that happened during that invocation: the application logs, Bref's errors (for example a timeout), and Lambda's `REPORT` line with the duration and the memory used. + + + + In the [Bref Cloud](https://bref.sh/cloud) dashboard, click the request ID next to a log line to see all the logs of that request. The [X-Ray trace](/docs/monitoring#traces) of a request also shows its logs: + + The logs of a request below its X-Ray trace in Bref Cloud + + From the terminal, search for the request ID with `bref logs`. Its first 8 characters are enough, like in the dashboard: + + ```bash + bref logs --env=prod --search=8f507cfc --all + ``` + + + In CloudWatch Logs Insights, select the log group of the function and filter on the `@requestId` field: + + ``` + fields @timestamp, @message + | filter @requestId = '8f507cfc-8b35-4e7e-9f26-f2a3a6e7e1a2' + | sort @timestamp asc + ``` + + + +If you use another log formatter, the request ID of the current invocation is available in `$_SERVER['LAMBDA_REQUEST_ID']`. For example, to add it to every Monolog record: + +```php +$logger->pushProcessor(function (Monolog\LogRecord $record) { + $record->extra['requestId'] = $_SERVER['LAMBDA_REQUEST_ID'] ?? null; + return $record; +}); +``` diff --git a/docs/monitoring/cloud-trace-logs.png b/docs/monitoring/cloud-trace-logs.png new file mode 100644 index 000000000..750ad53dd Binary files /dev/null and b/docs/monitoring/cloud-trace-logs.png differ