Runtimes in detail

AWS Lambda layers

Bref runtimes are distributed as AWS Lambda layers . While Bref provides a Serverless plugin to simplify how to use them, you can use the layers directly.

The layer names (aka “ARN ”) follow this pattern:

arn:aws:lambda:<region>:873528684822:layer:<layer-name>:<layer-version>

For example:

arn:aws:lambda:us-east-1:873528684822:layer:php-84:25

There is one layer per PHP version (php-82 to php-85, and arm-php-82 to arm-php-85 for ARM functions). The same layer runs all Bref runtimes: the BREF_RUNTIME environment variable selects the runtime, and the function’s handler has a different meaning for each:

When BREF_RUNTIME is not set, the function fails on every invocation with “The environment variable BREF_RUNTIME is not set”.

You can use layers via their full ARN, for example in serverless.yml:

service: app
provider:
    name: aws
functions:
    hello:
        handler: public/index.php
        runtime: provided.al2023
        layers:
            - 'arn:aws:lambda:us-east-1:873528684822:layer:php-84:25'
        environment:
            BREF_RUNTIME: fpm

Or if you are using SAM’s template.yaml:

AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Resources:
    Hello:
        Type: AWS::Serverless::Function
        Properties:
            # ...
            Handler: public/index.php
            Runtime: provided.al2023
            Layers:
                - 'arn:aws:lambda:us-east-1:873528684822:layer:php-84:25'
            Environment:
                Variables:
                    BREF_RUNTIME: fpm

Bref layers work with AWS Lambda regardless of the tool you use to deploy your application: Serverless, SAM, CloudFormation, Terraform, AWS CDK, etc.

Layer versions

All the layer/runtime versions can be found at runtimes.bref.sh.

Here are the latest versions:

You can also find the appropriate ARN/version for your current Bref version by running:

serverless bref:layers

Layers NPM package

You can use the @bref.sh/layers NPM package to get up-to-date layer ARNs in Node applications. With the AWS CDK, use Bref’s CDK constructs instead.

Environment variables

Bref exposes the following environment variables on every Lambda invocation, in all runtimes:

• 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  trace ID. This is a standard AWS Lambda variable that is normally set by native runtimes.
• LAMBDA_INVOCATION_CONTEXT: the Lambda context as a JSON-encoded string.

The PHP-FPM runtime also exposes LAMBDA_REQUEST_CONTEXT: the API Gateway request context as a JSON-encoded string.

These variables are refreshed on every invocation.

The Bref plugin for serverless.yml sets these variables on deployment:

• BREF_RUNTIME: the runtime to start, set from runtime: php-xx, php-xx-fpm or php-xx-console. Set it yourself (fpm, function or console) when you use the layers (see above) or the Docker images directly.
• BREF_STACK_NAME: the name of the CloudFormation stack (see Variables set by Bref).

You can set these variables to change how Bref behaves:

• BREF_LOOP_MAX: the number of invocations a PHP process handles before restarting (default: 1). See keeping the PHP process alive.
• BREF_AUTOLOAD_PATH: the path to Composer’s autoload.php if the vendor directory is not at the root of the project (see Custom vendor path).
• BREF_BINARY_RESPONSES: set to 1 to return binary HTTP responses (see Binary requests and responses).
• BREF_PING_DISABLE: set to 1 to disable the telemetry ping.

Telemetry ping

Bref’s runtime (the bref/bref Composer package) sends an anonymous ping to estimate the total number of Lambda invocations powered by Bref. That statistic is useful in two ways:

• to provide new users an idea on how much Bref is used in production
• to communicate to AWS how much Bref is used and push for better PHP integration with AWS Lambda tooling

We consider this to be beneficial both to the Bref project (to get more users and more consideration from AWS) and for Bref users (more users means a larger community, a stronger and more active project, as well as more features from AWS).

So far, knowing the number of Bref invocations has helped Bref grow, be recognized by AWS, and opened a lot of doors.

Data

You can find the latest number of AWS Lambda invocations on the Bref homepage .

On the month of the Bref 1.0 release, Bref was powering 1 billion invocations per month.

On the month of the Bref 2.0 release, Bref was powering 10 billion invocations per month.

On the month of the Bref 3.0 release, Bref was powering 40 billion invocations per month.

What is sent

The data sent in the ping is completely anonymous. It does not contain any identifiable data about anything (the project, users, etc.).

The only data it contains is: A Bref invocation happened with the runtime XYZ (where XYZ is the name of the Bref runtime, like “function”, “fpm” or “console”) and whether the invocation was a cold start.

Here is an example payload:

Invocations_100:1|c\nLayer_fpm_100:1|c\nCold_100:1|c\nWarm_100:0|c

Anyone can inspect the code and the data sent by checking the Bref\Runtime\LambdaRuntime::ping() function.

How is it sent

The data is sent via the statsd  protocol, over UDP .

Unlike TCP, UDP does not check that the message correctly arrived at the server. It doesn’t even establish a connection. That means that UDP is extremely fast: the data is sent over the network and the code moves on to the next line. When actually sending data, the overhead of that ping takes about 150 micro-seconds.

However, this function actually sends data in 1% of invocations (picked at random), because we don’t need to measure all invocations. We only need an approximation. That means that 99% of the time, no data is sent, and the function takes 30 micro-seconds. If we average all executions, the overhead of that ping is about 31 micro-seconds.

Given that it is much much less than even 1 milli-second, we consider that overhead negligible.

Disabling

The ping can be disabled by setting a BREF_PING_DISABLE environment variable to 1.