github.com/inspektor-gadget/inspektor-gadget@v0.28.1/pkg/datasource/datasource.go (about) 1 // Copyright 2023-2024 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 package datasource 16 17 import ( 18 "encoding/binary" 19 "io" 20 21 "github.com/inspektor-gadget/inspektor-gadget/pkg/gadget-service/api" 22 "github.com/inspektor-gadget/inspektor-gadget/pkg/parser" 23 ) 24 25 type Type uint32 26 27 const ( 28 TypeUndefined Type = iota 29 TypeEvent 30 TypeMetrics 31 ) 32 33 type Data interface { 34 private() 35 SetSeq(uint32) 36 Raw() *api.GadgetData 37 } 38 39 func (d *data) SetSeq(seq uint32) { 40 d.Seq = seq 41 } 42 43 func (d *data) Raw() *api.GadgetData { 44 return (*api.GadgetData)(d) 45 } 46 47 // DataFunc is the callback that will be called for Data emitted by a DataSource. Data has to be consumed 48 // synchronously and may not be accessed after returning - make a copy if you need to hold on to Data. 49 type DataFunc func(DataSource, Data) error 50 51 // DataSource is an interface that represents a data source of a gadget. Usually, it represents a map in eBPF and some 52 // tooling around handling it in Go. An eBPF program can have multiple DataSources, each one representing a different 53 // map. 54 type DataSource interface { 55 // Name returns the name of the data source 56 Name() string 57 58 // Type returns the type of the data source 59 Type() Type 60 61 // AddStaticFields adds fields inside a container that has a fixed size; use it to directly map for example 62 // eBPF structs 63 AddStaticFields(totalSize uint32, fields []StaticField) (FieldAccessor, error) 64 65 // AddField adds a field as a new payload 66 AddField(fieldName string, options ...FieldOption) (FieldAccessor, error) 67 68 // NewData builds a new data structure that can be written to 69 NewData() Data 70 GetField(fieldName string) FieldAccessor 71 GetFieldsWithTag(tag ...string) []FieldAccessor 72 73 // EmitAndRelease sends data through the operator chain and releases it afterward; 74 // Data may not be used after calling this. This should only be used in the running phase of the gadget, not 75 // in the initialization phase. 76 EmitAndRelease(Data) error 77 78 // Release releases the memory of Data; Data may not be used after calling this 79 Release(Data) 80 81 // ReportLostData reports a number of lost data cases 82 ReportLostData(lostSampleCount uint64) 83 84 // Dump dumps the content of Data to a writer for debugging purposes 85 Dump(Data, io.Writer) 86 87 // Subscribe makes sure that events emitted from this DataSource are passed to DataFunc; subscribers will be 88 // sorted by priority and handed over data in that order (lower numbers = earlier). Subscriptions to 89 // DataSources should only happen in the initialization phase. Data sent to dataFn has to be consumed synchronously 90 // and must not be accessed after returning. 91 Subscribe(dataFn DataFunc, priority int) 92 93 Parser() (parser.Parser, error) 94 95 Fields() []*api.Field 96 97 Accessors(rootOnly bool) []FieldAccessor 98 99 IsRequested() bool 100 101 // ByteOrder returns a binary accessor using the byte order of the creator of the DataSource 102 ByteOrder() binary.ByteOrder 103 104 AddAnnotation(key, value string) 105 AddTag(tag string) 106 107 Annotations() map[string]string 108 Tags() []string 109 }