Expose Lambda request ID and trace ID to environment variables

docs/runtimes/runtimes-details.mdx

@@ -80,6 +80,15 @@ serverless bref:layers
 
 You can use [the `@bref.sh/layers.js` NPM package](https://github.com/brefphp/layers.js) to get up-to-date layer ARNs in Node applications, for example with the AWS CDK.
 
+## Environment variables
+
+Bref exposes the following environment variables on every Lambda invocation:
+
+- **`LAMBDA_REQUEST_ID`**: the current AWS Lambda request ID. This is useful for logging and tracing purposes, for example to group all logs of the same invocation.
+- **`_X_AMZN_TRACE_ID`**: the [AWS X-Ray](https://docs.aws.amazon.com/lambda/latest/dg/services-xray.html) trace ID. This is a standard AWS Lambda variable that is normally set by native runtimes.
+
+These variables are refreshed on every invocation.
+
 ## Telemetry ping
 
 Bref layers send an anonymous ping to estimate the total number of Lambda invocations powered by Bref. That statistic is useful in two ways:

src/Runtime/LambdaRuntime.php

@@ -82,6 +82,9 @@ public function processNextEvent(Handler | RequestHandlerInterface | callable $h
 
         // Expose the context in an environment variable
         $this->setEnv('LAMBDA_INVOCATION_CONTEXT', json_encode($context, JSON_THROW_ON_ERROR));
+        // These are used for logging/tracing purposes
+        $this->setEnv('LAMBDA_REQUEST_ID', $context->getAwsRequestId());
+        $this->setEnv('_X_AMZN_TRACE_ID', $context->getTraceId());
 
         try {
             ColdStartTracker::invocationStarted();

tests/Runtime/LambdaRuntimeTest.php

@@ -431,4 +431,18 @@ public function afterInvoke(mixed ...$params): void
         $this->assertStringContainsString('Invoke Error	{"errorType":"Exception","errorMessage":"Invocation error","stack":', $this->output());
         $this->assertStringContainsString('Invoke Error	{"errorType":"Exception","errorMessage":"This is an exception in afterInvoke","stack":', $this->output());
     }
+
+    public function test request id env variables()
+    {
+        $this->givenAnEvent([]);
+
+        $this->runtime->processNextEvent(function () use (&$requestId, &$traceId) {
+            $requestId = getenv('LAMBDA_REQUEST_ID');
+            $traceId = getenv('_X_AMZN_TRACE_ID');
+            return ['hello' => 'world'];
+        });
+
+        $this->assertSame('1', $requestId);
+        $this->assertSame('Root=1-67891233-abcdef012345678912345678', $traceId);
+    }
 }

tests/RuntimeTestCase.php

@@ -34,6 +34,7 @@ protected function givenAnEvent(mixed $event): void
                 [
                     'lambda-runtime-aws-request-id' => '1',
                     'lambda-runtime-invoked-function-arn' => 'test-function-name',
+                    'lambda-runtime-trace-id' => 'Root=1-67891233-abcdef012345678912345678',
                 ],
                 json_encode($event, JSON_THROW_ON_ERROR)
             ),

website/src/pages/news/03-bref-3.0.mdx

@@ -39,6 +39,7 @@ Here's a summary, we'll dive into the details below:
 - **Unified PHP runtime**: one layer and one container image instead of three.
 - **New regions**: `ap-southeast-3` and `me-central-1`.
 - **Better CloudWatch logs** with the new Monolog formatter enabled by default.
+- **Lambda request ID and trace ID** exposed as environment variables for easier logging.
 - **[Bref Cloud](https://bref.sh/cloud)**: a simpler way to deploy Bref applications.
 
 What did we break? **Almost nothing**, the upgrade should be smooth. Here are the details:
@@ -158,6 +159,15 @@ This format makes logs easier to read in CloudWatch and enables powerful filteri
 
 That new logging approach also allows reading all the logs of a single request, by filtering via the AWS request ID.
 
+## Lambda request ID and trace ID
+
+Bref now exposes the **Lambda request ID** and **X-Ray trace ID** as environment variables on every invocation:
+
+- `LAMBDA_REQUEST_ID`: the current AWS Lambda request ID.
+- `_X_AMZN_TRACE_ID`: the [AWS X-Ray](/xray) trace ID.
+
+These are useful for logging and tracing purposes, for example to group all logs of the same invocation in CloudWatch.
+
 ## New regions
 
 Bref layers are now available in two additional regions: