.TH "GCLOUD_ALPHA_STORAGE_DIAGNOSE" 1



.SH "NAME"
.HP
gcloud alpha storage diagnose \- diagnose Google Cloud Storage



.SH "SYNOPSIS"
.HP
\f5gcloud alpha storage diagnose\fR \fIURL\fR [\fB\-\-test\-type\fR=[\fITEST_TYPES\fR,...]] [\fB\-\-download\-type\fR=\fIDOWNLOAD_TYPE\fR;\ default=<DownloadType.FILE:\ 'FILE'>] [\fB\-\-logs\-path\fR=\fILOGS_PATH\fR] [\fB\-\-upload\-type\fR=\fIUPLOAD_TYPE\fR;\ default=<UploadType.FILE:\ 'FILE'>] [\fB\-\-process\-count\fR=\fIPROCESS_COUNT\fR] [\fB\-\-thread\-count\fR=\fITHREAD_COUNT\fR] [\fB\-\-object\-count\fR=\fIOBJECT_COUNT\fR\ (\fB\-\-object\-size\fR=\fIOBJECT_SIZE\fR\ |\ \fB\-\-object\-sizes\fR=[\fIOBJECT_SIZES\fR,...])] [\fB\-\-export\fR\ :\ \fB\-\-destination\fR=\fIDESTINATION\fR] [\fIGCLOUD_WIDE_FLAG\ ...\fR]



.SH "DESCRIPTION"

\fB(ALPHA)\fR The diagnose command runs a series of diagnostic tests for common
gcloud storage issues.

The \f5URL\fR argument must name an exisiting bucket for which the user already
has write permissions. Standard billing also applies. Several test files/objects
will be uploaded and downloaded to this bucket to gauge out the performance
metrics. All the temporary files will be deleted on successfull completion of
the command.

By default, the command executes \f5DOWNLOAD_THROUGHPUT\fR,
\f5UPLOAD_THROUGHPUT\fR and \f5LATENCY\fR tests. Tests to execute can be
overriden by using the \f5\-\-test\-type\fR flag. Each test uses the command
defaults or gcloud CLI configurations for performing the operations. This
command also provides a way to override these values via means of different
flags like \f5\-\-process\-count\fR, \f5\-\-thread\-count\fR,
\f5\-\-download\-type\fR, etc.

The command outputs a diagnostic report with sytem information like free memory,
available CPU, average CPU load per test, disk counter deltas and diagnostic
information specific to individual tests on successful completion.



.SH "EXAMPLES"

The following command runs the default diagnostic tests on
\f5\fImy\-bucket\fR\fR bucket:

.RS 2m
$ gcloud alpha storage diagnose gs://my\-bucket
.RE

The following command runs only UPLOAD_THROUGHPUT and DOWNLOAD_THROUGHPUT
diagnostic tests:

.RS 2m
$ gcloud alpha storage diagnose gs://my\-bucket \e
    \-\-test\-type=UPLOAD_THROUGHPUT,DOWNLOAD_THROUGHPUT
.RE

The following command runs the diagnostic tests using \f5\fI10\fR\fR objects of
\f5\fI1MiB\fR\fR size each with \f5\fI10\fR\fR threads and \f5\fI10\fR\fR
processes at max:

.RS 2m
$ gcloud alpha storage diagnose gs://my\-bucket \-\-no\-of\-objects=10 \e
    \-\-object\-size=1MiB \-\-process\-count=10 \-\-thread\-count=10
.RE

The following command can be used to bundle and export the diagnostic
information to a user defined \f5\fIPATH\fR\fR destination:

.RS 2m
$ gcloud alpha storage diagnose gs://my\-bucket \-\-export \e
    \-\-destination=<PATH>
.RE



.SH "POSITIONAL ARGUMENTS"

.RS 2m
.TP 2m
\fIURL\fR

Bucket URL to use for the diagnostic tests.


.RE
.sp

.SH "FLAGS"

.RS 2m
.TP 2m
\fB\-\-test\-type\fR=[\fITEST_TYPES\fR,...]

Tests to run as part of this diagnosis. Following tests are supported:

DIRECT_CONNECTIVITY: Run a test upload over the Direct Connectivity network path
and run other diagnostics if the upload fails.

DOWNLOAD_THROUGHPUT: Upload objects to the specified bucket and record the
number of bytes transferred per second.

UPLOAD_THROUGHPUT: Download objects from the specified bucket and record the
number of bytes transferred per second.

LATENCY: Write the objects, retrieve their metadata, read the objects, and
record latency of each operation.

\fITEST_TYPES\fR must be one of: \fBDIRECT_CONNECTIVITY\fR,
\fBDOWNLOAD_THROUGHPUT\fR, \fBLATENCY\fR, \fBUPLOAD_THROUGHPUT\fR.

