bacula-sd

title: bacula-sd(8)

summary: Bacula's Storage Daemon

text:
# bacula-sd(8)

## NAME
bacula-sd - Bacula's Storage Daemon

## SYNOPSIS
bacula-sd [options]

## DESCRIPTION
This manual page documents briefly the bacula-sd command.

Bacula's Storage Daemon acts as the interface between the Bacula network backup system and a tape drive/autochanger or filesystem where the backups will be stored.

## OPTIONS
-c file

Specify the configuration file to use.

-d nn

Set debug level to nn.

-dt

Print timestamp in debug output.

-T

Send debug messages to the trace file.

-f

Run in foreground (for debugging).

-g group

Set the group/gid to run as.

-P

Do not create a PID file.

-p

Proceed in spite of I/O errors

-m

Print kaboom output (for debugging)

-s

No signals (for debugging).

-t

Test the configuration file and report errors.

-u user

Set the username/uid to run as.

-v

Set verbose mode.

-?

Show version and usage of program.

## SEE ALSO
bacula-dir(8), bacula-fd(8).

## AUTHOR
This manual page was written by Jose Luis Tallon <jltallon@adv-solutions.net>.

## COPYRIGHT
This man page document is released under the BSD 2-Clause license.


bextract

title: bextract(8)

summary: Bacula's 'Extract from tape'

text:
# bextract(8)

## NAME

bextract - Bacula's 'Extract from tape'

## SYNOPSIS
bextract [options] bacula-archive-device-name output-directory

## DESCRIPTION
This manual page documents briefly the bextract command.

## OPTIONS
A summary of options is included below.

-?

Show version and usage of program.

-b bootstrap

Specify a bootstrap file.

-c config

Specify configuration file.

-d nn

Set debug level to nn.

-dt

Print timestamp in debug output.

-e file

Specify exclude list.

-i file

Specify include list.

-p

Proceed in spite of I/O errors.

-t

Read data from volume, do not write anything

-v

Set verbose mode.

-V volume-name

Specify volume names.

## SEE ALSO
bls(1), bextract(1).

## AUTHOR
This manual page was written by Jose Luis Tallon <jltallon@adv-solutions.net>.

## COPYRIGHT
This man page document is released under the BSD 2-Clause license.


bls

title: bls(8)

summary: Bacula's 'Tape LS'

text:
# bls(8)

## NAME

bls - Bacula's 'Tape LS'

## SYNOPSIS
bls [options] <device-name>

## DESCRIPTION
This manual page documents briefly the bls command.

## OPTIONS
A summary of options is included below.

-?

Show version and usage of program.

-b bootstrap

Specify a bootstrap file.

-c config

Specify configuration file.

-d nn

Set debug level to nn.

-dt

Print timestamp in debug output

-e <file>

Specify exclude list file.

-i <file>

Specify include list file.

-j

List jobs.

-k

List blocks.

(no -j or -k option)

List saved files

-L

Dump label.

-p

Proceed in spite of errors.

-V volumes

Specify volume names (separated by '|').

-v

Set verbose mode.

## SEE ALSO
bscan(8), bextract(8).

## AUTHOR
This manual page was written by Jose Luis Tallon <jltallon@adv-solutions.net>.

## COPYRIGHT
This man page document is released under the BSD 2-Clause license.


btape

title: btape(8)

summary: Bacula's Tape interface test program

text:
# btape(8)

## NAME

btape - Bacula's Tape interface test program

## SYNOPSIS
btape [options] device-name

## DESCRIPTION
This manual page documents briefly the btape command.

## OPTIONS
A summary of options is included below.

-?

Show summary of options and commands.

-b bootstrap

Specify a bootstrap file.

-c config

Specify configuration file.

-d nn

Set debug level to nn.

-p

Proceed inspite of I/O errors.

-s

No signals (for debugging).

-v

Set verbose mode.

## COMMANDS
autochanger

test autochanger

bsf

backspace file

bsr

backspace record

cap

list device capabilities

clear

clear tape errors

eod

go to end of Bacula data for append

eom

go to the physical end of medium

fill

fill tape, write onto second volume

unfill

read filled tape

fsf

forward space a file

fsr

forward space a record

help

print this reference

label

write a Bacula label to the tape

load

load a tape

quit

quit btape

rawfill

use write() to fill tape

readlabel

read and print the Bacula tape label

rectest

test record handling functions

rewind

rewind the tape

scan

read() tape block by block to EOT and report

scanblocks

Bacula read block by block to EOT and report

status

print tape status

test

General test Bacula tape functions

weof

write an EOF on the tape

wr

write a single Bacula block

rr

read a single record

rb

read a single bacula block

qfill

quick fill command

## SEE ALSO
bscan(1), bextract(1).

## AUTHOR
This manual page was written by Jose Luis Tallon <jltallon@adv-solutions.net>.

## COPYRIGHT
This man page document is released under the BSD 2-Clause license.


bbconsjson

title: bbconsjson(8)

summary: Bacula's JSON configuration export tool

text:
# bbconsjson(8)

## NAME

bbconsjson - Bacula's JSON configuration export tool

## SYNOPSIS
bbconsjson [options]

## DESCRIPTION
This manual page documents briefly the bbconsjson command.

This is a simple program that will allow you to dump the Bacula Console configuration in JSON format.

## OPTIONS
A summary of options is included below.

-?

Show version and usage of program.

-d nn

Set debug level to nn.

-dt

Print timestamp in debug output

-r <res>

Get resource type

-n <name>

Get resource name

-l <dirs>

Get only directives matching dirs (use with -r)

-D

Get only data

-R

Do not apply JobDefs to Job

-c <file>

Set configuration file to file

-d <nn>

Set debug level to <nn>

-dt

Print timestamp in debug output

-t

Read configuration and exit

-s

Output in show text format

-v

Verbose user messages

## AUTHOR
This manual page was written by Eric Bollengier <eric@baculasystems.com>. This man page document is released under the BSD 2-Clause license.


bdirjson

title: bdirjson(8)

summary: Bacula's JSON configuration export tool

text:
# bdirjson(8)

## NAME

bdirjson - Bacula's JSON configuration export tool

## SYNOPSIS
bdirjson [options]

## DESCRIPTION
This manual page documents briefly the bdirjson command.

This is a simple program that will allow you to dump the Bacula Director configuration in JSON format.

## OPTIONS
A summary of options is included below.

-?

Show version and usage of program.

-d nn

Set debug level to nn.

-dt

Print timestamp in debug output

-r <res>

Get resource type

-n <name>

Get resource name

-l <dirs>

Get only directives matching dirs (use with -r)

-D

Get only data

-R

Do not apply JobDefs to Job

-c <file>

Set configuration file to file

-d <nn>

Set debug level to <nn>

-dt

Print timestamp in debug output

-t

Read configuration and exit

-s

Output in show text format

-v

Verbose user messages

## AUTHOR
This manual page was written by Eric Bollengier <eric@baculasystems.com>. This man page document is released under the BSD 2-Clause license.


bfdjson

title: bfdjson(8)

summary: Bacula's JSON configuration export tool

text:
# bfdjson(8)

## NAME

bfdjson - Bacula's JSON configuration export tool

## SYNOPSIS
bfdjson [options]

## DESCRIPTION
This manual page documents briefly the bfdjson command.

This is a simple program that will allow you to dump the Bacula File Daemon configuration in JSON format.

## OPTIONS
A summary of options is included below.

-?

Show version and usage of program.

-d nn

Set debug level to nn.

-dt

Print timestamp in debug output

-r <res>

Get resource type

-n <name>

Get resource name

-l <dirs>

Get only directives matching dirs (use with -r)

-D

Get only data

-R

Do not apply JobDefs to Job

-c <file>

Set configuration file to file

-d <nn>

Set debug level to <nn>

-dt

Print timestamp in debug output

-t

Read configuration and exit

-s

Output in show text format

-v

Verbose user messages

## AUTHOR
This manual page was written by Eric Bollengier <eric@baculasystems.com>. This man page document is released under the BSD 2-Clause license.


bsdjson

title: bsdjson(8)

summary: Bacula's JSON configuration export tool

text:
# bsdjson(8)

## NAME

bsdjson - Bacula's JSON configuration export tool

## SYNOPSIS
bsdjson [options]

## DESCRIPTION
This manual page documents briefly the bsdjson command.

This is a simple program that will allow you to dump the Bacula Storage Daemon configuration in JSON format.

## OPTIONS
A summary of options is included below.

-?

Show version and usage of program.

-d nn

Set debug level to nn.

-dt

Print timestamp in debug output

-r <res>

Get resource type

-n <name>

Get resource name

-l <dirs>

Get only directives matching dirs (use with -r)

-D

Get only data

-R

Do not apply JobDefs to Job

-c <file>

Set configuration file to file

-d <nn>

Set debug level to <nn>

-dt

Print timestamp in debug output

-t

Read configuration and exit

-s

Output in show text format

-v

Verbose user messages

## AUTHOR
This manual page was written by Eric Bollengier <eric@baculasystems.com>. This man page document is released under the BSD 2-Clause license.


bcache-status

package: bcache-status

title: bcache-status(8)

summary: Display useful bcache statistics

text:
# bcache-status(8)

## NAME
bcache-status - Display useful bcache statistics

## SYNOPSIS
bcache-status [ --help ] [ -f ] [ -h ] [ -d ] [ -t ] [ -a ] [ -r ] [ -s ] [ -g ]

## DESCRIPTION
This command displays useful bcache statistics in a convenient way.

## OPTIONS
--help

Print help message and exit.

-f, --five-minute

Print the last five minutes of stats.

-h, --hour

Print the last hour of stats.

-d, --day

Print the last day of stats.

-t, --total

Print total stats.

-a, --all

Print all stats.

-r, --reset-stats

Reset stats after printing them.

-s, --sub-status

Print subdevice status.

-g, --gc

Invoke GC before printing status (root only).


bcache-super-show

package: bcache-tools

title: bcache-super-show(8)

summary: Print the bcache superblock

text:
# bcache-super-show(8)

## NAME
bcache-super-show - Print the bcache superblock

## SYNOPSIS
bcache-super-show [ -f] device

## OPTIONS
-f

Keep going if the superblock crc is invalid


make-bcache

title: make-bcache(8)

summary: create a cache device

text:
# make-bcache(8)

## NAME
make-bcache - create a cache device

## SYNOPSIS
make-bcache [ -U UUID ] [ -b bucket-size ] device

## OPTIONS
-C

Create a cache

-B

Create a backing device (kernel functionality not yet implemented)

-U UUID

Create a cache device with the specified UUID

-b bucket-size

Specifies the bucket size. Allocation is done in terms of buckets, and cache hits are counted per bucket; thus a smaller bucket size will give better cache utilization, but poorer write performance. The bucket size is intended to be equal to the size of your SSD's erase blocks, which seems to be 128k-512k for most SSDs. Must be a power of two; accepts human readable units. Defaults to 128k.


probe-bcache

title: probe-bcache(8)

summary: probe a bcache device

text:
# probe-bcache(8)

## NAME
probe-bcache - probe a bcache device

## SYNOPSIS
probe-bcache [ -o udev ] device

## OPTIONS
-o

return UUID in udev style for invocation by udev rule as IMPORT{program}

## USAGE
Return UUID if device identified as bcache-formatted.

Only necessary until support for the bcache superblock is included in blkid; in the meantime, provides just enough functionality for a udev script to create the /dev/disk/by-uuid symlink.


bcachefs

package: bcachefs-tools

title: bcachefs(8)

summary: manage bcachefs filesystems/devices

text:
# bcachefs(8)

## NAME
bcachefs — manage bcachefs filesystems/devices

## SYNOPSIS
bcachefs

command [options] [arguments]

## DESCRIPTION
The bcachefs utility supports the following subcommands, which are documented in detail below:

### Superblock commands
format

Format one or a list of devices with bcachefs data structures.

show-super

Dump superblock information to stdout.

set-option

Set a filesystem option

### Mount commands
mount

Mount a filesystem.

### Repair commands
fsck

Check an existing filesystem for errors.

### Commands for managing a running filesystem
fs usage

Show disk usage

### Commands for managing devices within a running filesystem
device add

Add a new device to an existing filesystem

device remove

Remove a device from an existing filesystem

