bpfcc/dist/index.d.ts

Frontend / bindings for BPF Compiler Collection (BCC)

import { MapType, ProgramType, MapRef, TypeConversion, RawMap, ConvMap, RawArrayMap, ConvArrayMap, RawQueueMap, ConvQueueMap } from 'bpf';
import { FD } from './util';
export { Code, BCCError } from './exception';
export interface USDT {
    pid?: number;
    binaryPath?: string;
    provider: string;
    name: string;
    probeFunc: string;
    /**
     * When the kludge flag is set to 1 (default), we will only match on inode
     * when searching for modules in /proc/PID/maps that might contain the
     * tracepoint we're looking for.
     * By setting this to 0, we will match on both inode and
     * (dev_major, dev_minor), which is a more accurate way to uniquely
     * identify a file, but may fail depending on the filesystem backing the
     * target file (see bcc#2715)
     *
     * This hack exists because btrfs and overlayfs report different device
     * numbers for files in /proc/PID/maps vs stat syscall. Don't use it unless
     * you've had issues with inode collisions. Both btrfs and overlayfs are
     * known to require inode-only resolution to accurately match a file.
     *
     * set_probe_matching_kludge(0) must be called before USDTs are submitted to
     * BPF::init()
     */
    matchingKludge?: number;
}
export declare enum ProbeAttachType {
    ENTRY = 0,
    RETURN = 1
}
export interface Options {
    /** Module flags */
    flags?: number;
    rwEngineEnabled?: boolean;
    /** Map namespace */
    mapsNamespace?: string;
    allowRlimit?: boolean;
    /** Compilation flags */
    cflags?: string[];
    /** USDT probe definitions */
    usdt?: USDT[];
    /** Call [[autoload]] after loading the source (default: true) */
    autoload?: boolean;
}
export declare const defaultOptions: Options;
/**
 * Description of an eBPF map from BCC
 * Should be compatible with `bpf.MapDesc`.
 */
export interface TableDesc {
    name: string;
    fd: number;
    type: MapType;
    keySize: number;
    valueSize: number;
    maxEntries: number;
    /**
     * Flags specified on map creation, see
     * [MapFlags](https://bpf.alba.sh/docs/enums/mapflags.html)
     */
    flags: number;
}
export interface BCCMapRef extends MapRef {
    /** Program to which this module belongs */
    bpf: BPFModule;
}
/**
 * Compile a program and load it into the kernel.
 *
 * **Note:** This is a heavy operation, use [[load]]
 * to avoid blocking the event loop.
 *
 * @param program C code to compile
 * @param options Additional options
 * @returns Loaded program instance
 */
export declare function loadSync(program: string, options?: Options): BPFModule;
/**
 * Compile a program and load it into the kernel.
 *
 * @param program C code to compile
 * @param options Additional options
 * @returns Promise for loaded program instance
 */
