analyze.flexfs

analyze.flexfs reports storage usage by file, folder, or user. It queries the metadata server’s REST API, either from within a mounted flexFS directory or against a volume named with --volume.

# From within a flexFS mount
cd /mnt/flexfs && analyze.flexfs files

# Or report on a volume that is not mounted here
analyze.flexfs files --volume <volume-name> /data

Persistent Flags

--reportErrors applies to every subcommand. The query flags that files, folders, and users share are listed under each of those commands below.

Flag	Type	Default	Description	Visibility
--reportErrors	bool	false	Report errors and panics to Paradigm4	Public

Subcommands

Subcommand	Description	Visibility
deinit creds	Remove the credentials for a volume	Public
files	Report top files by size, size_bin, or cost	Public
folders	Report per-directory recursive size and cost	Public
init creds	Store the credentials for a volume	Public
users	Report per-user size and cost	Public
version	Print the build version	Public

deinit creds

analyze.flexfs deinit creds <volume-name>

Remove the credentials for a volume. Removing credentials that are not there succeeds, so this is safe to run twice.

Flag	Type	Default	Description	Visibility
--credsFile	string	~/.flexfs/util/creds/<name>	Credentials file path	Public

files

analyze.flexfs files [--limit N] [--orderBy field] [path...]

Reports the top files by size, size_bin, or cost.

Flag	Type	Default	Description	Visibility
--adminAddr	string	""	Admin server address. Only needed to override the one stored in the credentials, or alongside --token when there are none.	Internal
--credsFile	string	~/.flexfs/util/creds/<name>	Credentials file path	Public
--friendly	bool	false	Aligned columns, readable sizes, and dollar costs	Public
--limit	uint32	100	Maximum number of results (1-1000)	Public
--mountPath	string	""	Client mount path. Only needed when reporting on an unmounted volume and the report path passes through symbolic links whose targets are absolute paths; when run from inside a mount, this is detected automatically.	Public
--noAdminSSL	bool	false	Disable SSL for admin server connections	Internal
--noDecode	bool	false	Print base32-encoded paths	Public
--noMetaSSL	bool	false	Disable SSL for metadata server connections	Internal
--orderBy	string	size	Sort field: size, size_bin, or cost	Public
--outputFile, -o	string	""	Output file path. With multiple path arguments, all results go to this one file, with a single header row.	Public
--token	string	""	Volume token to use, instead of reading one from a credentials file	Internal
--volume	string	""	Volume name, to report on a volume that is not mounted here. Selects the credentials file.	Public

folders

analyze.flexfs folders [--maxDepth N] [path...]

Reports per-directory recursive size and cost.

Flag	Type	Default	Description	Visibility
--adminAddr	string	""	Admin server address. Only needed to override the one stored in the credentials, or alongside --token when there are none.	Internal
--credsFile	string	~/.flexfs/util/creds/<name>	Credentials file path	Public
--friendly	bool	false	Aligned columns, readable sizes, and dollar costs	Public
--maxDepth	uint32	0	Maximum query depth (0 = unlimited)	Public
--mountPath	string	""	Client mount path. Only needed when reporting on an unmounted volume and the report path passes through symbolic links whose targets are absolute paths; when run from inside a mount, this is detected automatically.	Public
--noAdminSSL	bool	false	Disable SSL for admin server connections	Internal
--noDecode	bool	false	Print base32-encoded paths	Public
--noMetaSSL	bool	false	Disable SSL for metadata server connections	Internal
--outputFile, -o	string	""	Output file path. With multiple path arguments, all results go to this one file, with a single header row.	Public
--token	string	""	Volume token to use, instead of reading one from a credentials file	Internal
--volume	string	""	Volume name, to report on a volume that is not mounted here. Selects the credentials file.	Public

init creds

analyze.flexfs init creds --adminAddr <admin-host:port> [flags]