device online

Re-add an existing member to a filesystem

device offline

Take a device offline, without removing it

device evacuate

Migrate data off of a specific device

device set-state

Mark a device as failed

device resize

Resize filesystem on a device

device resize-journal

Resize journal on a device

### Commands for managing subvolumes and snapshots
subvolume create

Create a new subvolume

subvolume delete

Delete an existing subvolume

subvolume snapshot

Create a snapshot

### Commands for managing filesystem data
data rereplicate

Rereplicate degraded data

data job

Kick off low level data jobs

### Commands for encryption
unlock

Unlock an encrypted filesystem prior to running/mounting

set-passphrase

Change passphrase on an existing (unmounted) filesystem

remove-passphrase

Remove passphrase on an existing (unmounted) filesystem

### Commands for migration
migrate

Migrate an existing filesystem to bcachefs, in place

migrate-superblock

Add default superblock, after bcachefs migrate

### Commands for operating on files in a bcachefs filesystem
setattr

Set various per file attributes

### Commands for debugging
dump

Dump filesystem metadata to a qcow2 image

list

List filesystem metadata in textual form

list_journal

List contents of journal

### FUSE commands
fusemount Mount a filesystem via FUSE

### Miscellaneous commands
version

Display the version of the invoked bcachefs tool

completions

Generate shell completions

## Superblock commands
bcachefs format [options] devices ...

Format one or a list of devices with bcachefs data structures. You need to do this before you create a volume. Device specific options must come before corresponding devices, e.g.

bcachefs format --label=ssd /dev/sda --label=hdd /dev/sdb

--block_size=size

block size, in bytes (e.g. 4k)

--btree_node_size=size

Btree node size, default 256k

--errors=(continue | ro | panic)

Action to take on filesystem error

--data_replicas=number

Number of data replicas

--metadata_replicas=number

Number of metadata replicas

--data_replicas_required=number

--metadata_replicas_required=number

--encoded_extent_max=size

Maximum size of checksummed/compressed extents

--metadata_checksum=(none | crc32c | crc64 | xxhash)

Set metadata checksum type (default: crc32c).

--data_checksum=(none | crc32c | crc64 | xxhash)

Set data checksum type (default: crc32c).

--compression=(none | lz4 | gzip | zstd)

Set compression type (default: none).

--background_compression=(none | lz4 | gzip | zstd)

--str_hash=(crc32c | crc64 | siphash)

Hash function for directory entries and xattrs

--metadata_target=target

Device or label for metadata writes

--foreground_target=target

Device or label for foreground writes

--background_target=target

Device or label to move data to in the background

--promote_target=target

Device or label to promote data to on read

--erasure_code

Enable erasure coding (DO NOT USE YET)

--inodes_32bit

Constrain inode numbers to 32 bits

--shared_inode_numbers

Shared new inode numbers by CPU id

--inodes_use_key_cache

Use the btree key cache for the inodes btree

--gc_reserve_percent=percentage

Percentage of disk space to reserve for copygc

--gc_reserve_bytes=percentage

Amount of disk space to reserve for copygc This takes precedence over gc_reserve_percent if set

--root_reserve_percent=percentage

Percentage of disk space to reserve for superuser

--wide_macs

Store full 128bits of cryptographic MACS, instead of 80

--acl

Enable POSIX acls

--usrquota

Enable user quotas

--grpquota

Enable group quotas

-prjquota

Enable project quotas

--journal_transaction_names

Log transaction function names in journal

--nocow

Nocow mode: Writes will be done in place when possible. Snapshots and reflink will still caused writes to be COW.

This flag implicitly disables data checksumming, compression and encryption.

--replicas=number

Sets both data and metadata replicas

--encrypted

Enable whole filesystem encryption (chacha20/poly1305); passphrase will be prompted for.

--no_passphrase

Don't encrypt master encryption key

-L, --fs_label=label

Create the filesystem with the specified label

-U, --uuid=uuid

Create the filesystem with the specified uuid

--superblock_size=size

Device specific options:

--discard

Enable discard/TRIM support

--fs_size=size

Create the filesystem using size bytes on the subsequent device.

--bucket=size

Specifies the bucket size; must be greater than the btree node size

--durability=n

Data written to this device will be considered to have already been replicated n times

-l, --label

Disk label

-f, --force

Force the filesystem to be created, even if the device already contains a filesystem.

-q, --quiet

Only print errors

-v, --verbose

Verbose filesystem initialization

bcachefs show-super [options] device

Dump superblock information to stdout. -f, --fields=fields

List of sections to print

-l, --layout

Print superblock layout

bcachefs set-option [options] device

--errors=(continue | ro | panic)

Action to take on filesystem error

--metadata_replicas=number

Number of metadata replicas

--data_replicas=number

Number of data replicas

--metadata_replicas_required=number

--data_replicas_required=number

--metadata_checksum=(none | crc32c | crc64 | xxhash)

Set metadata checksum type (default: crc32c).

--data_checksum=(none | crc32c | crc64 | xxhash)

Set data checksum type (default: crc32c).

--compression=(none | lz4 | gzip | zstd)

Set compression type (default: none).

--background_compression=(none | lz4 | gzip | zstd)

--str_hash=(crc32c | crc64 | siphash)

Hash function for directory entries and xattrs

--metadata_target=target

Device or label for metadata writes

--foreground_target=target

Device or label for foreground writes

--background_target=target

Device or label to move data to in the background

--promote_target=target

Device or label to promote data to on read

--erasure_code

Enable erasure coding (DO NOT USE YET)

--inodes_32bit

Constrain inode numbers to 32 bits

--shared_inode_numbers

Shared new inode numbers by CPU id

--inodes_use_key_cache

Use the btree key cache for the inodes btree

--gc_reserve_percent=percentage

Percentage of disk space to reserve for copygc

--gc_reserve_bytes=percentage

Amount of disk space to reserve for copygc This takes precedence over gc_reserve_percent if set

--root_reserve_percent=percentage

Percentage of disk space to reserve for superuser

--wide_macs

Store full 128bits of cryptographic MACS, instead of 80

--acl

Enable POSIX acls

--usrquota

Enable user quotas

--grpquota

Enable group quotas

--prjquota

Enable project quotas

--degraded

Allow mounting in degraded mode

--very_degraded

Allow mounting in when data will be missing

--discard

Enable discard/TRIM support

--verbose

Extra debugging information during mount/recovery

--journal_flush_delay=ms

Delay in milliseconds before automatic journal commits

--journal_flush_disabled

Disable journal flush on sync/fsync If enabled, writes can be lost, but only since the last journal write (default 1 second)

--journal_reclaim_delay=ms

Delay in milliseconds before automatic journal reclaim

--move_bytes_in_flight=bytes

Maximum Amount of IO to keep in flight by the move path

--move_ios_in_flight=number

Maximum number of IOs to keep in flight by the move path

--fsck

Run fsck on mount

--fix_errors=error

Fix errors during fsck without asking

--ratelimit_errors

Ratelimit error messages during fsck

--nochanges

Super read only mode - no writes at all will be issued, even if we have to replay the journal

--norecovery

Don't replay the journal

--journal_transaction_names

Log transaction function names in journal

--noexcl

Don't open device in exclusive mode

--direct_io

Use O_DIRECT (userspace only)

--sb=offset

Sector offset of superblock

--reconstruct_alloc

Reconstruct alloc btree

--version_upgrade=(compatible | incompatible | none)

Set superblock to latest version, allowing any new features to be used

--nocow

Nocow mode: Writes will be done in place when possible. Snapshots and reflink will still caused writes to be COW.

This flag implicitly disables data checksumming, compression and encryption.

--nocow_enabled

Enable nocow mode: enables runtime locking in data move path needed if nocow will ever be in use

--no_data_io

Skip submit_bio() for data reads and writes, for performance testing purposes

## Mount commands
bcachefs mount [options] device mountpoint

Mount a filesystem. The device can be a device, a colon-separated list of devices, or UUID=<UUID>. The mountpoint is the path where the filesystem should be mounted. If not set, then the filesystem won't actually be mounted but all steps preceding mounting the filesystem (e.g. asking for passphrase) will still be performed. -o options

Mount options provided as a comma-separated list. See user guide for complete list. degraded

Allow mounting with data degraded

verbose

Extra debugging info during mount/recovery

fsck

Run fsck during mount

fix_errors

Fix errors without asking during fsck

read_only

Mount in read only mode

version_upgrade

-k, --key-location=(fail | wait | ask)

Where the password would be loaded from. (default: ask). fail

don't ask for password, fail if filesystem is encrypted.

wait

wait for password to become available before mounting.

ask

prompt the user for password.

-c, --colorize=(true | false)

Force color on/off. Default: auto-detect TTY

-v

Be verbose. Can be specified more than once.

## Repair commands
bcachefs fsck [options] devices ...

Check an existing filesystem for errors. -p

Automatic repair (no questions)

-n

Don't repair, only check for errors

-y

Assume "yes" to all questions

-f

Force checking even if filesystem is marked clean

-r, --ratelimit_errors

Don't display more than 10 errors of a given type

-R, --reconstruct_alloc

Reconstruct the alloc btree

-v

Be verbose

## Commands for managing a running filesystem
bcachefs fs usage [options] [filesystem]

Show disk usage. -h, --human-readable

Print human readable sizes.

## Commands for managing devices within a running filesystem
bcachefs device add [options] device

Add a device to an existing filesystem. --fs_size=size

Size of filesystem on device

--bucket=size

Set bucket size

--discard

Enable discards

-l, --label=label

Disk label

-f, --force

Use device even if it appears to already be formatted

bcachefs device remove [options] device

Remove a device from a filesystem -f, --force

Force removal, even if some data couldn't be migrated

-F, --force-metadata

Force removal, even if some metadata couldn't be migrated

bcachefs device online device

Re-add a device to a running filesystem

bcachefs device offline device

Take a device offline, without removing it -f, --force

Force, if data redundancy will be degraded

bcachefs device evacuate device

Move data off of a given device

bcachefs device set-state [options] new-state device

new-state=(rw | ro | failed | spare)

-f, --force

Force, if data redundancy will be degraded

--force-if-data-lost

Force, if data will be lost

-o, --offline

Set state of an offline device

bcachefs device resize device [size]

Resize filesystem on a device

bcachefs device resize-journal device [size]

Resize journal on a device

## Commands for managing subvolumes and snapshots
subvolume create [options] path

Create a new subvolume

subvolume delete [options] path

Delete an existing subvolume

subvolume delete [options] source dest

Create a snapshot of source at dest. If specified, source must be a subvolume; if not specified the snapshot will be of the subvolume containing dest. -r

Make snapshot read-only

## Commands for managing filesystem data
bcachefs data rereplicate filesystem

Walks existing data in a filesystem, writing additional copies of any degraded data.

bcachefs data job job filesystem

Kick off a data job and report progress job is one of ( scrub | rereplicate | migrate | rewrite_old_nodes )

-b btree

Btree to operate on

-s inode:offset

Start position

-e inode:offset

End position

## Commands for encryption
bcachefs unlock device

Unlock an encrypted filesystem prior to running/mounting. -c

Check if a device is encrypted

-k=(session | user | user_session)

Keyring to add to (default: user)

bcachefs set-passphrase devices ...

Change passphrase on an existing (unmounted) filesystem.

bcachefs remove-passphrase devices ...

Remove passphrase on an existing (unmounted) filesystem.

## Commands for migration
bcachefs migrate [options] device

Migrate an existing filesystem to bcachefs -f fs

Root of filesystem to migrate

--encrypted

Enable whole filesystem encryption (chacha20/poly1305)

--no_passphrase

Don't encrypt master encryption key

-F

Force, even if metadata file already exists

bcachefs migrate-superblock [options] device

Create default superblock after migrating -d device

Device to create superblock for

-o offset

Offset of existing superblock

## Commands for operating on files in a bcachefs filesystem
bcachefs setattr [options] devices ...

--data_replicas=number

Number of data replicas

--data_checksum=(none | crc32c | crc64 | xxhash)

Set data checksum type (default: crc32c).

--compression=(none | lz4 | gzip | zstd)

Set compression type (default: none).

--background_compression=(none | lz4 | gzip | zstd)

--metadata_target=target

