WSL and MultiProcessCollector

[kschroeder]

I ran into relatively esoteric issue when using MultiProcessCollector on a Windows Subsystem for Linux installation. I don't know that I would consider it a bug or anything that necessarily requires any developer cycles on it. But I wanted to make it known so the maintainers could at least know about it to fix if they so wish, to document this peculiarity so search engines or AI scrapers can catch it, or to ignore it as just a weird quirk not worth anybody's time.

When using the MultiProcessCollector in a Windows Subsystem for Linux (WSL) environment, metric files in prometheus_multiproc_dir (e.g., counter_.db) have the used field written at offset 0x00010000 (65536 bytes) instead of the expected page-aligned offset (e.g., 0x00000000) when the directory is on a Windows-mounted file system (e.g., /mnt/c/...). This causes the collector to read no data, as it expects used at the start of pages (e.g., 4096-byte boundaries). Moving prometheus_multiproc_dir to a Linux-native file system (e.g., /tmp) resolves the issue, with the used field correctly written at offset 0x00000000.

This appears to be a WSL-specific quirk affecting ftruncate or mmap operations. The file is opened in 'a+b' mode, truncated to _INITIAL_MMAP_SIZE = 65536, and mapped with mmap.mmap(fileno, 65536, MAP_SHARED, PROT_READ|PROT_WRITE, offset=0). Despite file.tell() returning 0 after truncate, writes occur at 0x00010000 on Windows-mounted paths.

Steps to Reproduce

1. In a WSL environment (e.g., WSL2), set prometheus_multiproc_dir to a Windows-mounted path:

import os
from prometheus_client import Counter, MultiProcessCollector, REGISTRY
os.environ['PROMETHEUS_MULTIPROC_DIR'] = '/mnt/c/prometheus_multiproc_dir'
REGISTRY._collector = MultiProcessCollector(REGISTRY)
counter = Counter('my_counter', 'A sample counter')
counter.inc()

2. Run the script and inspect a metric file:

xxd /mnt/c/prometheus_multiproc_dir/counter_<pid>.db

The used field (e.g., 50 04 00 00 for 1104 bytes) appears at offset 0x00010000, with zeros before it.

3. Move prometheus_multiproc_dir to /tmp:

os.environ['PROMETHEUS_MULTIPROC_DIR'] = '/tmp/prometheus_multiproc_dir'

4. Repeat step 2 and the used field is now at 0x00000000, and metrics are collected correctly.

Suggested Action

Add a note to the MultiProcessCollector documentation (e.g., in README.md or multiproc.py) warning WSL users to place prometheus_multiproc_dir on a Linux-native file system (e.g., /tmp, /home/user) to avoid offset issues with Windows-mounted paths (e.g., /mnt/c). Example:

Note for WSL Users: In WSL, set prometheus_multiproc_dir to a Linux-native file system (e.g., /tmp or /home/user) to ensure correct metric file writes. Windows-mounted paths (e.g., /mnt/c) may cause the used field to be written at offset 0x00010000, preventing metric collection.

Additional Context

• No explicit lseek to 65536 was observed via strace, suggesting a WSL file system quirk.
• Moving to /tmp (a tmpfs or ext4 file system) resolved the issue.

[csmarchbanks]

Oh wow, thank you for the detailed writeup! I would be happy to have the note added to our docs, are you interested in opening a PR for that?

[kschroeder]

@csmarchbanks I've submitted the PR. Please let me know if you need anything else.