Store the volume token analyze.flexfs uses for a volume. The token is prompted for unless --token is given. The volume’s name is taken from the admin server, so the credentials are always filed under the name a mount reports, and the token is checked for the admin flag before anything is written. init on its own does the same thing as init creds.

Flag	Type	Default	Description	Visibility
--adminAddr	string	""	Admin server address (required)	Public
--credsFile	string	~/.flexfs/util/creds/<name>	Credentials file path	Public
--force	bool	false	Overwrite existing credentials file	Public
--noAdminSSL	bool	false	Disable SSL for admin server connections	Internal
--token	string	""	Volume token (prompted for if omitted)	Public
--volume	string	""	Volume name, checked against the token	Public

Credentials

analyze.flexfs queries the metadata server, which requires a volume token carrying the admin flag. Store one per volume:

analyze.flexfs init creds --adminAddr admin.example.com:443

The command prompts for the token, confirms with the admin server that it allows reporting queries, and files it under the volume’s name. See Volume Tokens for how to obtain one.

Credentials are looked for in this order:

1. ~/.flexfs/util/creds/<volume-name>, written by analyze.flexfs init creds.
2. ~/.flexfs/mount/creds/<volume-name>, written by mount.flexfs init creds for the same user.

analyze.flexfs, dedup.flexfs and find.flexfs share the first of these, so one init creds serves all three — and one deinit creds removes the credentials all three were using.

Both files must be readable only by their owner (chmod 600); a file readable by others is refused.

--credsFile moves the first of these. Give the same value to init creds and to the query, or credentials will be written somewhere the query does not look — and to the other two utilities as well, if they are to go on sharing one file. Each user needs their own credentials, since a mount created by root keeps its credentials where other users cannot read them.

Tokens scoped to a subdirectory

A volume token can be issued for one subdirectory of a volume rather than the whole of it (see Volume Tokens). Every query made with such a token is answered from that subdirectory, whichever part of the volume the mount itself shows.

analyze.flexfs accounts for the difference, so paths are always given the way they look on this machine. With a volume mounted whole at /flexfs-1 and a token scoped to /sub-1:

analyze.flexfs folders /flexfs-1/sub-1        # the token's whole subtree
analyze.flexfs folders /flexfs-1/sub-1/data   # part of it
analyze.flexfs folders /flexfs-1              # refused: outside the token's subtree

The first of those is the same query as analyze.flexfs folders --volume <name> /, which names the path as the token sees it because no mount is involved to interpret it against.

To make the adjustment, analyze.flexfs asks the admin server what the token is scoped to — once per volume, on every run. Nothing about the token is cached on disk, so a token that is reissued or re-scoped needs no re-initialization, and a token passed with --token is treated exactly like a stored one. The admin server must therefore be reachable for a query made inside a mount.

users

analyze.flexfs users [--limit N] [--orderBy field] [path...]

Reports per-user size and cost. Resolves UIDs to usernames when possible.

Flag	Type	Default	Description	Visibility
--adminAddr	string	""	Admin server address. Only needed to override the one stored in the credentials, or alongside --token when there are none.	Internal
--credsFile	string	~/.flexfs/util/creds/<name>	Credentials file path	Public
--friendly	bool	false	Aligned columns, readable sizes, and dollar costs	Public
--limit	uint32	100	Maximum number of results (1-1000)	Public
--mountPath	string	""	Client mount path. Only needed when reporting on an unmounted volume and the report path passes through symbolic links whose targets are absolute paths; when run from inside a mount, this is detected automatically.	Public
--noAdminSSL	bool	false	Disable SSL for admin server connections	Internal
--noDecode	bool	false	Print base32-encoded paths	Public
--noMetaSSL	bool	false	Disable SSL for metadata server connections	Internal
--orderBy	string	cost	Sort field: size or cost	Public
--outputFile, -o	string	""	Output file path. With multiple path arguments, all results go to this one file, with a single header row.	Public
--token	string	""	Volume token to use, instead of reading one from a credentials file	Internal
--volume	string	""	Volume name, to report on a volume that is not mounted here. Selects the credentials file.	Public