export declare function load(program: string, options?: Options): Promise<BPFModule>;
export declare class BPFModule {
    private _bpf;
    private constructor();
    /**
     * Detach all functions & events.
     *
     * @category Event attaching
     */
    detachAll(): void;
    /**
     * @category Event attaching
     */
    attachKprobe(kernelFunc: string, probeFunc: string, options?: {
        kernelFuncOffset?: bigint;
        attachType?: ProbeAttachType;
        maxActive?: number;
    }): void;
    /**
     * @category Event attaching
     */
    detachKprobe(kernelFunc: string, options?: {
        attachType?: ProbeAttachType;
    }): void;
    /**
     * @category Event attaching
     */
    attachUprobe(binaryPath: string, symbol: string, probeFunc: string, options?: {
        symbolAddr?: bigint;
        attachType?: ProbeAttachType;
        pid?: number;
        symbolOffset?: bigint;
    }): void;
    /**
     * @category Event attaching
     */
    detachUprobe(binaryPath: string, symbol: string, options?: {
        symbolAddr?: bigint;
        attachType?: ProbeAttachType;
        pid?: number;
        symbolOffset?: bigint;
    }): void;
    /**
     * Convenience method, see [[attachKprobe]].
     *
     * @category Event attaching
     */
    attachKretprobe(kernelFunc: string, probeFunc: string, options?: {
        kernelFuncOffset?: bigint;
        attachType?: ProbeAttachType;
        maxActive?: number;
    }): void;
    /**
     * Convenience method, see [[detachKprobe]].
     *
     * @category Event attaching
     */
    detachKretprobe(kernelFunc: string): void;
    /**
     * Convenience method, see [[attachUprobe]].
     *
     * @category Event attaching
     */
    attachUretprobe(binaryPath: string, symbol: string, probeFunc: string, options?: {
        symbolAddr?: bigint;
        attachType?: ProbeAttachType;
        pid?: number;
        symbolOffset?: bigint;
    }): void;
    /**
     * Convenience method, see [[detachUprobe]].
     *
     * @category Event attaching
     */
    detachUretprobe(binaryPath: string, symbol: string, options?: {
        symbolAddr?: bigint;
        attachType?: ProbeAttachType;
        pid?: number;
        symbolOffset?: bigint;
    }): void;
    /**
     * @category Event attaching
     */
    attachUsdt(usdt: USDT, options?: {
        pid?: number;
    }): void;
    /**
     * @category Event attaching
     */
    /**
     * @category Event attaching
     */
    detachUsdt(usdt: USDT, options?: {
        pid?: number;
    }): void;
    /**
     * @category Event attaching
     */
    /**
     * @category Event attaching
     */
    attachTracepoint(tracepoint: string, probeFunc: string): void;
    /**
     * @category Event attaching
     */
    detachTracepoint(tracepoint: string): void;
    /**
     * @category Event attaching
     */
    /**
     * @category Event attaching
     */
    /**
     * @category Event attaching
     */
    attachPerfEvent(evType: number, evConfig: number, probeFunc: string, samplePeriod: bigint, sampleFreq: bigint, options?: {
        pid?: number;
        cpu?: number;
        groupFd?: number;
    }): void;
    /**
     * @category Event attaching
     */
    detachPerfEvent(evType: number, evConfig: number): void;
    getSyscallFnName(name: string): string;
    addModule(module: string): void;
    openPerfEvent(name: string, type: number, config: bigint): void;
    closePerfEvent(name: string): void;
    loadFunction(funcName: string, type: ProgramType): FD;
    unloadFunction(funcName: string): void;
    freeBccMemory(): void;
    /**
     * Retrieves all registered eBPF maps on this program
     * and their information, as a `(path, tableDesc)` dictionary.
     * See [[TableDesc]].
     */
    get maps(): Map<string, TableDesc>;
    /**
     * Find the information of a map by name.
     * Returns undefined if the map is not found.
     *
     * @param name Map name
     * @category Module info
     */
    findMap(name: string): TableDesc | undefined;
    /**
     * Retrieves all declared functions
     */
    get functions(): string[];
    /**
     * Automatically load and attach functions beginning with
     * special prefixes (`kprobe__`, `tracepoint__`, etc.).
     *
     * By default, this is automatically called by [[load]] or [[loadSync]].
     */
    autoload(): void;
    /**
     * Creates and returns a custom
     * [MapRef](https://bpf.alba.sh/docs/interfaces/mapref.html)
     * reference to the given map.
     *
     * The reference doesn't support closing the FD, and
     * keeps the full BPF program alive for convenience.
     *
     * @param name Map name
     * @category Map access
     */
    getMapRef(name: string): BCCMapRef;
    /**
     * Creates and returns a
     * [RawMap](https://bpf.alba.sh/docs/classes/rawmap.html)
     * instance to manipulate the given map.
     *
     * @param name Map name
     * @category Map access
     */
    getRawMap(name: string): RawMap;
    /**
     * Creates and returns a generic
     * [IMap](https://bpf.alba.sh/docs/interfaces/imap.html)
     * instance to manipulate the given map, using
     * the given
     * [conversions](https://bpf.alba.sh/docs/interfaces/typeconversion.html)
     * for keys and values.
     *
     * @param name Map name
     * @category Map access
     */
    getMap<K, V>(name: string, keyConv: TypeConversion<K>, valueConv: TypeConversion<V>): ConvMap<K, V>;
    /**
     * Creates and returns a
     * [RawArrayMap](https://bpf.alba.sh/docs/classes/rawarraymap.html)
     * instance to manipulate the given array map.
     *
     * @param name Map name
     * @category Map access
     */
    getRawArrayMap(name: string): RawArrayMap;
    /**
     * Creates and returns a generic
     * [IArrayMap](https://bpf.alba.sh/docs/interfaces/iarraymap.html)
     * instance to manipulate the given array map, using
     * the given
     * [conversion](https://bpf.alba.sh/docs/interfaces/typeconversion.html)
     * for values.
     *
     * @param name Map name
     * @category Map access
     */
    getArrayMap<V>(name: string, valueConv: TypeConversion<V>): ConvArrayMap<V>;
    /**
     * Creates and returns a
     * [RawQueueMap](https://bpf.alba.sh/docs/classes/rawqueuemap.html)
     * instance to manipulate the given queue or stack map.
     *
     * @param name Map name
     * @category Map access
     */
    getRawQueueMap(name: string): RawQueueMap;
    /**
     * Creates and returns a generic
     * [IQueueMap](https://bpf.alba.sh/docs/interfaces/iqueuemap.html)
     * instance to manipulate the given queue or stack map, using
     * the given
     * [conversion](https://bpf.alba.sh/docs/interfaces/typeconversion.html)
     * for values.
     *
     * @param name Map name
     * @category Map access
     */
    getQueueMap<V>(name: string, valueConv: TypeConversion<V>): ConvQueueMap<V>;
}