`bm admin trace`

Description

The bm admin trace command displays API operations occurring on the target Buckit deployment.

Use bm admin on Buckit Deployments Only

Buckit does not support using bm admin commands with other S3-compatible services, regardless of their claimed compatibility with Buckit deployments.

Examples

Monitor All API operations

Use bm admin trace to monitor API operations on a Buckit deployment:

bm admin trace -a ALIAS

Replace ALIAS with the alias of the Buckit deployment.

See Calls that Return 503 Errors

Use bm admin trace to monitor API operations that return a service unavailable 503 error:

bm admin trace -v --status-code 503 ALIAS

Replace ALIAS with the alias of the Buckit deployment.

See Console Trace for a Path

Use bm admin trace to monitor activity for a specific path:

bm admin trace --path my-bucket/my-prefix/* ALIAS

Replace ALIAS with the alias of the Buckit deployment.
Replace my-bucket/my-prefix/* with the bucket, prefix, and object name or wildcard you wish to trace.

See Console Trace for a Response Size Greater than 1Mb

Use bm admin trace to monitor responses over a specific size:

bm admin trace --filter-response --filter-size 1Mb ALIAS

Replace ALIAS with the alias of the Buckit deployment.
Replace 1Mb with the desired response size.

See Console Trace for a Request Operation Durations Greater than 5ms

Use bm admin trace to monitor long operations:

bm admin trace --filter-duration --filter-size 5ms ALIAS

Replace ALIAS with the alias of the Buckit deployment.

Syntax

bm admin trace has the following syntax:

bm admin trace [FLAGS] TARGET

bm admin trace supports the following argument:

TARGET: Specify the alias of a configured Buckit deployment for which to monitor API operations.

--all, a: Returns all traffic on the Buckit deployment, including internode traffic between Buckit servers.

--call

Traces only matching client operation or call types. For example, the following command only traces operations of the type scanner.

bm admin trace --call scanner TARGET

Valid call types include:

batch-keyrotation
batch-replication
bootstrap
decommission
ftp
healing
ilm
internal
os
rebalance
replication-resync
s3
scanner
storage

If not specified, Buckit returns call types of s3.

--errors, e: Returns failed API operations only.

--filter-request

Trace client operations or calls with request size greater than the specified --filter-size value.

Must be used with --filter-size flag.

--filter-response

Trace client operations or calls with response size greater than the specified --filter-size value.

Must be used with --filter-size flag.

--filter-size

Size limit of a filtered client operation or call.

Must be used with either --filter-request or --filter-response flag.

Valid units include:

Suffix	Unit Size
`k`	KB (Kilobyte, 1000 Bytes)
`m`	MB (Megabyte, 1000 Kilobytes)
`g`	GB (Gigabyte, 1000 Megabytes)
`t`	TB (Terrabyte, 1000 Gigabytes)
`ki`	KiB (Kibibyte, 1024 Bites)
`mi`	MiB (Mebibyte, 1024 Kibibytes)
`gi`	GiB (Gibibyte, 1024 Mebibytes)
`ti`	TiB (Tebibyte, 1024 Gibibytes)

--funcname: Returns calls for the entered function name.

--method: Returns call of the specified HTTP method.

--node: Returns calls for the specified server.

--path: Returns calls for the specified path.

--request-header: Returns calls matching the supplied request header.

--request-query: Returns calls matching the supplied request query parameter. This debug option should only be used at the direction of Buckit Support.

--response-duration: Trace calls with response duration greater than the specified value.

--response-threshold

Takes a time string as a value, such as 5ms. Returns only calls with a response time greater than the supplied threshold.

If not specified, Buckit returns calls with a response time greater than 5ms.

--status-code: Returns calls of the specified HTTP status code.

--stats

Accumulates aggregated statistics for each traced function call during the current trace session.

The output table includes the following columns.

Call	The name of the captured client operation or function.
Count	The number of times the client operation or call occurred.
RPM	The Rate Per Minute (RPM) of the client operation or call.
Avg Time	The average time required for the client operation or call to complete.
Min Time	The minimum time spent for the client operation or call to complete.
Max Time	The maximum time spent for the client operation or call to complete.
Avg TTFB	New in version RELEASE.2023-11-15T22-45-58Z. The average Time To First Byte (TTFB) for the client operation or call response.
Max TTFB	New in version RELEASE.2023-11-15T22-45-58Z. The maximum Time To First Byte for the client operation or call response.
Avg Size	Average size of client operation or call responses.
Errors	The number of client operations or calls that failed with an error.
RX Avg	The average number of Bytes Received (RX) for the client operation or call. This stat only displays if not zero (0).
TX AVG	The average number of Bytes Sent (TX) for the client operation or call. This stat only displays if not zero (0).

Accumulate stats, such as name, count, duration, min time, max time, time to first byte, or errors. Accumulates up to 15 stat entries.

--verbose: Returns verbose output.

Global Flags

This command supports any of the global flags.