Output format

By default, output is tab-separated with a header row. The first line always contains column names. The files subcommand outputs path followed by size/cost fields. The folders subcommand outputs path followed by aggregate stats. The users subcommand outputs UID, username, and cost fields.

Default (TSV) output

analyze.flexfs files --limit 5 /mnt/flexfs

path  size  size_bin  cost
/data/genome/sample1.bam  52428800000  62  15.23
/data/genome/sample2.bam  48318382080  61  14.02
/data/genome/reference.fa  3221225472  4  1.50
/data/logs/pipeline.log  104857600  0  0.05
/data/tmp/scratch.dat  10737418240  45  1.12

Friendly output

When --friendly is set, output uses aligned columns with human-readable sizes (GiB, MiB, etc.), dollar-formatted costs, and day ranges since last use in interval notation. Headers are always included.

analyze.flexfs files --friendly --limit 5 /mnt/flexfs

path                                        size    cost                     last_active
/mnt/flexfs/data/genome/sample1.bam    48.83 GiB  $15.23  [1860, 1890) days ago (bin 62)
/mnt/flexfs/data/genome/sample2.bam    45.00 GiB  $14.02  [1830, 1860) days ago (bin 61)
/mnt/flexfs/data/genome/reference.fa    3.00 GiB   $1.50    [120, 150) days ago (bin  4)
/mnt/flexfs/data/logs/pipeline.log    100.00 MiB   $0.05          < 30 days ago (bin  0)
/mnt/flexfs/data/tmp/scratch.dat       10.00 GiB   $1.12  [1350, 1380) days ago (bin 45)

The last_active column is a billing tier expressed as an age, not a precise last-I/O timestamp: a file’s tier moves only once its use is sustained. See Size Bin.

For folders, friendly mode renders an ASCII directory tree:

analyze.flexfs folders --friendly --maxDepth 2 /mnt/flexfs

path                  size    cost
/mnt/flexfs      62.83 GiB  $17.69
├── data         52.83 GiB  $16.52
│   ├── genome   51.83 GiB  $16.02
│   ├── logs    100.00 MiB   $0.05
│   └── tmp      10.00 GiB   $1.12
└── scratch      10.00 GiB   $1.17

For users:

analyze.flexfs users --friendly /mnt/flexfs

uid    user        size    cost
1001  alice   48.83 GiB  $15.23
1002    bob   10.00 GiB   $1.12
0      root  100.00 MiB   $0.05

Cost field

The cost field is an estimated monthly storage cost in US dollars ($/month). It is calculated per file as:

cost = (effective_size / 1 GiB) * rate

Where:

• effective_size is the smaller of the file’s logical size and its allocated block size (blksize * blocks). This prevents sparse files from being overcharged.
• rate is a per-GiB monthly dollar rate determined by the file’s size bin — an activity-based tier reflecting how long since the file’s data was last read or written. Each 30-day increment maps to a bin (bin 0 = active within the last 30 days, bin 1 = 30-60 days ago, up to bin 127). Rate bins are configured per account and can assign different $/GiB/month rates to each tier, enabling tiered pricing where recently-active “hot” data may cost more than cold data. See Size Bin for what counts as activity.
• Files with multiple hard links are counted only once.
• For folders and users, the cost is the sum of per-file costs within the scope.

The metadata server fetches rates from the admin server and caches them for a few minutes, falling back to its last copy for up to a day while the admin server is unreachable. A query that reports or filters on cost fails with cost unavailable, rather than reporting a cost of zero, when no rates are available at all. Every analyze.flexfs report includes cost, so all of them depend on the rates; find.flexfs needs them only when a cost field or cost filter is used.

Symbolic links

Report paths may pass through symbolic links; links that stay within the volume are followed automatically. A link whose target points outside the volume returns an error that names the link. Error messages are written to standard error, so piped or redirected report output stays clean.