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  }