.TP 2m
\fB\-\-download\-type\fR=\fIDOWNLOAD_TYPE\fR; default=<DownloadType.FILE: 'FILE'>

Download strategy to use for the DOWNLOAD_THROUGHPUT diagnostic test.

STREAMING: Downloads the file in memory, does not use parallelism.
\f5\-\-process\-count\fR and \f5\-\-thread\-count\fR flag values will be ignored
if provided.

SLICED: Performs a sliced download
(https://cloud.google.com/storage/docs/sliced\-object\-downloads) of objects to
a directory. Parallelism can be controlled via \f5\-\-process\-count\fR and
\f5\-\-thread\-count\fR flags.

FILE: Download objects as files. Parallelism can be controlled via
\f5\-\-process\-count\fR and \f5\-\-thread\-count\fR flags.

\fIDOWNLOAD_TYPE\fR must be one of: \fBFILE\fR, \fBSLICED\fR, \fBSTREAMING\fR.

.TP 2m
\fB\-\-logs\-path\fR=\fILOGS_PATH\fR

If the diagnostic supports writing logs, write the logs to this file location.

.TP 2m
\fB\-\-upload\-type\fR=\fIUPLOAD_TYPE\fR; default=<UploadType.FILE: 'FILE'>

Upload strategy to use for the \fIUPLOAD_THROUGHPUT\fR diagnostic test.

FILE: Uploads files to a bucket. Parallelism can be controlled via
\f5\-\-process\-count\fR and \f5\-\-thread\-count\fR flags.

PARALLEL_COMPOSITE: Uploads files using a parallel composite strategy
(https://cloud.google.com/storage/docs/parallel\-composite\-uploads).
Parallelism can be controlled via \f5\-\-process\-count\fR and
\f5\-\-thread\-count\fR flags.

STREAMING: Streams the data to the bucket, does not use parallelism.
\f5\-\-process\-count\fR and \f5\-\-thread\-count\fR flag values will be ignored
if provided.

\fIUPLOAD_TYPE\fR must be one of: \fBFILE\fR, \fBPARALLEL_COMPOSITE\fR,
\fBSTREAMING\fR.

.TP 2m
\fB\-\-process\-count\fR=\fIPROCESS_COUNT\fR

Number of processes at max to use for each diagnostic test.

.TP 2m
\fB\-\-thread\-count\fR=\fITHREAD_COUNT\fR

Number of threads at max to use for each diagnostic test.

.TP 2m

Object properties:


.RS 2m
.TP 2m
\fB\-\-object\-count\fR=\fIOBJECT_COUNT\fR

Number of objects to use for each diagnostic test.

This flag argument must be specified if any of the other arguments in this group
are specified.

.TP 2m

Object size properties:

Exactly one of these must be specified:


.RS 2m
.TP 2m
\fB\-\-object\-size\fR=\fIOBJECT_SIZE\fR

Object size to use for the diagnostic tests.

.TP 2m
\fB\-\-object\-sizes\fR=[\fIOBJECT_SIZES\fR,...]

List of object sizes to use for the tests. Sizes should be provided for each
object specified using \f5\-\-object\-count\fR flag.

.RE
.RE
.sp
.TP 2m

Export diagnostic bundle.


.RS 2m
.TP 2m
\fB\-\-export\fR

Generate and export a diagnostic bundle. The following information will be
bundled and exported into a gzipped tarball (.tar.gz):

.RS 2m
.IP "\(bu" 2m
Latest gcloud CLI logs.
.IP "\(bu" 2m
Output of running the \f5gcloud storage diagnose\fR command.
.IP "\(bu" 2m
Output of running the \f5gcloud info \-\-anonymize\fR command.
.RE
.sp

Note: This command generates a bundle containing system information like disk
counter detlas, CPU information and system configurations. Please exercise
caution while sharing.

This flag argument must be specified if any of the other arguments in this group
are specified.

.TP 2m
\fB\-\-destination\fR=\fIDESTINATION\fR

Destination file path where the diagnostic bundle will be exported.


.RE
.RE
.sp

.SH "GCLOUD WIDE FLAGS"

These flags are available to all commands: \-\-access\-token\-file, \-\-account,
\-\-billing\-project, \-\-configuration, \-\-flags\-file, \-\-flatten,
\-\-format, \-\-help, \-\-impersonate\-service\-account, \-\-log\-http,
\-\-project, \-\-quiet, \-\-trace\-token, \-\-user\-output\-enabled,
\-\-verbosity.

Run \fB$ gcloud help\fR for details.



.SH "NOTES"

This command is currently in alpha and might change without notice. If this
command fails with API permission errors despite specifying the correct project,
you might be trying to access an API with an invitation\-only early access
allowlist. This variant is also available:

.RS 2m
$ gcloud storage diagnose
.RE