-
Notifications
You must be signed in to change notification settings - Fork 185
/
interface.go
175 lines (145 loc) · 6.8 KB
/
interface.go
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
// Copyright 2022-2023 The Inspektor Gadget authors
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
package gadgets
import (
"github.com/inspektor-gadget/inspektor-gadget/pkg/params"
"github.com/inspektor-gadget/inspektor-gadget/pkg/parser"
)
// GadgetType defines how a gadget is actually run
type GadgetType string
const (
TypeUnknown GadgetType = ""
TypeTrace GadgetType = "trace" // Normal trace gadgets
TypeTraceIntervals GadgetType = "traceIntervals" // top gadgets expecting arrays of events
TypeOneShot GadgetType = "oneShot" // Gadgets that only fetch results
TypeProfile GadgetType = "profile" // Gadgets that run until the user stops, or it times out and then shows results
TypeRun GadgetType = "run" // This is a special type only used by the run command
TypeOther GadgetType = "other"
)
func (t GadgetType) CanSort() bool {
return t == TypeOneShot || t == TypeTraceIntervals
}
func (t GadgetType) IsPeriodic() bool {
return t == TypeTraceIntervals
}
// GadgetDesc is the main interface for handling gadgets
type GadgetDesc interface {
// Name provides the name of the gadget. This is used for the calling the gadget, auto-creating the cobra commands,
// logging, etc.
Name() string
// Description provides a short description of the gadget. This is used for a quick help in cobra, help,
// web-interface etc.
Description() string
// Category is used for cobra sub-commands and categories on the web interface.
Category() string
// Type is used to differentiate between how gadgets are run. The type essentially controls the workflow of the
// gadget.
Type() GadgetType
// ParamDescs returns a map of configuration parameters. These hold also default values, descriptions, validators and
// so on. Used whenever a gadget is called somehow. Auto-creates parameters for cobra as well.
ParamDescs() params.ParamDescs
// Parser returns a parser.Parser instance that can handle events and do certain operations on them
// (sorting, filtering, etc.) without the caller needing to know about the underlying types.
Parser() parser.Parser
// EventPrototype returns a blank event. Useful for checking for interfaces on it (see operators).
EventPrototype() any
}
// Optional extensions to GadgetDesc
// GadgetDescSkipParams / SkipParams() can define params that a gadget, runtime or operators never can use in
// combination with this gadget. Currently, this is used to not allow to specify for example a container name
// when the gadget is working inside the kubernetes environment and using the netns (as results could be ambiguous in
// that case).
type GadgetDescSkipParams interface {
SkipParams() []params.ValueHint
}
type OutputFormats map[string]OutputFormat
// OutputFormat can hold alternative output formats for a gadget. Whenever
// such a format is used, the result of the gadget will be passed to the Transform()
// function and returned to the user.
type OutputFormat struct {
Name string `json:"name"`
Description string `json:"description"`
RequiresCombinedResult bool `json:"requiresCombinedResult"`
Transform func(any) ([]byte, error) `json:"-"`
}
// Append appends the OutputFormats given in other to of
func (of OutputFormats) Append(other OutputFormats) {
for k, v := range other {
of[k] = v
}
}
// GadgetOutputFormats can be implemented together with the gadget interface
// to register alternative output formats that are used in combination with
// the GadgetResult interface. The defaultFormatKey MUST match the key of
// an entry in the supportedFormats map
type GadgetOutputFormats interface {
OutputFormats() (supportedFormats OutputFormats, defaultFormatKey string)
}
type EventHandlerSetter interface {
SetEventHandler(handler any)
}
type EventHandlerArraySetter interface {
SetEventHandlerArray(handler any)
}
type EventEnricherSetter interface {
SetEventEnricher(func(ev any) error)
}
// RunGadget is an interface that will be implemented by gadgets that are run in
// the background and emit events as soon as they occur.
type RunGadget interface {
// Run is expected to run the gadget and emits the events using the
// EventHandler. This function is expected to be blocking and return only
// when the context is done, after which the gadget should clean up all
// resources. Notice that this function will be called after operators are
// installed.
Run(GadgetContext) error
}
// RunWithResultGadget is an alternative to RunGadget that returns the result
// of the gadget only at the end of its execution.
type RunWithResultGadget interface {
// RunWithResult follows the same rules as Run() but instead of using an
// EventHandler to emit the events, it returns the result of the gadget as a
// byte array after the context is done.
RunWithResult(GadgetContext) ([]byte, error)
}
// InitCloseGadget is an optional interface that can be implemented by gadgets
// that needs to be initialized before the operators are installed. An example
// of this is when the gadget needs to be kept up-to-date with the containers
// that need to be traced, as the operators will start sending notifications of
// this as soon as it is installed. So, the gadget needs to be initialized and
// ready to receive those notifications before the operators are installed.
type InitCloseGadget interface {
// Init is expected to initialize the gadget. It will be called right before
// the operators are installed, and also before Run() is called (which is
// done after the operators are installed, see the Gadget interface).
Init(GadgetContext) error
// Close is expected to clean up all the resources allocated by the gadget.
// It will be called after Run() returns and after the operators have been
// uninstalled.
// TODO: We should pass the gadget context to Close().
Close()
}
type Gadget any
// GadgetInstantiate is the same interface as Gadget but adds one call to instantiate an actual
// tracer
type GadgetInstantiate interface {
GadgetDesc
// NewInstance creates a new gadget and returns it; the tracer should be allocated and configured but
// should not run any code that depends on cleanup
NewInstance() (Gadget, error)
}
// GadgetExperimental allows to mark a gadget as experimental.
type GadgetExperimental interface {
Experimental() bool
}