Bound the number of array items serialized in stack frame arguments to limit memory usage on large arrays

Start in AbstractSerializer::serializeRecursively(), where the array loop copies every item up to max depth, and in serializeObject() for stdClass properties. Run the repro script with the default and bounded serializers to measure peak memory. Done means arrays stop at a breadth limit, the omitted count is recorded as a marker, and the default serializer's peak drops. The limit's default value and option name are still open, so confirm them with maintainers before coding.

Problem Statement

Hello,

When an exception is captured, RepresentationSerializer serializes the arguments of every frame. AbstractSerializer::serializeRecursively() loops over every item of an array up to maxDepth (3) and builds a full serialized copy of it:

if (\is_array($value)) {
    $serializedArray = [];

    foreach ($value as $k => $v) {
        $serializedArray[$k] = $this->serializeRecursively($v, $_depth + 1);
    }

    return $serializedArray;
}

Arrays are only reduced to Array of length N at the max depth. max_value_length only applies to strings, class_serializers only to objects, and before_send runs after serialization, when the memory is already used.

So when a frame holds a large array passed down a few function calls, the SDK builds a second, bigger copy of that structure just to report the error. This increases peak memory a lot at exactly the moment the process is already failing and makes it more likely that the produced event is above the 1MB envelope limit, and then gets silently dropped.

For comparison, the Python SDK bounds frame variables with MAX_DATABAG_BREADTH = 10 and MAX_DATABAG_DEPTH = 5 (sentry_sdk/serializer.py). It stops iterating a container once the breadth is reached and records the original length in _meta, so the work per variable is bounded whatever the size of the data.

Solution Brainstorm

Align AbstractSerializer with the Python SDK:

• Add a limit on items per array, either as a max_breadth-style option or a default of 10 like Python. Iteration would stop at the limit and add a marker giving the number of items left out (e.g. '{truncated}' => '499990 more items')
• Apply the same limit to stdClass properties in serializeObject().
• Cut the string representation of every leaf to max_value_length, not only strings, as Python does.

As a workaround we use a serializer similar to the BoundedRepresentationSerializer below. The script reproduces the issue with either the default serializer or the bounded one to be able to compare them:

<?php

// php -d memory_limit=-1 -d zend.exception_ignore_args=0 -d auto_prepend_file=../vendor/autoload.php repro.php [default|bounded]

use Sentry\ClientBuilder;
use Sentry\Options;
use Sentry\SentrySdk;
use Sentry\Serializer\RepresentationSerializer;

/**
 * Applies the same limits as the Python SDK (MAX_DATABAG_BREADTH and MAX_DATABAG_DEPTH): stops iterating an array after
 * MAX_BREADTH items, does not go deeper than MAX_DEPTH, and truncates the representation of every leaf to
 * max_value_length, not only strings.
 */
class BoundedRepresentationSerializer extends RepresentationSerializer
{
    public const MAX_BREADTH = 10;

    public const MAX_DEPTH = 5;

    public const TRUNCATED = '{truncated}';

    public function __construct(Options $options, ?string $mbDetectOrder = null)
    {
        parent::__construct($options, self::MAX_DEPTH, $mbDetectOrder);
    }

    protected function serializeRecursively($value, int $_depth = 0)
    {
        // stdClass properties are walked by serializeObject() without going through this method, so bound them as arrays
        if ($value instanceof \stdClass) {
            $value = (array) $value;
        }

        // Stop iterating bigger arrays after MAX_BREADTH items. At max depth, the parent only gives the array length
        if (\is_array($value) && \count($value) > self::MAX_BREADTH && $_depth < self::MAX_DEPTH) {
            $serialized = [];
            $i = 0;
            foreach ($value as $key => $item) {
                if ($i >= self::MAX_BREADTH) {
                    break;
                }
                $serialized[$key] = $this->serializeRecursively($item, $_depth + 1);
                ++$i;
            }
            $serialized[self::TRUNCATED] = \sprintf('%d more items', \count($value) - self::MAX_BREADTH);

            return $serialized;
        }

        $serialized = parent::serializeRecursively($value, $_depth);

        // The parent only truncates strings, so the representation of other values (objects, callables) is truncated here
        if (\is_string($serialized) && !\is_string($value)) {
            $serialized = $this->serializeString($serialized);
        }

        return $serialized;
    }
}

// No DSN: the event is fully prepared (stacktrace and frame arguments serialized) but not sent
$options = new Options(['dsn' => null]);
$builder = new ClientBuilder($options);
if (($argv[1] ?? 'default') === 'bounded') {
    $builder->setRepresentationSerializer(new BoundedRepresentationSerializer($options));
}
SentrySdk::init()->bindClient($builder->getClient());

function fail(array $rows): void
{
    throw new RuntimeException('boom');
}

$rows = array_fill(0, 500_000, ['id' => 1, 'name' => str_repeat('x', 50), 'value' => 1.5]);

$before = memory_get_usage();
memory_reset_peak_usage();
$start = hrtime(true);

try {
    fail($rows);
} catch (Throwable $e) {
    Sentry\captureException($e);
}

printf("peak +%.1f MB, %.0f ms\n", (memory_get_peak_usage() - $before) / 1024 / 1024, (hrtime(true) - $start) / 1e6);

Results:

php -d memory_limit=-1 -d zend.exception_ignore_args=0 -d auto_prepend_file=../vendor/autoload.php repro.php default
peak +241.5 MB, 1826 ms

php -d memory_limit=-1 -d zend.exception_ignore_args=0 -d auto_prepend_file=../vendor/autoload.php repro.php bounded
peak +0.8 MB, 3 ms

php 8.5
sentry/sentry 4.33.1

Thanks!