`mc admin trace`

Description

The mc admin trace command displays API operations occurring on the target MinIO deployment.

Use mc admin on MinIO Deployments Only

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

Examples

Monitor All API operations

Use mc admin trace to monitor API operations on a MinIO deployment:

mc admin trace -a ALIAS

Replace ALIAS with the alias of the MinIO deployment.

See Calls that Return 503 Errors

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

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

Replace ALIAS with the alias of the MinIO deployment.

See Console Trace for a Path

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

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

Replace ALIAS with the alias of the MinIO 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 mc admin trace to monitor responses over a specific size:

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

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

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

Use mc admin trace to monitor long operations:

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

Replace ALIAS with the alias of the MinIO deployment.

Syntax

mc admin trace has the following syntax:

mc admin trace [FLAGS] TARGET

mc admin trace supports the following argument:

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

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

--call

Traces only matching call types. For example, the following command only traces calls of the type scanner.

mc admin trace --call scanner TARGET

Valid call types include:

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

If not specified, MinIO returns call types of s3.

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

--filter-request

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

Must be used with --filter-size flag.

--filter-response

Trace 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 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 MinIO 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, MinIO 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 function.
Count	The number of times the Call occurred.
RPM	The Rate Per Minute (RPM) of that Call.
Avg Time	The average time required for the Call to complete.
Min Time	The minimum time spent for the Call to complete.
Avg TTFB	New in version RELEASE.2023-11-15T22-45-58Z. The average Time To First Byte (TTFB) for the Call.
Max TTFB	New in version RELEASE.2023-11-15T22-45-58Z. The maximum Time To First Byte for the Call.
Errors	The number of Calls that failed with an error.
RX Avg	The average number of Bytes Received (RX) for the Call.
TX AVG	The average number of Bytes Sent (TX) for the Call.

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.