[DISCUSS] Simplfied sensuctl resource list output?

[calebhailey]

Feature Suggestion

One of my favorite features in Sensu Go is the new sensuctl CLI utility. It's a natural fit alongside the other modern ops tools in my workflow (e.g. kubectl, docker, etc). Having said that, the more complex my Sensu Go deployments become, the more cumbersome the sensuctl <resource> list views become (see screenshot, below).

So this got me thinking about workflows, and the way I use sensuctl. I think my most common workflow with sensuctl is to use a sensuctl <resource> list command to lookup a given resource (where the most important detail I need is the resource name). From there I usually run a sensuctl <resource> info <resource_name> command, optionally passing a --format yaml or --format json flag to get machine-parseable output (or to pipe/copy a resource template to a file where I can edit it for another use case).

Example

$ sensuctl entity list 
          ID            Class    OS                     Subscriptions                             Last Seen            
 ───────────────────── ─────── ─────── ─────────────────────────────────────────────── ─────────────────────────────── 
  i-0c9a17b8577c0077b   agent   linux   linux,system/linux,entity:i-0c9a17b8577c0077b   2020-04-04 12:36:57 -0700 PDT  
  i-0d2c011350692245e   agent   linux   linux,system/linux,entity:i-0d2c011350692245e   2020-04-04 12:37:07 -0700 PDT  

$ sensuctl entity info i-0c9a17b8577c0077b
=== i-0c9a17b8577c0077
Name:                   i-0c9a17b8577c0077b
Entity Class:           agent
Subscriptions:          linux, system/linux, entity:i-0c9a17b8577c0077b
Last Seen:              2020-04-04 12:34:37 -0700 PDT
Hostname:               ip-10-0-1-135.us-west-2.compute.internal
OS:                     linux
Platform:               centos
Platform Family:        rhel
Platform Version:       7.6.1810
Auto-Deregistration:    false
Deregistration Handler: 

$ sensuctl entity info i-0c9a17b8577c0077b --format yaml 
type: Entity
api_version: core/v2
metadata:
  name: i-0c9a17b8577c0077b
  namespace: us-west-2a
spec:
  deregister: false
  deregistration: {}
  entity_class: agent
  last_seen: 1586028937
  redact:
  - password
  - passwd
  - pass
  - api_key
  - api_token
  - access_key
  - secret_key
  - private_key
  - secret
  sensu_agent_version: 5.18.1
  subscriptions:
  - linux
  - system/linux
  - entity:i-0c9a17b8577c0077b
  system:
    arch: amd64
    cloud_provider: ""
    hostname: ip-10-0-1-135.us-west-2.compute.internal
    libc_type: ""
    network:
      interfaces:
      - addresses:
        - 127.0.0.1/8
        - ::1/128
        name: lo
      - addresses:
        - 10.0.1.135/24
        - 2600:1f14:8f6:ed01:1e60:c96d:12c:ce6/64
        - fe80::7:a0ff:fe1c:ba92/64
        mac: 02:07:a0:1c:ba:92
        name: eth0
    os: linux
    platform: centos
    platform_family: rhel
    platform_version: 7.6.1810
    vm_role: ""
    vm_system: ""
  user: agent

Entity list command output is less cumbersome than the check list command output (as shown in the earlier screenshot, above), but that also adds a degree of confusion. Is there any rhyme or reason to what resource attributes we show in these outputs? In some cases the sensuctl <resource> list command output is the same as the corresponding sensuctl <resource> info command output; in others the outputs differ with regards to the resource attributes that are displayed. And the JSON/YAML format output just show everything. This has got me asking myself the question: what is the purpose of these CLI features/functions?

I propose we adopt the following guidelines for sensuctl <resource> list and sensuctl <resource> info command outputs:

• sensuctl <resource> list: outputs resource names and (optionally) up to three primary/key attributes.

• sensuctl <resource> info <resource_name>: outputs the complete resource definition for a given resource name (i.e. type, api_version, metadata, and spec).

If this proposal successfully achieves its goal, it should help improve the consistency of sensuctl <resource> list and sensuctl <resource> info command outputs, and simplify the sensuctl UX – imagine if every sensuctl <resource> list command only displayed the most pertinent information (beginning with the resource names).

$ sensuctl check list 

NAME                                PUBLISH  INTERVAL  SUBSCRIPTIONS
check-banner                        false    30        system/linux,system/linux/network
check-checksums                     false    30        system/linux,system/linux/filesystem
check-cmd                           false    30        system/linux,system/linux/process
check-cpu                           false    30        system/linux,system/linux/cpu 
check-dir-count                     false    30        system/linux,system/linux/filesystem
check-json-whois-domain-expiration  false    30        system/linux,system/linux/network 

$ sensuctl entity list 
NAME                 CLASS  OS       SUBSCRIPTIONS
i-0c9a17b8577c0077b  agent  linux    system/linux,entity:i-0c9a17b8577c0077b
i-0d2c011350692245e  agent  windows  system/windows,entity:i-0d2c011350692245e
sensu.io             proxy  

$ sensuctl handler list 
NAME           TYPE    MUTATOR
alert          set
elasticsearch  pipe
pagerduty      pipe
servicenow     pipe
slack          pipe
splunk         socket  event-enrichment

😍

It should also make contributions easier to reason about by reducing the number of decisions to make – not every new feature or resource attribute needs to be added to list views! List command output will only require resource names and up to three key attributes (e.g. for checks those key attributes might be publish, interval, and subscriptions); is a new check feature/attribute more important to show in a list view than the publish/interval/subscriptions attributes ??? (HINT: probably not). And since info command output should include everything, should we even need to update the output function(s) when we add new attributes?

NOTE: we may need to implement support for redacting certain attribute values in sensuctl <resource> info command output.

Possible Implementation

TBD, but I suspect that this could help simplify the sensuctl code, since it seems that there may be one-off functions in use between the different resources for sensuctl <resource> info --format tabular output (because it seems that only a certain subset of attributes are being output per resource)? Would "printing everything" make things easier here?

Context

Let's make sensuctl easier to use!

Related: let's update the layout/format of sensuctl command output!

[calebhailey]

Related: https://github.com/sensu/sensu-go/issues/2099

[calebhailey]

Related: #2902

[calebhailey]

Related: #2906

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.