Device or label for metadata writes

--foreground_target=target

Device or label for foreground writes

--background_target=target

Device or label to move data to in the background

--promote_target=target

Device or label to promote data to on read

--erasure_code

Enable erasure coding (DO NOT USE YET)

--project

--nocow

Nocow mode: Writes will be done in place when possible.

## Commands for debugging
These commands work on offline, unmounted filesystems.

bcachefs dump [options] device

Dump filesystem metadata -o output

Required flag: Output qcow2 image(s)

-f, --force

Force; overwrite when needed

--nojournal

Don't dump entire journal, just dirty entries

bcachefs list [options] devices ...

List filesystem metadata to stdout -b (extents | inodes | dirents | xattrs)

Btree to list from. (default: extents)

-l, --level

Btree depth to descend to. ( 0 == leaves; default: 0)

-s inode:offset

Start position to list from

-e inode:offset

End position

-m, --mode (keys | formats | nodes | nodes-ondisk)

(default: keys)

-f

Check (fsck) the filesystem first

-c, --colorize=(true | false)

Force color on/off. Default: auto-detect TTY

-v

Verbose mode

bcachefs list_journal [options] devices ...

-a

Read entire journal, not just dirty entries

-n, --nr-entries=nr

Number of journal entries to print, starting from the most recent

-t, --transaction-filter=bbpos

Filter transactions not updating bbpos

-k, --key-filter=btree

Filter keys not updating btree

-v, --verbose

Verbose mode

## FUSE commands
bcachefs fusemount

Mount a filesystem via FUSE

## Miscellaneous commands
bcachefs completions shell

Generate shell completions

bcachefs version

Display the version of the invoked bcachefs tool

## EXIT STATUS
The bcachefs utility exits 0 on success, and >0 if an error occurs.


bcc-argdist

package: bcc-tools

title: bcc-argdist(8)

text:
# bcc-argdist(8)

## NAME
argdist - Trace a function and display a histogram or frequency count of its parameter values. Uses Linux eBPF/bcc.

## SYNOPSIS
argdist [-h] [-p PID] [-z STRING_SIZE] [-i INTERVAL] [-d DURATION] [-n COUNT] [-v] [-T TOP] [-H specifier] [-C specifier] [-I header] [-t TID]

## DESCRIPTION
argdist attaches to function entry and exit points, collects specified parameter values, and stores them in a histogram or a frequency collection that counts the number of times a parameter value occurred. It can also filter parameter values and instrument multiple entry points at once.

Since this uses BPF, only the root user can use this tool.

## REQUIREMENTS
CONFIG_BPF and bcc.

## OPTIONS
-h

Print usage message.

-p PID

Trace only functions in the process PID.

-t TID

Trace only functions in the thread TID.

-z STRING_SIZE

When collecting string arguments (of type char*), collect up to STRING_SIZE characters. Longer strings will be truncated.

-i INTERVAL

Print the collected data every INTERVAL seconds. The default is 1 second.

-d DURATION

Total duration of trace in seconds.

-n NUMBER

Print the collected data COUNT times and then exit.

-v

Display the generated BPF program, for debugging purposes.

-T TOP

When collecting frequency counts, display only the top TOP entries.

-H specifiers, -C specifiers

One or more probe specifications that instruct argdist which functions to probe, which parameters to collect, how to aggregate them, and whether to perform any filtering. See SPECIFIER SYNTAX below.

-I header

One or more header files that should be included in the BPF program. This enables the use of structure definitions, enumerations, and constants that are available in these headers. You should provide the same path you would include in the BPF program, e.g. 'linux/blkdev.h' or 'linux/time.h'. Note: in many cases, argdist will deduce the necessary header files automatically.

## SPECIFIER SYNTAX
The general specifier syntax is as follows:

