github.com/inspektor-gadget/inspektor-gadget@v0.28.1/pkg/columns/doc.go (about)

     1  // Copyright 2022 The Inspektor Gadget authors
     2  //
     3  // Licensed under the Apache License, Version 2.0 (the "License");
     4  // you may not use this file except in compliance with the License.
     5  // You may obtain a copy of the License at
     6  //
     7  //     http://www.apache.org/licenses/LICENSE-2.0
     8  //
     9  // Unless required by applicable law or agreed to in writing, software
    10  // distributed under the License is distributed on an "AS IS" BASIS,
    11  // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    12  // See the License for the specific language governing permissions and
    13  // limitations under the License.
    14  
    15  /*
    16  Package columns is a library that helps to carry data structs in a more generic way using a combination of reflection and
    17  generics. It can work with any type of struct (and arrays of those), providing useful functions like sorting, grouping,
    18  filtering and printing. How columns are handled can be configured using tags along the struct definition. This keeps
    19  metadata and type data in the same place, avoiding extra and/or duplicated code and thereby the likelihood of typos/errors.
    20  
    21  Columns just has to be initialized by passing a prototype of the struct. Afterwards you can use all helper functions
    22  (sorting, grouping, etc.) on it.
    23  
    24  # How does it work?
    25  
    26  You simply add a "column" tag to members of the struct you want to handle, like so:
    27  
    28  	type Event struct {
    29  		Node  string `json:"node" column:"node,width:12,ellipsis:middle"`
    30  		PID   int    `json:"pid" column:"PID,hide,align:right,width:6"`
    31  		Comm  string `json:"comm" column:"Comm"`
    32  		Name  string `json:"name" column:"Name"`
    33  		Dummy string `json:"dummy"`
    34  		Time  int64  `json:"time" column:"Time,align:right,width:24,group:sum"`
    35  	}
    36  
    37  Let's briefly analyze:
    38  
    39    - All fields that have a column tag will be considered, that means the `Dummy` field will not be considered.
    40    - Each column tag starts with the name of the field. This name is case-insensitive (and an error will be thrown if
    41      multiple fields share the same name.)
    42    - Additional information on the fields are added as a comma separated list after the name of the column; key and value
    43      (if applicable) are separated by a colon (see `attributes` below)
    44  
    45  You initialize `Columns` by passing it the type of the struct you want to use, like so:
    46  
    47  	cols, err := columns.NewColumns[Event]()
    48  
    49  The parameter could be used for specific options, passing nil will use the defaults.
    50  
    51  # Attributes
    52  
    53  	| Attribute | Value(s)               | Description                                                                                                          |
    54  	|-----------|------------------------|----------------------------------------------------------------------------------------------------------------------|
    55  	| align     | left,right             | defines the alignment of the column (whitespace before or after the value)                                           |
    56  	| ellipsis  | none,left,right,middle | defines how situations of content exceeding the given space should be handled, eg: where to place the ellipsis ("…") |
    57  	| fixed     | none                   | defines that this column will have a fixed width, even when auto-scaling is enabled                                  |
    58  	| group     | sum                    | defines what should happen with the field whenever entries are grouped (see grouping)                                |
    59  	| hide      | none                   | specifies that this column is not to be considered by default                                                        |
    60  	| precision | int                    | specifies the precision of floats (number of decimals)                                                               |
    61  	| width     | int                    | defines the space allocated for the column                                                                           |
    62  
    63  # Virtual Columns or Custom Extractors
    64  
    65  Sometimes it's necessary to add columns on the fly or have special treatment when extracting values. This can be
    66  achieved by specifying a virtual column or custom extractors.
    67  
    68  Say that for example you have a struct with a (by default) not printable member `Foo` that you still want to output.
    69  
    70  	type Event struct {
    71  		Node  string `json:"node" column:"node,width:12,ellipsis:middle"`
    72  		Foo   []byte
    73  	}
    74  
    75  You can do that by adding a virtual column:
    76  
    77  	cols.AddColumn(columns.Attributes{
    78  		Name:  "foo",
    79  		Width: 14,
    80  	}, func(e *Event) any {
    81  		return string(e.Foo)
    82  	})
    83  
    84  This will convert the []byte to a string before printing it.
    85  
    86  You can also just override the default extractor like so:
    87  
    88  	cols.SetExtractor("node", func(a *Event) any {
    89  		return "Foobar"
    90  	})
    91  */
    92  package columns