mention log_output_level flag in istioctl help

[rittneje]

(This is used to request new product features, please visit https://discuss.istio.io for questions on using Istio)

Describe the feature request

istioctl supports a --log_output_level flag to control the logging level of its various components. This flag is very useful for troubleshooting when istioctl is misbehaving. However, it is not documented in istioctl -h or istioctl help.

Describe alternatives you've considered

n/a

Affected product area (please put an X in all that apply)

[ ] Docs
[x] Installation
[ ] Networking
[ ] Performance and Scalability
[ ] Extensions and Telemetry
[ ] Security
[ ] Test and Release
[x] User Experience
[ ] Developer Infrastructure

Affected features (please put an X in all that apply)

[ ] Multi Cluster
[ ] Virtual Machine
[ ] Multi Control Plane

Additional context

[howardjohn]

Does --log_output_level=all:debug not work? They SetOutputLevel overrides those?

[rittneje]

We can try that. However, that flag is not mentioned in the output from istioctl help.

[litong01]

@howardjohn @rittneje the --log_output_level=all:debug does work, it will make istioctl show a lot of information.

[rittneje]

Yes we were able to use it successfully. For this reason I've changed the request to instead document this flag.

[hanxiaop]

@rittneje The flag is not shown because it prints several lines with many scopes. See #22061. There's a command istioctl options that can see all of these global flags. I think the point may become that users are not awaring of using this command. Maybe adding a more detailed command could be better?

[rittneje]

@hanxiaop Personally, I don't understand why istioctl help arbitrarily prints some of the global flags (e.g., --context), and istioctl options prints the rest of them. Fundamentally, the documentation ought to be internally consistent, and put them all in a singular location.

In addition to that, istioctl help should definitely explicitly refer to istiotctl options. That is a fairly non-standard way to document flags (other than kubectl I don't know of any application that does that), so as it stands it is extremely unlikely that most developers will ever see that documentation. Also, to be frank, I don't understand what the motivation is for not simply including all flags under istioctl help, regardless of whether they are global.

I will also point out that currently istioctl help doesn't even mention options as a command.

Available Commands:
  admin          Manage control plane (istiod) configuration
  analyze        Analyze Istio configuration and print validation messages
  authz          (authz is experimental. Use `istioctl experimental authz`)
  bug-report     Cluster information and log capture support tool.
  completion     generate the autocompletion script for the specified shell
  dashboard      Access to Istio web UIs
  experimental   Experimental commands that may be modified or deprecated
  help           Help about any command
  install        Applies an Istio manifest, installing or reconfiguring Istio on a cluster.
  kube-inject    Inject Istio sidecar into Kubernetes pod resources
  manifest       Commands related to Istio manifests
  operator       Commands related to Istio operator controller.
  profile        Commands related to Istio configuration profiles
  proxy-config   Retrieve information about proxy configuration from Envoy [kube only]
  proxy-status   Retrieves the synchronization status of each Envoy in the mesh [kube only]
  tag            Command group used to interact with revision tags
  upgrade        Upgrade Istio control plane in-place
  validate       Validate Istio policy and rules files
  verify-install Verifies Istio Installation Status
  version        Prints out build version information

[zirain]

fixed by #38236.