# Memory Distribution

Memory distributions are used to accumulate and store memory sizes.

Memory distributions are recorded in a histogram where the buckets have an exponential distribution, specifically with 16 buckets for every power of 2. That is, the function from a value $$x$$ to a bucket index is:

$\lfloor 16 \log_2(x) \rfloor$

This makes them suitable for measuring memory sizes on a number of different scales without any configuration.

Note Check out how this bucketing algorithm would behave on the Simulator.

## Recording API

### accumulate

Accumulates the provided sample in the metric.

import org.mozilla.yourApplication.GleanMetrics.Memory

fun allocateMemory(nbytes: Int) {
// ...
Memory.heapAllocated.accumulate(nbytes / 1024)
}

import org.mozilla.yourApplication.GleanMetrics.Memory;

fun allocateMemory(nbytes: Int) {
// ...
Memory.INSTANCE.heapAllocated().accumulate(nbytes / 1024);
}

import Glean

func allocateMemory(nbytes: UInt64) {
// ...
Memory.heapAllocated.accumulate(nbytes / 1024)
}

from glean import load_metrics

def allocate_memory(nbytes):
# ...
metrics.memory.heap_allocated.accumulate(nbytes / 1024)


#![allow(unused)]
fn main() {
use glean_metrics::memory;

fn allocate_memory(bytes: u64) {
// ...
memory::heap_allocated.accumulate(bytes / 1024);
}
}


C++

#include "mozilla/glean/GleanMetrics.h"

mozilla::glean::memory::heap_allocated.Accumulate(bytes / 1024);


JavaScript

Glean.memory.heapAllocated.accumulate(bytes / 1024);


## Testing API

### testGetValue

Gets the recorded value for a given memory distribution metric.

import org.mozilla.yourApplication.GleanMetrics.Memory

// Get snapshot
val snapshot = Memory.heapAllocated.testGetValue()

// Does the sum have the expected value?
assertEquals(11, snapshot.sum)

// Usually you don't know the exact memory values,
// but how many should have been recorded.
assertEquals(2L, snapshot.count)

import org.mozilla.yourApplication.GleanMetrics.Memory;

// Get snapshot
val snapshot = Memory.INSTANCE.heapAllocated().testGetValue();

// Does the sum have the expected value?
assertEquals(11, snapshot.sum);

// Usually you don't know the exact memory values,
// but how many should have been recorded.
assertEquals(2L, snapshot.getCount());

// Get snapshot
let snapshot = try! Memory.heapAllocated.testGetValue()

// Does the sum have the expected value?
XCTAssertEqual(11, snapshot.sum)

// Usually you don't know the exact memory values,
// but how many should have been recorded.
XCTAssertEqual(2, snapshot.count)

from glean import load_metrics

# Get snapshot.
snapshot = metrics.memory.heap_allocated.test_get_value()

# Does the sum have the expected value?
assert 11 == snapshot.sum

# Usually you don't know the exact memory values,
# but how many should have been recorded.
assert 2 == snapshot.count


#![allow(unused)]
fn main() {
use glean::ErrorType;
use glean_metrics::memory;

// Get snapshot
let snapshot = memory::heap_allocated.test_get_value(None).unwrap();

// Does the sum have the expected value?
assert_eq!(11, snapshot.sum);

// Usually you don't know the exact timing values,
// but how many should have been recorded.
assert_eq!(2, snapshot.values.len());
}


C++

#include "mozilla/glean/GleanMetrics.h"

// Does it have an expected values?
const data = mozilla::glean::memory::heap_allocated.TestGetValue().value().unwrap()
ASSERT_EQ(11 * 1024, data.sum);


JavaScript

const data = Glean.memory.heapAllocated.testGetValue();
Assert.equal(11 * 1024, data.sum);


### testHasValue

Whether or not any value was recorded for a given memory distribution metric.

import org.mozilla.yourApplication.GleanMetrics.Pages

// Get snapshot
assertTrue(Memory.heapAllocated.testHasValue())

import org.mozilla.yourApplication.GleanMetrics.Pages;

// Was anything recorded?
assertTrue(Memory.INSTANCE.heapAllocated().testHasValue());

// Was anything recorded?
XCTAssert(Memory.heapAllocated.testHasValue())

from glean import load_metrics

# Was anything recorded?


### testGetNumRecordedErrors

Gets number of errors recorded for a given memory distribution metric.

import org.mozilla.yourApplication.GleanMetrics.Memory

// Did this record a negative value?
assertEquals(
0,
Memory.heapAllocated.testGetNumRecordedErrors(ErrorType.InvalidValue)
)

import org.mozilla.yourApplication.GleanMetrics.Memory;

// Assert that no errors were recorded.
assertEquals(
0,
Memory.INSTANCE.heapAllocated().testGetNumRecordedErrors(
ErrorType.InvalidValue
)
);

// Did this record a negative value?
XCTAssertEqual(0, Memory.heapAllocated.testGetNumRecordedErrors(.invalidValue))

from glean import load_metrics

# Did this record a negative value?
assert 0 == metrics.memory.heap_allocated.test_get_num_recorded_errors(
ErrorType.INVALID_VALUE
)

use glean::ErrorType;
use glean_metrics::pages;

assert_eq!(
0,
);


## Metric parameters

Example memory distribution metric definition:

memory:
heap_allocated:
type: memory_distribution
memory_unit: kilobyte
description: >
The heap memory allocated
bugs:
- https://bugzilla.mozilla.org/000000
data_reviews:
- https://bugzilla.mozilla.org/show_bug.cgi?id=000000#c3
- me@mozilla.com
expires: 2020-10-01


### Extra metric parameters

#### memory_unit

Memory distributions have a required memory_unit parameter, which specifies the unit the incoming memory size values are recorded in. The allowed values for time_unit are:

• byte
• kilobyte (= 2^10 = 1,024 bytes)
• megabyte (= 2^20 = 1,048,576 bytes)
• gigabyte (= 2^30 = 1,073,741,824 bytes)

## Limits

• The maximum memory size that can be recorded is 1 Terabyte (240 bytes). Larger sizes will be truncated to 1 Terabyte.

## Data questions

• What is the distribution of the size of heap allocations?

## Simulator

Note The data provided, is assumed to be in the configured memory unit. The data recorded, on the other hand, is always in bytes. This means that, if the configured memory unit is not byte, the data will be transformed before being recorded. Notice this, by using the select field above to change the memory unit and see the mean of the data recorded changing.