{p,r,t,u}:{[library],category}:function(signature):type[,type...]:expr[,expr...][:filter]][#label]

{p,r,t,u}

Probe type - "p" for function entry, "r" for function return, "t" for kernel tracepoint, "u" for USDT probe; -H for histogram collection, -C for frequency count. Indicates where to place the probe and whether the probe should collect frequency count information, or aggregate the collected values into a histogram. Counting probes will collect the number of times every parameter value was observed, whereas histogram probes will collect the parameter values into a histogram. Only integral types can be used with histogram probes; there is no such limitation for counting probes.

[library]

Library containing the probe. Specify the full path to the .so or executable file where the function to probe resides. Alternatively, you can specify just the lib name: for example, "c" refers to libc. If no library name is specified, the kernel is assumed.

category

The category of the kernel tracepoint. For example: net, sched, block.

function(signature)

The function to probe, and its signature. The function name must match exactly for the probe to be placed. The signature, on the other hand, is only required if you plan to collect parameter values based on that signature. For example, if you only want to collect the first parameter, you don't have to specify the rest of the parameters in the signature. When capturing kernel tracepoints, this should be the name of the event, e.g. net_dev_start_xmit. The signature for kernel tracepoints should be empty. When capturing USDT probes, this should be the name of the probe, e.g. reloc_complete. The signature for USDT probes should be empty.

[type[,type...]]

The type(s) of the expression(s) to capture. This is the type of the keys in the histogram or raw event collection that are collected by the probes.

[expr[,expr...]]

The expression(s) to capture. These are the values that are assigned to the histogram or raw event collection. You may use the parameters directly, or valid C expressions that involve the parameters, such as "size % 10". Tracepoints may access a special structure called "args" that is formatted according to the tracepoint format (which you can obtain using tplist). For example, the block:block_rq_complete tracepoint can access args->nr_sector. USDT probes may access the arguments defined by the tracing program in the special arg1, arg2, ... variables. To obtain their types, use the tplist tool. Return probes can use the argument values received by the function when it was entered, through the $entry(paramname) special variable. Return probes can also access the function's return value in $retval, and the function's execution time in nanoseconds in $latency. Note that adding the $latency or $entry(paramname) variables to the expression will introduce an additional probe at the function's entry to collect this data, and therefore introduce additional overhead.

[filter]

The filter applied to the captured data. Only parameter values that pass the filter will be collected. This is any valid C expression that refers to the parameter values, such as "fd == 1 && length > 16". The $entry, $retval, and $latency variables can be used here as well, in return probes. The filter expression may also use the STRCMP pseudo-function to compare a predefined string to a string argument. For example: STRCMP("test.txt", file). The order of arguments is important: the first argument MUST be a quoted literal string, and the second argument can be a runtime string.

[label]

The label that will be displayed when printing the probed values. By default, this is the probe specifier.

## EXAMPLES
Print a histogram of allocation sizes passed to kmalloc:

\# argdist -H 'p::__kmalloc(u64 size):u64:size'

Print a count of how many times process 1005 called malloc with an allocation size of 16 bytes:

\# argdist -p 1005 -C 'p:c:malloc(size_t size):size_t:size:size==16'

Snoop on all strings returned by gets():

\# argdist -C 'r:c:gets():char*:$retval'

Print a histogram of read sizes that were longer than 1ms:

\# argdist -H 'r::__vfs_read(void *file, void *buf, size_t count):size_t:$entry(count):$latency > 1000000'

Print frequency counts of how many times writes were issued to a particular file descriptor number, in process 1005:

\# argdist -p 1005 -C 'p:c:write(int fd):int:fd'

Print a histogram of error codes returned by read() in process 1005:

\# argdist -p 1005 -H 'r:c:read()'

Print a histogram of buffer sizes passed to write() across all processes, where the file descriptor was 1 (STDOUT):

\# argdist -H 'p:c:write(int fd, const void *buf, size_t count):size_t:count:fd==1'

Count fork() calls in libc across all processes, grouped by pid:

\# argdist -C 'p:c:fork():int:$PID;fork per process'

Print histogram of number of sectors in completing block I/O requests:

\# argdist -H 't:block:block_rq_complete():u32:nr_sector'

Aggregate interrupts by interrupt request (IRQ):

\# argdist -C 't:irq:irq_handler_entry():int:irq'

Print the functions used as thread entry points and how common they are:

\# argdist -C 'u:pthread:pthread_start():u64:arg2' -p 1337

Print histograms of sleep() and nanosleep() parameter values:

\# argdist -H 'p:c:sleep(u32 seconds):u32:seconds' -H 'p:c:nanosleep(struct timespec *req):long:req->tv_nsec'

Spy on writes to STDOUT performed by process 2780, up to a string size of 120 characters:

\# argdist -p 2780 -z 120 -C 'p:c:write(int fd, char* buf, size_t len):char*:buf:fd==1'

Group files being read from and the read sizes from __vfs_read:

\# argdist -C 'p::__vfs_read(struct file *file, void *buf, size_t count):char*,size_t:file->f_path.dentry->d_iname,count:file->f_path.dentry->d_iname[0]!=0'

## SOURCE
This is from bcc.

https://github.com/iovisor/bcc

Also look in the bcc distribution for a companion _examples.txt file containing example usage, output, and commentary for this tool.

## OS
Linux

## STABILITY
Unstable - in development.

## AUTHOR
Sasha Goldshtein


bcc-bashreadline

title: bcc-bashreadline(8)

text:
# bcc-bashreadline(8)

## NAME
bashreadline - Print entered bash commands system wide. Uses Linux eBPF/bcc.

## SYNOPSIS
bashreadline [-h] [-s SHARED]

## DESCRIPTION
bashreadline traces the return of the readline() function using uprobes, to show the bash commands that were entered interactively, system wide. The entered command may fail: this is just showing what was entered.

This program is also a basic example of eBPF/bcc and uprobes.

This makes use of a Linux 4.4 feature (bpf_perf_event_output()); for kernels older than 4.4, see the version under tools/old, which uses an older mechanism

Since this uses BPF, only the root user can use this tool.

## REQUIREMENTS
CONFIG_BPF and bcc.

## OPTIONS
-h

Print usage message.

-s

Specify the location of libreadline.so shared library when you failed to run the script directly with error: "Exception: could not determine address of symbol ´readline´". Default value is /lib/libreadline.so.

## EXAMPLES
Trace bash commands system wide:

\# bashreadline

## FIELDS
TIME

Time of the command (HH:MM:SS).

PID

Process ID of the bash shell.

COMMAND

Entered command.

## OVERHEAD
As the rate of interactive bash commands is expected to be very low (<<100/s), the overhead of this program is expected to be negligible.

## SOURCE
This is from bcc.

https://github.com/iovisor/bcc

Also look in the bcc distribution for a companion _examples.txt file containing example usage, output, and commentary for this tool.

## OS
Linux

## STABILITY
Unstable - in development.

## AUTHOR
Brendan Gregg

## SEE ALSO
opensnoop(8)


bcc-bindsnoop

title: bcc-bindsnoop(8)

summary: Trace bind() system calls.

text:
# bcc-bindsnoop(8)

## NAME
bindsnoop - Trace bind() system calls.

## SYNOPSIS
bindsnoop [-h] [-w] [-t] [-p PID] [-P PORT] [-E] [-U] [-u UID] [--count] [--cgroupmap MAP] [--mntnsmap MNTNSMAP]

## DESCRIPTION
bindsnoop reports socket options set before the bind call that would impact this system call behavior.

## REQUIREMENTS
CONFIG_BPF and bcc.

## OPTIONS:
Show help message and exit:

-h, --help

Include timestamp on output:

-t, --timestamp

Wider columns (fit IPv6):

-w, --wide

Trace this PID only:

-p PID, --pid PID

Comma-separated list of ports to trace:

-P PORT, --port PORT

Trace cgroups in this BPF map:

--cgroupmap MAP

Trace mount namespaces in this BPF map:

--mntnsmap MNTNSMAP

Include errors in the output:

-E, --errors

Include UID on output:

-U, --print-uid

Trace this UID only:

-u UID, --uid UID

Count binds per src ip and port:

--count

## EXAMPLES:
Trace all IPv4 and IPv6 bind()s

bindsnoop

Include timestamps

bindsnoop -t

Trace PID 181

bindsnoop -p 181

Trace port 80

bindsnoop -P 80

Trace port 80 and 81

bindsnoop -P 80,81

Include UID

bindsnoop -U

Trace UID 1000

bindsnoop -u 1000

Report bind errors

bindsnoop -E

Count bind per src ip

bindsnoop --count

Trace IPv4 and IPv6 bind system calls and report socket options that would impact bind call behavior:

SOL_IP IP_FREEBIND F....

SOL_IP IP_TRANSPARENT .T...

SOL_IP IP_BIND_ADDRESS_NO_PORT ..N..

SOL_SOCKET SO_REUSEADDR ...R.

SOL_SOCKET SO_REUSEPORT ....r

SO_BINDTODEVICE interface is reported as "IF" index

## SOURCE
This is from bcc.

https://github.com/iovisor/bcc

Also look in the bcc distribution for a companion _examples.txt file containing example usage, output, and commentary for this tool.

## OS
Linux

## STABILITY
Unstable - in development.

## AUTHOR
Pavel Dubovitsky

## SEE ALSO
tcpaccept(8)


bcc-biolatency

title: bcc-biolatency(8)

text:
# bcc-biolatency(8)

## NAME
biolatency - Summarize block device I/O latency as a histogram.

## SYNOPSIS
biolatency [-h] [-F] [-T] [-Q] [-m] [-D] [-F] [-e] [-j] [-d DISK] [interval [count]]

## DESCRIPTION
biolatency traces block device I/O (disk I/O), and records the distribution of I/O latency (time). This is printed as a histogram either on Ctrl-C, or after a given interval in seconds.

The latency of disk I/O operations is measured from when requests are issued to the device up to completion. A -Q option can be used to include time queued in the kernel.

This tool uses in-kernel eBPF maps for storing timestamps and the histogram, for efficiency.

This works by tracing various kernel blk_*() functions using dynamic tracing, and will need updating to match any changes to these functions.

Since this uses BPF, only the root user can use this tool.

## REQUIREMENTS
CONFIG_BPF and bcc.

## OPTIONS
-h Print usage message.

-T

Include timestamps on output.

-m

Output histogram in milliseconds.

-D

Print a histogram per disk device.

-F

Print a histogram per set of I/O flags.

-j

Print a histogram dictionary

-e

Show extension summary(total, average)

-d DISK

Trace this disk only

interval

Output interval, in seconds.

count

Number of outputs.

## EXAMPLES
Summarize block device I/O latency as a histogram:

\# biolatency

Print 1 second summaries, 10 times:

\# biolatency 1 10

Print 1 second summaries, using milliseconds as units for the histogram, and

include timestamps on output: # biolatency -mT 1

Include OS queued time in I/O time:

\# biolatency -Q

Show a latency histogram for each disk device separately:

\# biolatency -D

Show a latency histogram in a dictionary format:

\# biolatency -j

Also show extension summary(total, average):

\# biolatency -e

## FIELDS
usecs

Microsecond range

msecs

Millisecond range

count

How many I/O fell into this range

distribution

An ASCII bar chart to visualize the distribution (count column)

## OVERHEAD
This traces kernel functions and maintains in-kernel timestamps and a histogram, which are asynchronously copied to user-space. This method is very efficient, and the overhead for most storage I/O rates (< 10k IOPS) should be negligible. If you have a higher IOPS storage environment, test and quantify the overhead before use.

## SOURCE
This is from bcc.

https://github.com/iovisor/bcc

Also look in the bcc distribution for a companion _examples.txt file containing example usage, output, and commentary for this tool.

## OS
Linux

## STABILITY
Unstable - in development.

## AUTHOR
Brendan Gregg, Rocky Xing

## SEE ALSO
biosnoop(8)


bcc-biolatpcts

title: bcc-biolatpcts(8)

text:
# bcc-biolatpcts(8)

## NAME
biolatpcts - Monitor IO latency distribution of a block device.

## SYNOPSIS
biolatpcts [-h] [-i INTERVAL] [-w which] [-p PCT,...] [-j] [-v] DEV

## DESCRIPTION
biolatpcts traces block device I/O (disk I/O) of the specified device, and calculates and prints the completion latency distribution percentiles per IO type periodically. Example:

\# biolatpcts /dev/nvme0n1

nvme0n1 p1 p5 p10 p16 p25 p50 p75 p84 p90 p95 p99 p100

read 95us 175us 305us 515us 895us 985us 995us 1.5ms 2.5ms 3.5ms 4.5ms 10ms

write 5us 5us 5us 15us 25us 135us 765us 855us 885us 895us 965us 1.5ms

discard 5us 5us 5us 5us 135us 145us 165us 205us 385us 875us 1.5ms 2.5ms

flush 5us 5us 5us 5us 5us 5us 5us 5us 5us 1.5ms 4.5ms 5.5ms

[...]

biolatpcts prints a number of pre-set latency percentiles in tabular form every three seconds. The interval can be changed with the -i option.

The latency is measured between issue to the device and completion. The starting point can be changed with the -w option.

Any number of percentiles can be specified using the -p option. The input percentile string is used verbatim in the output to ease machine consumption.

-j option enables json output. The result for each interval is printed on a single line.

This tool works by tracing blk_account_io_done() with kprobe and bucketing the completion latencies into percpu arrays. It may need updating to match the changes to the function.

Since this uses BPF, only the root user can use this tool.

## REQUIREMENTS
CONFIG_BPF, CONFIG_KPROBES and bcc.

## OPTIONS
-h Print usage message.

-i INTERVAL, --interval INTERVAL

Report interval. (default: 3)

-w {from-rq-alloc,after-rq-alloc,on-device}, --which {from-rq-alloc,after-rq-alloc,on-device}

Which latency to measure. (default: on-device)

-p PCT,..., --pcts PCT,...

Percentiles to calculate. (default: 1,5,10,16,25,50,75,84,90,95,99,100)

-j, --json

Output in json.

-v, --verbose

Enable debug output.

DEV

Target block device. /dev/DEVNAME, DEVNAME or MAJ:MIN.

## EXAMPLES
Print sda's I/O latency percentiles every second

\# biolatpcts -i 1 sda

Print nvme0n1's all-9 I/O latency percentiles in json every second

\# biolatpcts -p 99,99.9,99.99,99.999 -j -i 1 /dev/nvme0n1

## OVERHEAD
This traces kernel functions and maintains in-kernel per-cpu latency buckets, which are asynchronously copied to user-space. This method is very efficient, and the overhead for most storage I/O rates should be negligible. If you have an extremely high IOPS storage device, test and quantify the overhead before use.

## SOURCE
This is from bcc.

https://github.com/iovisor/bcc

Also look in the bcc distribution for a companion _examples.txt file containing example usage, output, and commentary for this tool.

## OS
Linux

## STABILITY
Unstable - in development.

## AUTHOR
Tejun Heo

## SEE ALSO
biolatency(8), biosnoop(8)


bcc-biopattern

title: bcc-biopattern(8)

text:
# bcc-biopattern(8)

## NAME
biopattern - Identify random/sequential disk access patterns.

## SYNOPSIS
biopattern [-h] [-d DISK] [interval] [count]

## DESCRIPTION
This traces block device I/O (disk I/O), and prints ratio of random/sequential I/O for each disk or the specified disk either on Ctrl-C, or after a given interval in seconds.

This works by tracing kernel tracepoint block:block_rq_complete.

Since this uses BPF, only the root user can use this tool.

## REQUIREMENTS
CONFIG_BPF and bcc.

## OPTIONS
-h

Show help message and exit.

-d

Trace this disk only.

interval

Print output every interval seconds, if any.

count

Number of interval summaries.

## EXAMPLES
Trace access patterns of all disks, and print a summary on Ctrl-C:

\# biopattern

Trace disk sdb only:

\# biopattern -d sdb

Print 1 second summaries, 10 times:

\# biopattern 1 10

## FIELDS
TIME

Time of the output, in HH:MM:SS format.

DISK

Disk device name.

%RND

Ratio of random I/O.

%SEQ

Ratio of sequential I/O.

COUNT

Number of I/O during the interval.

KBYTES

Total Kbytes for these I/O, during the interval.

## OVERHEAD
Since block device I/O usually has a relatively low frequency (< 10,000/s), the overhead for this tool is expected to be low or negligible. For high IOPS storage systems, test and quantify before use.

## SOURCE
This is from bcc.

https://github.com/iovisor/bcc

Also look in the bcc distribution for a companion _examples.txt file containing example usage, output, and commentary for this tool.

## OS
Linux

## STABILITY
Unstable - in development.

## AUTHOR
Rocky Xing

## SEE ALSO
biosnoop(8), biolatency(8), iostat(1)


bcc-biosnoop

title: bcc-biosnoop(8)

text:
# bcc-biosnoop(8)

## NAME
biosnoop - Trace block device I/O and print details incl. issuing PID.

## SYNOPSIS
biosnoop [-h] [-Q] [-d DISK] [-P]

## DESCRIPTION
This tools traces block device I/O (disk I/O), and prints a one-line summary for each I/O showing various details. These include the latency from the time of issue to the device to its completion, and the PID and process name from when the I/O was first created (which usually identifies the responsible process).

This uses in-kernel eBPF maps to cache process details (PID and comm) by I/O request, as well as a starting timestamp for calculating I/O latency.

This works by tracing various kernel blk_*() functions using dynamic tracing, and will need updating to match any changes to these functions.

This makes use of a Linux 4.4 feature (bpf_perf_event_output()); for kernels older than 4.4, see the version under tools/old, which uses an older mechanism

Since this uses BPF, only the root user can use this tool.

## REQUIREMENTS
CONFIG_BPF and bcc.

## OPTIONS
-h

Print usage message.

-Q

Include a column showing the time spent queued in the OS.

-d DISK

Trace this disk only.

-P

Display block I/O pattern (sequential or random).

## EXAMPLES
Trace all block device I/O and print a summary line per I/O:

\# biosnoop

## FIELDS
TIME(s)

Time of the I/O completion, in seconds since the first I/O was seen.

COMM

Cached process name, if present. This usually (but isn't guaranteed) to identify the responsible process for the I/O.

PID

Cached process ID, if present. This usually (but isn't guaranteed) to identify the responsible process for the I/O.

DISK

Disk device name.

T

Type of I/O: R = read, W = write. This is a simplification.

SECTOR

Device sector for the I/O.

BYTES

Size of the I/O, in bytes.

QUE(ms)

Time the I/O was queued in the OS before being issued to the device, in milliseconds.

LAT(ms)

Time for the I/O (latency) from the issue to the device, to its completion, in milliseconds.

## OVERHEAD
Since block device I/O usually has a relatively low frequency (< 10,000/s), the overhead for this tool is expected to be negligible. For high IOPS storage systems, test and quantify before use.

## SOURCE
This is from bcc.

https://github.com/iovisor/bcc

Also look in the bcc distribution for a companion _examples.txt file containing example usage, output, and commentary for this tool.

## OS
Linux

## STABILITY
Unstable - in development.

## AUTHOR
Brendan Gregg, Rocky Xing

## SEE ALSO
disksnoop(8), iostat(1)


bcc-biotop

title: bcc-biotop(8)

summary: Block device (disk) I/O by process top.

text:
# bcc-biotop(8)

## NAME
biotop - Block device (disk) I/O by process top.

## SYNOPSIS
biotop [-h] [-C] [-r MAXROWS] [-p PID] [interval] [count]

## DESCRIPTION
This is top for disks.

This traces block device I/O (disk I/O), and prints a per-process summary every interval (by default, 1 second). The summary is sorted on the top disk consumers by throughput (Kbytes). The PID and process name shown are measured from when the I/O was first created, which usually identifies the responsible process.

For efficiency, this uses in-kernel eBPF maps to cache process details (PID and comm) by I/O request, as well as a starting timestamp for calculating I/O latency, and the final summary.

This works by tracing various kernel blk_*() functions using dynamic tracing, and will need updating to match any changes to these functions.

Since this uses BPF, only the root user can use this tool.

## REQUIREMENTS
CONFIG_BPF and bcc.

## OPTIONS
-C

Don't clear the screen.

-r MAXROWS

Maximum number of rows to print. Default is 20.

-p PID

Trace this PID only.

interval

Interval between updates, seconds.

count

Number of interval summaries.

## EXAMPLES
Summarize block device I/O by process, 1 second screen refresh:

\# biotop

Don't clear the screen:

\# biotop -C

5 second summaries, 10 times only:

\# biotop 5 10

## FIELDS
loadavg:

The contents of /proc/loadavg

PID

Cached process ID, if present. This usually (but isn't guaranteed) to identify the responsible process for the I/O.

COMM

Cached process name, if present. This usually (but isn't guaranteed) to identify the responsible process for the I/O.

D

Direction: R == read, W == write. This is a simplification.

MAJ

Major device number.

MIN

Minor device number.

DISK

Disk device name.

I/O

Number of I/O during the interval.

Kbytes

Total Kbytes for these I/O, during the interval.

AVGms

Average time for the I/O (latency) from the issue to the device, to its completion, in milliseconds.

## OVERHEAD
Since block device I/O usually has a relatively low frequency (< 10,000/s), the overhead for this tool is expected to be low or negligible. For high IOPS storage systems, test and quantify before use.

## SOURCE
This is from bcc.

https://github.com/iovisor/bcc

Also look in the bcc distribution for a companion _examples.txt file containing example usage, output, and commentary for this tool.

## OS
Linux

## STABILITY
Unstable - in development.

## AUTHOR
Brendan Gregg, Rocky Xing

## INSPIRATION
top(1) by William LeFebvre

## SEE ALSO
biosnoop(8), biolatency(8), iostat(1)


bcc-bitesize

title: bcc-bitesize(8)

summary: Summarize block device I/O size as a histogram \- Linux eBPF/bcc.

text:
# bcc-bitesize(8)

## NAME
bitesize - Summarize block device I/O size as a histogram - Linux eBPF/bcc.

## SYNOPSIS
bitesize

## DESCRIPTION
Show I/O distribution for requested block sizes, by process name.

This works by tracing block:block_rq_issue and prints a histogram of I/O size.

Since this uses BPF, only the root user can use this tool.

## REQUIREMENTS
CONFIG_BPF and bcc.

## EXAMPLES
Count I/O size per process until Ctrl-C is hit:

\# bitesize

## FIELDS
Kbtes

Size in kilobytes of range

count

How many I/O fell into this range

distribution

An ASCII bar chart to visualize the distribution (count column)

## OVERHEAD
This traces a block I/O tracepoint to update a histogram, which is asynchronously copied to user-space. This method is very efficient, and the overhead for most storage I/O rates (< 10k IOPS) should be negligible. If you have a higher IOPS storage environment, test and quantify the overhead before use.

## SOURCE
This is from bcc.

https://github.com/iovisor/bcc

Also look in the bcc distribution for a companion _examples.txt file containing example usage, output, and commentary for this tool.

## OS
Linux

## STABILITY
Unstable - in development.

## AUTHOR
Allan McAleavy

## SEE ALSO
https://github.com/brendangregg/systemtap-lwtools/blob/master/disk/bitesize-nd.stp


bcc-bpflist

title: bcc-bpflist(8)

text:
# bcc-bpflist(8)

## NAME
bpflist - Display processes currently using BPF programs and maps.

## SYNOPSIS
bpflist [-v]

## DESCRIPTION
This tool displays processes currently using BPF programs and maps, and optionally also kprobes and uprobes on the system. This is useful to understand which BPF programs are loaded on the system.

Currently, for lack of a better alternative, this tool pipes into 'ls' and parses its output to snoop for BPF file descriptors in all running processes. In the future, when BPF accounting is provided by the kernel, this tool should use these accounting features.

Only the root user can use this tool, because it accesses debugfs.

## REQUIREMENTS
bcc, debugfs

## OPTIONS
-h Print usage message.

-v

Count kprobes and uprobes as well as BPF programs. Repeating verbose mode twice also prints the kprobe and uprobe definitions in addition to counting them.

## EXAMPLES
Display processes currently using BPF programs:

\# bpflist

Also count kprobes and uprobes:

\# bpflist -v

## FIELDS
PID

Process ID.

COMM

Process comm.

TYPE

The type of the data displayed: BPF program, BPF map, kprobe, or uprobe.

COUNT

The number of items of this type that belong to the specified process.

## SOURCE
This is from bcc.

https://github.com/iovisor/bcc

Also look in the bcc distribution for a companion _examples.txt file containing example usage, output, and commentary for this tool.

## OS
Linux

## STABILITY
Unstable - in development.

## AUTHOR
Sasha Goldshtein


bcc-bps

title: bcc-bps(8)

text:
# bcc-bps(8)

## NAME
bps - List all BPF programs. 'ps' for BPF programs.

## SYNOPSIS
bps [bpf-prog-id]

## DESCRIPTION
bps lists all BPF programs loaded into the kernel. It is similar to the ps command but for the BPF programs.

Each loaded bpf program is identified by an unique integer (i.e. bpf-prog-id or simply BID). If a bpf-prog-id is specified, the maps used by bpf-prog-id will also be listed.

## EXAMPLES
List all BPF programs loaded into the kernel:

bps

Show the details and maps of BID 6:

bps 6

## BPF PROGRAM FIELDS
BID

BPF program ID. It ends with '-' if it is not jitted.

TYPE

The type of a BPF program. e.g. kprobe, tracepoint, xdp...etc.

UID

The user ID that loaded the BPF program.

\#MAPS

Total number of maps used by a BPF program.

LoadTime

When was the BPF program loaded?

NAME

The name of a BPF program. The user space library (like bcc ) usually uses the C function name of the original BPF's source code as the program name. It could be empty if the user space did not provide a name.

## BPF MAP FIELDS
MID

BPF map ID.

TYPE

The type of a BPF map. e.g. hash, array, stack trace...etc.

FLAGS

The flags used to create the BP map.

KeySz

The key size of a BPF map.

ValueSz

The value size of a BPF map.

MaxEnts

The maximum number of entries of a map.

NAME

The name of a BPF map. The user space library (like bcc ) usually uses the C variable name of the BPF map as its name. It could be empty if the user space did not provide a name.

## SOURCE
This is from bcc.

https://github.com/iovisor/bcc

## OS
Linux

## STABILITY
Unstable - in development.

## AUTHOR
Martin Lau


bcc-btrfsdist

title: bcc-btrfsdist(8)

text:
# bcc-btrfsdist(8)

## NAME
btrfsdist - Summarize btrfs operation latency. Uses Linux eBPF/bcc.

## SYNOPSIS
btrfsdist [-h] [-T] [-N] [-d] [interval] [count]

## DESCRIPTION
This tool summarizes time (latency) spent in common btrfs file operations: reads, writes, opens, and syncs, and presents it as a power-of-2 histogram. It uses an in-kernel eBPF map to store the histogram for efficiency.

Since this works by tracing the btrfs_file_operations interface functions, it will need updating to match any changes to these functions.

Since this uses BPF, only the root user can use this tool.

## REQUIREMENTS
CONFIG_BPF and bcc.

## OPTIONS
-h

Print usage message.

-T

Don't include timestamps on interval output.

-m

Output in milliseconds.

-p PID

Trace this PID only.

## EXAMPLES
Trace btrfs operation time, and print a summary on Ctrl-C:

\# btrfsdist

Trace PID 181 only:

\# btrfsdist -p 181

Print 1 second summaries, 10 times:

\# btrfsdist 1 10

1 second summaries, printed in milliseconds

\# btrfsdist -m 1

## FIELDS
msecs

Range of milliseconds for this bucket.

usecs

Range of microseconds for this bucket.

count

Number of operations in this time range.

distribution

ASCII representation of the distribution (the count column).

## OVERHEAD
This adds low-overhead instrumentation to btrfs writes and fsyncs, as well as all system reads and opens (due to the current implementation of the btrfs_file_operations interface). Particularly, all reads and writes from the file system cache will incur extra overhead while tracing. Such reads and writes can be very frequent (depending on the workload; eg, 1M/sec), at which point the overhead of this tool may become noticeable. Measure and quantify before use.

## SOURCE
This is from bcc.

https://github.com/iovisor/bcc

Also look in the bcc distribution for a companion _examples.txt file containing example usage, output, and commentary for this tool.

## OS
Linux

## STABILITY
Unstable - in development.

## AUTHOR
Brendan Gregg

## SEE ALSO
btrfsslower(8)


bcc-btrfsslower

title: bcc-btrfsslower(8)

text:
# bcc-btrfsslower(8)

## NAME
btrfsslower - Trace slow btrfs file operations, with per-event details.

## SYNOPSIS
btrfsslower [-h] [-j] [-p PID] [min_ms] [-d DURATION]

## DESCRIPTION
This tool traces common btrfs file operations: reads, writes, opens, and syncs. It measures the time spent in these operations, and prints details for each that exceeded a threshold.

WARNING: See the OVERHEAD section.

By default, a minimum millisecond threshold of 10 is used. If a threshold of 0 is used, all events are printed (warning: verbose).

Since this works by tracing the btrfs_file_operations interface functions, it will need updating to match any changes to these functions.

Since this uses BPF, only the root user can use this tool.

## REQUIREMENTS
CONFIG_BPF and bcc.

## OPTIONS
-p PID Trace this PID only.

min_ms

Minimum I/O latency (duration) to trace, in milliseconds. Default is 10 ms.

-d DURATION

Total duration of trace in seconds.

## EXAMPLES
Trace synchronous file reads and writes slower than 10 ms:

\# btrfsslower

Trace slower than 1 ms:

\# btrfsslower 1

Trace slower than 1 ms, and output just the fields in parsable format (csv):

\# btrfsslower -j 1

Trace all file reads and writes (warning: the output will be verbose):

\# btrfsslower 0

Trace slower than 1 ms, for PID 181 only:

\# btrfsslower -p 181 1

Trace for 10 seconds only:

\# btrfsslower -d 10

## FIELDS
TIME(s)

Time of I/O completion since the first I/O seen, in seconds.

COMM

Process name.

PID

Process ID.

T

Type of operation. R == read, W == write, O == open, S == fsync.

OFF_KB

File offset for the I/O, in Kbytes.

BYTES

Size of I/O, in bytes.

LAT(ms)

Latency (duration) of I/O, measured from when it was issued by VFS to the filesystem, to when it completed. This time is inclusive of block device I/O, file system CPU cycles, file system locks, run queue latency, etc. It's a more accurate measure of the latency suffered by applications performing file system I/O, than to measure this down at the block device interface.

FILENAME

A cached kernel file name (comes from dentry->d_name.name).

ENDTIME_us

Completion timestamp, microseconds (-j only).

OFFSET_b

File offset, bytes (-j only).

LATENCY_us

Latency (duration) of the I/O, in microseconds (-j only).

## OVERHEAD
This adds low-overhead instrumentation to btrfs writes and fsyncs, as well as all system reads and opens (due to the current implementation of the btrfs_file_operations interface). Particularly, all reads and writes from the file system cache will incur extra overhead while tracing. Such reads and writes can be very frequent (depending on the workload; eg, 1M/sec), at which point the overhead of this tool may become noticeable. Measure and quantify before use. If this continues to be a problem, consider switching to a tool that prints in-kernel summaries only, such as btrfsdist(8).

Note that the overhead of this tool should be less than fileslower(8), as this tool targets btrfs functions only, and not all file read/write paths (which can include socket I/O).

## SOURCE
This is from bcc.

https://github.com/iovisor/bcc

Also look in the bcc distribution for a companion _examples.txt file containing example usage, output, and commentary for this tool.

## OS
Linux

## STABILITY
Unstable - in development.

## AUTHOR
Brendan Gregg

## SEE ALSO
btrfsdist(8), biosnoop(8), funccount(8), fileslower(8)


bcc-cachestat

title: bcc-cachestat(8)

text:
# bcc-cachestat(8)

## NAME
cachestat - Statistics for linux page cache hit/miss ratios. Uses Linux eBPF/bcc.

## SYNOPSIS
cachestat [-T] [interval [count]]

## DESCRIPTION
This traces four kernel functions and prints per-second summaries. This can be useful for general workload characterization, and looking for patterns in operation usage over time.

This works by tracing kernel page cache functions using dynamic tracing, and will need updating to match any changes to these functions. Edit the script to customize which functions are traced.

Since this uses BPF, only the root user can use this tool.

## REQUIREMENTS
CONFIG_BPF and bcc.

## EXAMPLES
Print summaries every second:

\# cachestat

Print summaries every second with timestamp:

\# cachestat -T

Print output every five seconds, three times:

\# cachestat 5 3

Print output with timestamp every five seconds, three times:

\# cachestat -T 5 3

## FIELDS
TIME

Timestamp.

HITS

Number of page cache hits.

MISSES

Number of page cache misses.

DIRTIES

Number of dirty pages added to the page cache.

HITRATIO

The hit ratio as a percentage.

READ_HIT%

Read hit percent of page cache usage.

WRITE_HIT%

Write hit percent of page cache usage.

BUFFERS_MB

Buffers size taken from /proc/meminfo.

CACHED_MB

Cached amount of data in current page cache taken from /proc/meminfo.

## OVERHEAD
This traces various kernel page cache functions and maintains in-kernel counts, which are asynchronously copied to user-space. While the rate of operations can be very high (>1G/sec) we can have up to 34% overhead, this is still a relatively efficient way to trace these events, and so the overhead is expected to be small for normal workloads. Measure in a test environment.

## SOURCE
This is from bcc.

https://github.com/iovisor/bcc

Also look in the bcc distribution for a companion _examples.txt file containing example usage, output, and commentary for this tool.

## OS
Linux

## STABILITY
Unstable - in development.

## AUTHOR
Allan McAleavy

## SEE ALSO
https://github.com/brendangregg/perf-tools/blob/master/fs/cachestat


bcc-cachetop

title: bcc-cachetop(8)

text:
# bcc-cachetop(8)

## NAME
cachetop - Statistics for linux page cache hit/miss ratios per processes. Uses Linux eBPF/bcc.

## SYNOPSIS
cachetop [-p PID] [interval]

## DESCRIPTION
This traces four kernel functions and prints per-processes summaries every interval seconds. This can be useful for processes workload characterization, and looking for patterns in operation usage over time. It provides a top-like interface which by default sorts by HITS in ascending order.

This works by tracing kernel page cache functions using dynamic tracing, and will need updating to match any changes to these functions. Edit the script to customize which functions are traced.

Since this uses BPF, only the root user can use this tool.

## OPTIONS
-p PID

Trace this PID only.

## KEYBINDINGS
The following keybindings can be used to control the output of cachetop.

<

Use the previous column for sorting.

>

Use the next column for sorting.

r

Toggle sorting order (default ascending).

q

Quit cachetop.

## REQUIREMENTS
CONFIG_BPF and bcc.

## EXAMPLES
Update summaries every five second:

\# cachetop

Print summaries each second:

\# cachetop 1

## FIELDS
PID

Process ID of the process causing the cache activity.

UID

User ID of the process causing the cache activity.

CMD

Name of the process.

HITS

Number of page cache hits.

MISSES

Number of page cache misses.

DIRTIES

Number of dirty pages added to the page cache.

READ_HIT%

Read hit percent of page cache usage.

WRITE_HIT%

Write hit percent of page cache usage.

BUFFERS_MB

Buffers size taken from /proc/meminfo.

CACHED_MB

Cached amount of data in current page cache taken from /proc/meminfo.

## OVERHEAD
This traces various kernel page cache functions and maintains in-kernel counts, which are asynchronously copied to user-space. While the rate of operations can be very high (>1G/sec) we can have up to 34% overhead, this is still a relatively efficient way to trace these events, and so the overhead is expected to be small for normal workloads. Measure in a test environment.

## SOURCE
This is from bcc.

https://github.com/iovisor/bcc

Also look in the bcc distribution for a companion _examples.txt file containing example usage, output, and commentary for this tool.

## OS
Linux

## STABILITY
Unstable - in development.

## AUTHOR
Emmanuel Bretelle, Rocky Xing

## SEE ALSO
cachestat (8)


bcc-capable

title: bcc-capable(8)

text:
# bcc-capable(8)

## NAME
capable - Trace security capability checks (cap_capable()).

## SYNOPSIS
capable [-h] [-v] [-p PID] [-K] [-U] [-x] [--cgroupmap MAPPATH]

[--mntnsmap MAPPATH] [--unique]

## DESCRIPTION
This traces security capability checks in the kernel, and prints details for each call. This can be useful for general debugging, and also security enforcement: determining a white list of capabilities an application needs.

Since this uses BPF, only the root user can use this tool.

## REQUIREMENTS
CONFIG_BPF, bcc.

## OPTIONS
-h USAGE message.

-v

Include non-audit capability checks. These are those deemed not interesting and not necessary to audit, such as CAP_SYS_ADMIN checks on memory allocation to affect the behavior of overcommit.

-K

Include kernel stack traces to the output.

-U

Include user-space stack traces to the output.

-x

Show extra fields in TID and INSETID columns.

--cgroupmap MAPPATH

Trace cgroups in this BPF map only (filtered in-kernel).

--mntnsmap MAPPATH

Trace mount namespaces in this BPF map only (filtered in-kernel).

--unique

Don't repeat stacks for the same PID or cgroup.

## EXAMPLES
Trace all capability checks system-wide:

\# capable

Trace capability checks for PID 181:

\# capable -p 181

Trace capability checks in a set of cgroups only (see special_filtering.md

from bcc sources for more details): # capable --cgroupmap /sys/fs/bpf/test01

## FIELDS
TIME(s)

Time of capability check: HH:MM:SS.

UID

User ID.

PID

Process ID.

COMM

Process name. CAP Capability number. NAME Capability name. See capabilities(7) for descriptions.

AUDIT

Whether this was an audit event. Use -v to include non-audit events. INSETID Whether the INSETID bit was set (Linux >= 5.1).

## OVERHEAD
This adds low-overhead instrumentation to capability checks, which are expected to be low frequency, however, that depends on the application. Test in a lab environment before use.

## SOURCE
This is from bcc.

https://github.com/iovisor/bcc

Also look in the bcc distribution for a companion _examples.txt file containing example usage, output, and commentary for this tool.

## OS
Linux

## STABILITY
Unstable - in development.

## AUTHOR
Brendan Gregg

## SEE ALSO
capabilities(7)


bcc-cobjnew

title: bcc-cobjnew(8)

summary: Summarize object allocations in

text:
# bcc-cobjnew(8)

## NAME
uobjnew, cobjnew, javaobjnew, rubyobjnew, tclobjnew - Summarize object allocations in high-level languages.

## SYNOPSIS
cobjnew [-h] [-C TOP_COUNT] [-S TOP_SIZE] [-v] pid [interval]

javaobjnew [-h] [-C TOP_COUNT] [-S TOP_SIZE] [-v] pid [interval]

rubyobjnew [-h] [-C TOP_COUNT] [-S TOP_SIZE] [-v] pid [interval]

tclobjnew [-h] [-C TOP_COUNT] [-S TOP_SIZE] [-v] pid [interval]

uobjnew [-h] [-C TOP_COUNT] [-S TOP_SIZE] [-v] [-l {c,java,ruby,tcl}] pid [interval]

## DESCRIPTION
uobjnew traces object allocations in high-level languages (including "malloc") and prints summaries of the most frequently allocated types by number of objects or number of bytes.

This tool relies on USDT probes embedded in many high-level languages, such as C, Java, Ruby, and Tcl. It requires a runtime instrumented with these probes, which in some cases requires building from source with a USDT-specific flag, such as "--enable-dtrace" or "--with-dtrace". For Java, the Java process must be started with the "-XX:+ExtendedDTraceProbes" flag.

Since this uses BPF, only the root user can use this tool.

## REQUIREMENTS
CONFIG_BPF and bcc.

## OPTIONS
-C TOP_COUNT

Print the top object types sorted by number of instances.

-S TOP_SIZE

Print the top object types sorted by size.

-v

Print the resulting BPF program, for debugging purposes.

{c,java,ruby,tcl}

The language to trace.

pid

The process id to trace.

interval

Wait this many seconds and then print the summary and exit. By default, wait for Ctrl+C to exit.

## EXAMPLES
Trace object allocations in a Ruby process:

\# uobjnew ruby 148

Trace object allocations from "malloc" and print the top 10 by total size:

\# uobjnew -S 10 c 1788

## FIELDS
TYPE

The object type being allocated. For C (malloc), this is the block size.

ALLOCS

The number of objects allocated.

BYTES

The number of bytes allocated.

## OVERHEAD
Object allocation events are quite frequent, and therefore the overhead from running this tool can be considerable. Use with caution and make sure to test before using in a production environment. Nonetheless, even thousands of allocations per second will likely produce a reasonable overhead when investigating a problem.

## SOURCE
This is from bcc.

https://github.com/iovisor/bcc

Also look in the bcc distribution for a companion _example.txt file containing example usage, output, and commentary for this tool.

## OS
Linux

## STABILITY
Unstable - in development.

## AUTHOR
Sasha Goldshtein

## SEE ALSO
ustat(8), ugc(8), memleak(8)


bcc-compactsnoop

title: bcc-compactsnoop(8)

text:
# bcc-compactsnoop(8)

## NAME
compactsnoop - Trace compact zone events. Uses Linux eBPF/bcc.

## SYNOPSIS
compactsnoop [-h] [-T] [-p PID] [-d DURATION] [-K] [-e]

## DESCRIPTION
compactsnoop traces the compact zone events, showing which processes are allocing pages with memory compaction. This can be useful for discovering when compact_stall (/proc/vmstat) continues to increase, whether it is caused by some critical processes or not.

This works by tracing the compact zone events using raw_tracepoints and one kretprobe.

For the Centos 7.6 (3.10.x kernel), see the version under tools/old, which uses an older memory compaction mechanism.

Since this uses BPF, only the root user can use this tool.

## REQUIREMENTS
CONFIG_BPF and bcc.

## OPTIONS
-h

Print usage message.

-T

Include a timestamp column.

-p PID

Trace this process ID only (filtered in-kernel).

-d DURATION

Total duration of trace in seconds.

-K

Output kernel stack trace

-e

Show extended fields.

## EXAMPLES
Trace all compact zone events:

\# compactsnoop

Trace all compact zone events, for 10 seconds only:

\# compactsnoop -d 10

## FIELDS
TIME(s)

Time of the call, in seconds.

COMM

Process name

PID

Process ID

NODE

Memory node

ZONE

Zone of the node (such as DMA, DMA32, NORMAL eg)

ORDER

Shows which order alloc cause memory compaction, -1 means all orders (eg: write to /proc/sys/vm/compact_memory)

MODE

SYNC OR ASYNC

FRAGIDX (extra column)

The FRAGIDX is short for fragmentation index, which only makes sense if an allocation of a requested size would fail. If that is true, the fragmentation index indicates whether external fragmentation or a lack of memory was the problem. The value can be used to determine if page reclaim or compaction should be used.

Index is between 0 and 1 so return within 3 decimal places

0 => allocation would fail due to lack of memory

1 => allocation would fail due to fragmentation

MIN (extra column)

The min watermark of the zone

LOW (extra column)

The low watermark of the zone

HIGH (extra column)

The high watermark of the zone

FREE (extra column)

The nr_free_pages of the zone

LAT(ms)

compact zone's latency

STATUS

The compaction's result.

For (CentOS 7.6's kernel), the status include:

"skipped" (COMPACT_SKIPPED): compaction didn't start as it was not possible or direct reclaim was more suitable

"continue" (COMPACT_CONTINUE): compaction should continue to another pageblock

"partial" (COMPACT_PARTIAL): direct compaction partially compacted a zone and there are suitable pages

"complete" (COMPACT_COMPLETE): The full zone was compacted

For (kernel 4.7 and above):

"not_suitable_zone" (COMPACT_NOT_SUITABLE_ZONE): For more detailed tracepoint output - internal to compaction

"skipped" (COMPACT_SKIPPED): compaction didn't start as it was not possible or direct reclaim was more suitable

"deferred" (COMPACT_DEFERRED): compaction didn't start as it was deferred due to past failures

"no_suitable_page" (COMPACT_NOT_SUITABLE_PAGE): For more detailed tracepoint output - internal to compaction

"continue" (COMPACT_CONTINUE): compaction should continue to another pageblock

"complete" (COMPACT_COMPLETE): The full zone was compacted scanned but wasn't successful to compact suitable pages.

"partial_skipped" (COMPACT_PARTIAL_SKIPPED): direct compaction has scanned part of the zone but wasn't successful to compact suitable pages.

"contended" (COMPACT_CONTENDED): compaction terminated prematurely due to lock contentions

"success" (COMPACT_SUCCESS): direct compaction terminated after concluding that the allocation should now succeed

## OVERHEAD
This traces the kernel compact zone kprobe/kretprobe or raw_tracepoints and prints output for each event. As the rate of this is generally expected to be low (< 1000/s), the overhead is also expected to be negligible.

## SOURCE
This is from bcc.

https://github.com/iovisor/bcc

Also look in the bcc distribution for a companion _examples.txt file containing example usage, output, and commentary for this tool.

## OS
Linux

## STABILITY
Unstable - in development.

## AUTHOR
Wenbo Zhang


bcc-cpudist

title: bcc-cpudist(8)

text:
# bcc-cpudist(8)

## NAME
cpudist - On- and off-CPU task time as a histogram.

## SYNOPSIS
cpudist [-h] [-O] [-T] [-m] [-P] [-L] [-p PID] [-I] [-e] [interval] [count]

## DESCRIPTION
This measures the time a task spends on the CPU before being descheduled, and shows the times as a histogram. Tasks that spend a very short time on the CPU can be indicative of excessive context-switches and poor workload distribution, and possibly point to a shared source of contention that keeps tasks switching in and out as it becomes available (such as a mutex).

Similarly, the tool can also measure the time a task spends off-CPU before it is scheduled again. This can be helpful in identifying long blocking and I/O operations, or alternatively very short descheduling times due to short-lived locks or timers.

By default CPU idle time are excluded by simply excluding PID 0.

This tool uses in-kernel eBPF maps for storing timestamps and the histogram, for efficiency. Despite this, the overhead of this tool may become significant for some workloads: see the OVERHEAD section.

Since this uses BPF, only the root user can use this tool.

## REQUIREMENTS
CONFIG_BPF and bcc.

## OPTIONS
-h

Print usage message.

-O

Measure off-CPU time instead of on-CPU time.

-T

Include timestamps on output.

-m

Output histogram in milliseconds.

-P

Print a histogram for each PID (tgid from the kernel's perspective).

-L

Print a histogram for each TID (pid from the kernel's perspective).

-p PID

Only show this PID (filtered in kernel for efficiency).

-I

Include CPU idle time (by default these are excluded).

-e

Show extension summary (average/total/count).

interval

Output interval, in seconds.

count

Number of outputs.

## EXAMPLES
Summarize task on-CPU time as a histogram:

\# cpudist

Summarize task off-CPU time as a histogram:

\# cpudist -O

Print 1 second summaries, 10 times:

\# cpudist 1 10

Print 1 second summaries, using milliseconds as units for the histogram, and include timestamps on output:

\# cpudist -mT 1

Trace PID 185 only, 1 second summaries:

\# cpudist -p 185 1

Include CPU idle time:

\# cpudist -I

Also show extension summary:

\# cpudist -e

## FIELDS
usecs

Microsecond range

msecs

Millisecond range

count

How many times a task event fell into this range

distribution

An ASCII bar chart to visualize the distribution (count column)

## OVERHEAD
This traces scheduler tracepoints, which can become very frequent. While eBPF has very low overhead, and this tool uses in-kernel maps for efficiency, the frequency of scheduler events for some workloads may be high enough that the overhead of this tool becomes significant. Measure in a lab environment to quantify the overhead before use.

## SOURCE
This is from bcc.

https://github.com/iovisor/bcc

Also look in the bcc distribution for a companion _example.txt file containing example usage, output, and commentary for this tool.

## OS
Linux

## STABILITY
Unstable - in development.

## AUTHOR
Sasha Goldshtein, Rocky Xing

## SEE ALSO
pidstat(1), runqlat(8)


bcc-cpuunclaimed

title: bcc-cpuunclaimed(8)

text:
# bcc-cpuunclaimed(8)

## NAME
cpuunclaimed - Sample CPU run queues and calculate unclaimed idle CPU. Uses Linux eBPF/bcc.

## SYNOPSIS
cpuunclaimed [-T] [-j] [-J] [interval [count]]

## DESCRIPTION
This tool samples the length of the run queues and determine when there are idle CPUs, yet queued threads waiting their turn. It reports the amount of idle (yet unclaimed by waiting threads) CPU as a system-wide percentage.

This situation can happen for a number of reasons:

-

An application has been bound to some, but not all, CPUs, and has runnable threads that cannot migrate to other CPUs due to this configuration.

-

CPU affinity: an optimization that leaves threads on CPUs where the CPU caches are warm, even if this means short periods of waiting while other CPUs are idle. The wait period is tunale (see sysctl, kernel.sched*).

-

Scheduler bugs.

An unclaimed idle of < 1% is likely to be CPU affinity, and not usually a cause for concern. By leaving the CPU idle, overall throughput of the system may be improved. This tool is best for identifying larger issues, > 2%, due to the coarseness of its 99 Hertz samples.

This is an experimental tool that currently works by use of sampling to keep overheads low. Tool assumptions:

-

CPU samples consistently fire around the same offset. There will sometimes be a lag as a sample is delayed by higher-priority interrupts, but it is assumed the subsequent samples will catch up to the expected offsets (as is seen in practice). You can use -J to inspect sample offsets. Some systems can power down CPUs when idle, and when they wake up again they may begin firing at a skewed offset: this tool will detect the skew, print an error, and exit.

-

All CPUs are online (see ncpu).

If this identifies unclaimed CPU, you can double check it by dumping raw samples (-j), as well as using other tracing tools to instrument scheduler events (although this latter approach has much higher overhead).

Since this uses BPF, only the root user can use this tool.

## REQUIREMENTS
CONFIG_BPF and bcc.

## EXAMPLES
Sample and calculate unclaimed idle CPUs, output every 1 second (default:

\# cpuunclaimed

Print 5 second summaries, 10 times:

\# cpuunclaimed 5 10

Print 1 second summaries with timestamps:

\# cpuunclaimed -T 1

Raw dump of all samples (verbose), as comma-separated values:

\# cpuunclaimed -j

## FIELDS
%CPU

CPU utilization as a system-wide percentage.

unclaimed idle

Percentage of CPU resources that were idle when work was queued on other CPUs, as a system-wide percentage.

TIME

Time (HH:MM:SS)

TIMESTAMP_ns

Timestamp, nanoseconds.

CPU#

CPU ID.

OFFSET_ns_CPU#

Time offset that a sample fired within a sample group for this CPU.

## OVERHEAD
The overhead is expected to be low/negligible as this tool uses sampling at 99 Hertz (on all CPUs), which has a fixed and low cost, rather than sampling every scheduler event as many other approaches use (which can involve instrumenting millions of events per second). Sampled CPUs, run queue lengths, and timestamps are written to ring buffers that are periodically read by user space for reporting. Measure overhead in a test environment.

## SOURCE
This is from bcc.

https://github.com/iovisor/bcc

Also look in the bcc distribution for a companion _examples.txt file containing example usage, output, and commentary for this tool.

## OS
Linux

## STABILITY
Unstable - in development.

## AUTHOR
Brendan Gregg

## SEE ALSO
runqlen(8)


bcc-criticalstat

title: bcc-criticalstat(8)

text:
# bcc-criticalstat(8)

## NAME
criticalstat - A tracer to find and report long atomic critical sections in kernel

## SYNOPSIS
criticalstat [-h] [-p] [-i] [-d DURATION]

## DESCRIPTION
criticalstat traces and reports occurrences of atomic critical sections in the kernel with useful stacktraces showing the origin of them. Such critical sections frequently occur due to use of spinlocks, or if interrupts or preemption were explicitly disabled by a driver. IRQ routines in Linux are also executed with interrupts disabled. There are many reasons. Such critical sections are a source of long latency/responsive issues for real-time systems.

This works by probing the preempt/irq and cpuidle tracepoints in the kernel. Since this uses BPF, only the root user can use this tool. Further, the kernel has to be built with certain CONFIG options enabled. See below.

## REQUIREMENTS
Enable following kernel configurations based on which kernel version you use.

- CONFIG_DEBUG_PREEMPT

- CONFIG_PREEMPT_TRACER

For kernel 4.19 and later:

- CONFIG_PREEMPTIRQ_TRACEPOINTS

- CONFIG_TRACE_IRQFLAGS

- CONFIG_TRACE_PREEMPT_TOGGLE

For kernel 4.15 to 4.18:

- CONFIG_PREEMPTIRQ_EVENTS

- CONFIG_PROVE_LOCKING

- CONFIG_DEBUG_PREEMPT Additionally, the following options should be turned off on older kernels:

- CONFIG_LOCKDEP

## OPTIONS
-h

Print usage message.

-p

Find long sections where preemption was disabled on local CPU.

-i

Find long sections where interrupt was disabled on local CPU.

-d DURATION

Only identify sections that are longer than DURATION in microseconds.

## EXAMPLES
Run with default options: irq disabled for more than 100 uS

\# criticalstat

Find sections with preemption disabled for more than 100 uS.

\# criticalstat -p

Find sections with IRQ disabled for more than 500 uS.

\# criticalstat -d 500

Find sections with preemption disabled for more than 500 uS.

\# criticalstat -p -d 500

## OVERHEAD
This tool can cause overhead if the application is spending a lot of time in kernel mode. The overhead is variable but can be 2-4% of performance degradation. If overhead is seen to be too much, please pass a higher DURATION to the -d option to filter more aggressively.

## SOURCE
This is from bcc.

https://github.com/iovisor/bcc

Also look in the bcc distribution for a companion _examples.txt file containing example usage, output, and commentary for this tool.

## OS
Linux

## STABILITY
Unstable - in development.

## AUTHOR
Joel Fernandes

## SEE ALSO
Linux kernel's preemptoff and irqoff tracers.


bcc-cthreads

title: bcc-cthreads(8)

text:
# bcc-cthreads(8)

## NAME
uthreads, cthreads, javathreads - Trace thread creation events in Java or pthreads.

## SYNOPSIS
cthreads [-h] [-v] pid javathreads [-h] [-v] pid uthreads [-h] [-l {c,java,none}] [-v] pid

## DESCRIPTION
This traces thread creation events in Java processes, or pthread creation events in any process. When a thread is created, its name or start address is printed.

Since this uses BPF, only the root user can use this tool.

## REQUIREMENTS
CONFIG_BPF and bcc.

## OPTIONS
-l {c,java,none}

The language to trace. C and none select tracing pthreads only, regardless of the runtime being traced.

-v

Print the resulting BPF program, for debugging purposes.

pid

The process id to trace.

## EXAMPLES
Trace Java thread creations:

\# uthreads -l java 148

Trace pthread creations:

\# uthreads 1802

## FIELDS
TIME

The event's time in seconds from the beginning of the trace.

ID

The thread's ID. The information in this column depends on the runtime.

TYPE

Event type -- thread start, stop, or pthread event.

DESCRIPTION

The thread's name or start address function name.

## OVERHEAD
Thread start and stop events are usually not very frequent, which makes this tool's overhead negligible.

## SOURCE
This is from bcc.

https://github.com/iovisor/bcc

Also look in the bcc distribution for a companion _example.txt file containing example usage, output, and commentary for this tool.

## OS
Linux

## STABILITY
Unstable - in development.

## AUTHOR
Sasha Goldshtein

## SEE ALSO
ustat(8), trace(8)


bcc-dbslower

title: bcc-dbslower(8)

text:
# bcc-dbslower(8)

## NAME
dbslower - Trace MySQL/PostgreSQL server queries slower than a threshold.

## SYNOPSIS
dbslower [-v] [-p PID [PID ...]] [-x PATH] [-m THRESHOLD] {mysql,postgres}

## DESCRIPTION
This traces queries served by a MySQL or PostgreSQL server, and prints those that exceed a latency (query time) threshold. By default a threshold of 1 ms is used.

This uses User Statically-Defined Tracing (USDT) probes, a feature added to MySQL and PostgreSQL for DTrace support, but which may not be enabled on a given installation. See requirements. Alternatively, MySQL queries can be traced without the USDT support using the -x option.

Since this uses BPF, only the root user can use this tool.

## REQUIREMENTS
CONFIG_BPF, bcc, and MySQL server with USDT probe support (when configuring the build: -DENABLE_DTRACE=1) or PostgreSQL server with USDT probe support (when configuring the build: --enable-dtrace).

## OPTIONS
-h Print usage message.

-p PID

Trace this PID. If no PID is specified, the tool will attempt to automatically detect the MySQL or PostgreSQL processes running on the system.

-x PATH

Path to MySQL binary. This option allow to MySQL queries even when USDT probes aren't enabled on the MySQL server.

-m THRESHOLD

Minimum query latency (duration) to trace, in milliseconds. Default is 1 ms.

{mysql,postgres}

The database engine to trace.

## EXAMPLES
Trace MySQL server queries slower than 1 ms:

\# dbslower mysql

Trace slower than 10 ms for PostgreSQL in process 408:

\# dbslower postgres -p 408 -m 10

## FIELDS
TIME(s)

Time of query start, in seconds.

PID

Process ID of the traced server.

MS

Milliseconds for the query, from start to end.

QUERY

Query string, truncated to 256 characters.

## OVERHEAD
This adds low-overhead instrumentation to queries, and only emits output data from kernel to user-level if they query exceeds the threshold. If the server query rate is less than 1,000/sec, the overhead is expected to be negligible. If the query rate is higher, test to gauge overhead.

## SOURCE
This is from bcc.

https://github.com/iovisor/bcc

Also look in the bcc distribution for a companion _examples.txt file containing example usage, output, and commentary for this tool.

## OS
Linux

## STABILITY
Unstable - in development.

## AUTHOR
Sasha Goldshtein, Brendan Gregg

## SEE ALSO
biosnoop(8), mysqld_qslower(8), dbstat(8)


bcc-dbstat

title: bcc-dbstat(8)

text:
# bcc-dbstat(8)

## NAME
dbstat - Collect histograms of MySQL/PostgreSQL query latencies.

## SYNOPSIS
dbstat [-v] [-p PID [PID ...]] [-m THRESHOLD] [-u] [-i INTERVAL] {mysql,postgres}

## DESCRIPTION
This traces queries served by a MySQL or PostgreSQL server, and collects a histogram of query latencies. The histogram is printed at the end of collection, or at specified intervals.

This uses User Statically-Defined Tracing (USDT) probes, a feature added to MySQL and PostgreSQL for DTrace support, but which may not be enabled on a given installation. See requirements.

Since this uses BPF, only the root user can use this tool.

## REQUIREMENTS
CONFIG_BPF, bcc, and MySQL server with USDT probe support (when configuring the build: -DENABLE_DTRACE=1) or PostgreSQL server with USDT probe support (when configuring the build: --enable-dtrace).

## OPTIONS
-h Print usage message.

-p PID

Trace this PID. If no PID is specified, the tool will attempt to automatically detect the MySQL or PostgreSQL processes running on the system.

-m THRESHOLD

Minimum query latency (duration) to trace, in milliseconds. Default is all queries.

-u

Display query latencies in microseconds (default: milliseconds).

-i INTERVAL

Print summaries (histograms) at this interval, specified in seconds.

{mysql,postgres}

The database engine to trace.

## EXAMPLES
Display histogram of MySQL query latencies:

\# dbstat mysql

Display histogram of PostgreSQL query latencies slower than 10ms in pid 408:

\# dbstat postgres -p 408 -m 10

Display histogram of PostgreSQL query latencies at 3-second intervals:

\# dbstat postgres -i 3

## OVERHEAD
This adds low-overhead instrumentation to queries, and only emits output data from kernel to user-level if they query exceeds the threshold. If the server query rate is less than 1,000/sec, the overhead is expected to be negligible. If the query rate is higher, test to gauge overhead.

## SOURCE
This is from bcc.

https://github.com/iovisor/bcc

Also look in the bcc distribution for a companion _examples.txt file containing example usage, output, and commentary for this tool.

## OS
Linux

## STABILITY
Unstable - in development.

## AUTHOR
Sasha Goldshtein

## SEE ALSO
dbslower(8)


bcc-dcsnoop

title: bcc-dcsnoop(8)

text:
# bcc-dcsnoop(8)

## NAME
dcsnoop - Trace directory entry cache (dcache) lookups. Uses Linux eBPF/bcc.

## SYNOPSIS
dcsnoop [-h] [-a]

## DESCRIPTION
By default, this traces every failed dcache lookup (cache miss), and shows the process performing the lookup and the filename requested. A -a option can be used to show all lookups, not just failed ones.

The output of this tool can be verbose, and is intended for further investigations of dcache performance beyond dcstat(8), which prints per-second summaries.

This uses kernel dynamic tracing of the d_lookup() function, and will need and will need updating to match any changes to this function.

Since this uses BPF, only the root user can use this tool.

## REQUIREMENTS
CONFIG_BPF and bcc.

## OPTIONS
-h

Print usage message.

-a

Trace references, not just failed lookups.

## EXAMPLES
Trace failed dcache lookups:

\# dcsnoop

Trace all dcache lookups:

\# dcsnoop -a

## FIELDS
TIME(s)

Time of lookup, in seconds.

PID

Process ID.

COMM

Process name.

T

Type: R == reference (only visible with -a), M == miss. A miss will print two lines, one for the reference, and one for the miss.

FILE

The file name component that was being looked up. This contains trailing pathname components (after '/'), which will be the subject of subsequent lookups.

## OVERHEAD
File name lookups can be frequent (depending on the workload), and this tool prints a line for each failed lookup, and with -a, each reference as well. The output may be verbose, and the incurred overhead, while optimized to some extent, may still be from noticeable to significant. This is only really intended for deeper investigations beyond dcstat(8), when absolutely necessary. Measure and quantify the overhead in a test environment before use.

## SOURCE
This is from bcc.

https://github.com/iovisor/bcc

Also look in the bcc distribution for a companion _examples.txt file containing example usage, output, and commentary for this tool.

## OS
Linux

## STABILITY
Unstable - in development.

## AUTHOR
Brendan Gregg

## SEE ALSO
dcstat(1)


bcc-dcstat

title: bcc-dcstat(8)

text:
# bcc-dcstat(8)

## NAME
dcstat - Directory entry cache (dcache) stats. Uses Linux eBPF/bcc.

## SYNOPSIS
dcstat [interval [count]]

## DESCRIPTION
The Linux directory entry cache (dcache) improves the performance of file and directory name lookups. This tool provides per-second summary statistics of dcache performance.

This uses kernel dynamic tracing of kernel functions, lookup_fast() and d_lookup(), which will need to be modified to match kernel changes.

Since this uses BPF, only the root user can use this tool.

## REQUIREMENTS
CONFIG_BPF and bcc.

## EXAMPLES
Print summaries each second:

\# dcstat

Print output every five seconds, three times:

\# dcstat 5 3

## FIELDS
REFS/s

Number dcache lookups (references) per second.

SLOW/s

Number of dcache lookups that failed the lookup_fast() path and executed the lookup_slow() path instead.

MISS/s

Number of dcache misses (failed both fast and slow lookups).

HIT%

Percentage of dcache hits over total references.

## OVERHEAD
The overhead depends on the frequency of file and directory name lookups. While the per-event overhead is low, some applications may make over 100k lookups per second, and the low per-event overhead will begin to add up, and could begin to be measurable (over 10% CPU usage). Measure in a test environment.

## SOURCE
This is from bcc.

https://github.com/iovisor/bcc

Also look in the bcc distribution for a companion _examples.txt file containing example usage, output, and commentary for this tool.

## OS
Linux

## STABILITY
Unstable - in development.

## AUTHOR
Brendan Gregg

## SEE ALSO
dcsnoop(8)


bcc-deadlock

title: bcc-deadlock(8)

text:
# bcc-deadlock(8)

## NAME
deadlock - Find potential deadlocks (lock order inversions) in a running program.

## SYNOPSIS
deadlock [-h] [--binary BINARY] [--dump-graph DUMP_GRAPH] [--verbose] [--lock-symbols LOCK_SYMBOLS] [--unlock-symbols UNLOCK_SYMBOLS] pid

## DESCRIPTION
deadlock finds potential deadlocks in a running process. The program attaches uprobes on `pthread_mutex_lock` and `pthread_mutex_unlock` by default to build a mutex wait directed graph, and then looks for a cycle in this graph. This graph has the following properties:

- Nodes in the graph represent mutexes.

- Edge (A, B) exists if there exists some thread T where lock(A) was called and lock(B) was called before unlock(A) was called.

If there is a cycle in this graph, this indicates that there is a lock order inversion (potential deadlock). If the program finds a lock order inversion, the program will dump the cycle of mutexes, dump the stack traces where each mutex was acquired, and then exit.

This program can only find potential deadlocks that occur while the program is tracing the process. It cannot find deadlocks that may have occurred before the program was attached to the process.

This tool does not work for shared mutexes or recursive mutexes.

Since this uses BPF, only the root user can use this tool.

## REQUIREMENTS
CONFIG_BPF and bcc

## OPTIONS
-h, --help

show this help message and exit

--binary BINARY

If set, trace the mutexes from the binary at this path. For statically-linked binaries, this argument is not required. For dynamically-linked binaries, this argument is required and should be the path of the pthread library the binary is using. Example: /lib/x86_64-linux-gnu/libpthread.so.0

--dump-graph DUMP_GRAPH

If set, this will dump the mutex graph to the specified file.

--verbose

Print statistics about the mutex wait graph.

--lock-symbols LOCK_SYMBOLS

Comma-separated list of lock symbols to trace. Default is pthread_mutex_lock. These symbols cannot be inlined in the binary.

--unlock-symbols UNLOCK_SYMBOLS

Comma-separated list of unlock symbols to trace. Default is pthread_mutex_unlock. These symbols cannot be inlined in the binary.

-t THREADS, --threads THREADS

Specifies the maximum number of threads to trace. default 65536. Note. 40 bytes per thread.

-e EDGES, --edges EDGES

Specifies the maximum number of edge cases that can be recorded. default 65536. Note. 88 bytes per edge case.

pid

Pid to trace

## EXAMPLES
Find potential deadlocks in PID 181. The --binary argument is not needed for statically-linked binaries.

\# deadlock 181

Find potential deadlocks in PID 181. If the process was created from a dynamically-linked executable, the --binary argument is required and must be the path of the pthread library:

\# deadlock 181 --binary /lib/x86_64-linux-gnu/libpthread.so.0

Find potential deadlocks in PID 181. If the process was created from a statically-linked executable, optionally pass the location of the binary. On older kernels without https://lkml.org/lkml/2017/1/13/585, binaries that contain `:` in the path cannot be attached with uprobes. As a workaround, we can create a symlink to the binary, and provide the symlink name instead with the `--binary` option:

\# deadlock 181 --binary /usr/local/bin/lockinversion

Find potential deadlocks in PID 181 and dump the mutex wait graph to a file:

\# deadlock 181 --dump-graph graph.json

Find potential deadlocks in PID 181 and print mutex wait graph statistics:

\# deadlock 181 --verbose

Find potential deadlocks in PID 181 with custom mutexes:

\# deadlock 181 --lock-symbols custom_mutex1_lock,custom_mutex2_lock --unlock_symbols custom_mutex1_unlock,custom_mutex2_unlock

## OUTPUT
This program does not output any fields. Rather, it will keep running until it finds a potential deadlock, or the user hits Ctrl-C. If the program finds a potential deadlock, it will output the stack traces and lock order inversion in the following format and exit:

Potential Deadlock Detected!

Cycle in lock order graph: Mutex M0 => Mutex M1 => Mutex M0

Mutex M1 acquired here while holding Mutex M0 in Thread T:

[stack trace]

Mutex M0 previously acquired by the same Thread T here:

[stack trace]

Mutex M0 acquired here while holding Mutex M1 in Thread S:

[stack trace]

Mutex M1 previously acquired by the same Thread S here:

[stack trace]

Thread T created by Thread R here:

[stack trace]

Thread S created by Thread Q here:

[stack trace]

## OVERHEAD
This traces all mutex lock and unlock events and all thread creation events on the traced process. The overhead of this can be high if the process has many threads and mutexes. You should only run this on a process where the slowdown is acceptable.

## SOURCE
This is from bcc.

https://github.com/iovisor/bcc

Also look in the bcc distribution for a companion _examples.txt file containing example usage, output, and commentary for this tool.

## OS
Linux

## STABILITY
Unstable - in development.

## AUTHOR
Kenny Yu