Yoshi Yamaguchi

Appendix: Glossary and References

Originally published in Japanese at https://zenn.dev/ymotongpoo/books/go-ebpf-primer/viewer/99-glossary_references.

Glossary

This is a quick-reference glossary of terms that appear in this book. The parentheses after each term point to the chapter that introduces it. If you start reading from a Hurdle chapter and run into a term you don’t know, use this list to find your way back to the chapter where it first appears.

Computing basics

  • Bits and bytes: The smallest unit of information is a bit, which is 0 or 1, and 8 bits make a byte. One byte can represent 0 through 255 (Chapter 2).
  • Memory: A sequence of bytes, each with a numbered address. You read and write by number, not by name (Chapter 2).
  • Address: The serial number assigned to each cell of memory. It is just a number, usually written in hexadecimal (Chapter 2).
  • Hexadecimal: Number notation that starts with 0x. Two digits correspond to exactly one byte (Chapter 2).
  • Instructions and machine code: The smallest units of work a CPU can perform, and their representation as byte sequences. Instructions also live in memory and have addresses (Chapters 2 and 4).
  • PC (program counter): The register that holds the address of the next instruction to execute. Its formal name is RIP (Chapter 2).
  • Register: A fast storage location inside the CPU. amd64 has 16 general-purpose registers, each 64 bits wide (Chapter 2).
  • SP (stack pointer): The register that points to the top of the stack. Its formal name is RSP (Chapters 2 and 5).
  • Pointer: A variable whose value is an address (Chapter 2).
  • Field offset: The number of bytes from the start of a struct to a field. You can get it with unsafe.Offsetof (Chapter 2, Hurdle 3).
  • Padding: Unused bytes inserted into a struct to align its fields (Chapter 2).

The OS and the kernel

  • Kernel: The core of the OS. It handles hardware access, process isolation, and scheduling (Chapter 3).
  • Process: One running program’s worth of state. Processes are distinguished by PID and each has its own virtual address space (Chapter 3).
  • Virtual addresses and virtual memory: A private sequence of addresses prepared for each process. The kernel manages the mapping to physical memory (Chapter 3).
  • Text segment, data segment, heap, stack: The regions of an address space, used respectively for machine code, global variables, dynamic allocation, and the working area for function calls (Chapter 3).
  • User space and kernel space: A division based on CPU privilege levels. Applications run on the restricted side (user space) (Chapter 3).
  • System call: A request from user space to the kernel. It involves switching privilege levels (Chapter 3).
  • Thread: The unit of execution the kernel manages. Threads within a process share the address space but each has its own stack (Chapter 3).
  • ASLR: A security mechanism that randomizes the placement of the stack and heap on each launch (Chapter 3).
  • Escape analysis: The analysis the Go compiler performs to decide whether a value goes on the stack or the heap (Chapter 3).

Executables

  • Compiling and linking: The step that turns source code into machine code, and the step that combines the parts into a single executable and fixes the addresses (Chapter 4).
  • Static linking and dynamic linking: Embedding libraries into the executable, versus binding to shared libraries at run time (Chapter 4).
  • Disassembly: Turning machine-code byte sequences back into human-readable instruction notation. This is what go tool objdump does (Chapter 4).
  • Symbol table: The mapping from names to addresses. You can peek at it with go tool nm. It lives in the ELF .symtab (Chapter 4).
  • ELF and sections: The Linux executable format and its subdivisions (.text, .rodata, and so on) (Chapter 4).
  • .gopclntab: A Go-specific table that maps instruction addresses to function names and line numbers. It is used for stack traces on panic, and even -s -w does not remove it (Chapters 4 and 13).
  • DWARF: Debug information that records types, field offsets, and line numbers. It lives in the .debug_* sections and is removed by -w (Chapter 4, Hurdle 3).
  • Build info: A blob that records the Go version and the list of dependency modules. go version -m reads it (Chapter 4, Hurdle 3).
  • Page: The fixed-size unit (usually 4KB) that the virtual memory mapping tables manage. Loading into and swapping out of physical memory happens page by page (Chapter 4).
  • Copy-on-write: The kernel mechanism that, when a read-only shared page needs to be modified, makes a private copy for that process and repoints the mapping table at it (Chapters 4 and 7).

Function calls

  • Stack frame: The working area pushed onto the stack for each individual function call (Chapter 5).
  • Return address: The “address of the instruction after the call” that CALL pushes onto the stack. RET pops it and jumps there (Chapter 5, Hurdle 1).
  • Calling convention: The agreement on where arguments and return values go. There is stack-based and register-based argument passing (Chapter 5, Hurdle 2).
  • Inlining: A compiler optimization that replaces a call to a small function with its body. The CALL disappears entirely (Chapter 5).
  • //go:noinline: A compiler directive that forbids inlining. This book uses it in experiments to keep the observation target in place (Chapter 5).

The Go runtime

  • Runtime: The execution support machinery bundled into every Go binary. It does its own scheduling and memory management (Chapter 6).
  • goroutine: The unit of execution the Go runtime manages. The kernel cannot see it (Chapter 6).
  • g, m, p: Runtime-internal structs representing a goroutine, an OS thread, and the resources needed to run Go code, respectively (Chapter 6).
  • Movable stack: The property that a goroutine’s stack relocates to a different region when it grows (Chapter 6, Hurdle 1).
  • ABIInternal: Go’s internal calling convention since Go 1.17. It passes arguments in registers (Hurdle 2).
  • R14: The register that, on amd64, always points to the current goroutine’s g struct (Hurdle 2).

eBPF and OBI

  • eBPF: The Linux mechanism for safely running small user-written programs inside the kernel (Chapter 7).
  • Verifier: The mechanism that statically analyzes an eBPF program before loading and guarantees termination and memory safety (Chapter 7).
  • Map: A kernel-managed key-value store shared between eBPF programs and user space (Chapter 7).
  • uprobe and uretprobe: A hook placed by swapping one byte at an instruction address for a breakpoint instruction, and a mechanism that rewrites the return address on the stack at function entry to catch the return (Chapter 7, Hurdle 1).
  • Trampoline: The kernel-side code that a uretprobe uses as the rewritten return address’s destination (Hurdle 1).
  • cilium/ebpf: The de facto Go library for loading and attaching eBPF programs (Chapter 7).
  • Ring buffer: A shared buffer for passing events from the kernel to user space (Chapter 8).
  • OBI: OpenTelemetry eBPF Instrumentation. An eBPF auto-instrumentation tool descended from Beyla (Chapter 8).
  • Zero-code instrumentation: Adding observation points from the outside without changing the application’s code (Chapter 1).
  • Protocol-level instrumentation: A language-independent instrumentation path that interprets the bytes flowing through a socket as a protocol (Chapter 8).
  • offsets.json: OBI’s table of field offsets per version of Go and of libraries (Hurdle 3).
  • bpf_probe_write_user: The eBPF helper that rewrites user-space memory in the target process (Hurdle 4).

Distributed tracing

  • Instrumentation: Adding observation points to record processing times and call relationships (Chapter 1).
  • Distributed trace, trace ID, span: The record of a single operation spanning multiple services, its identifier, and one segment of it (Chapter 1).
  • traceparent: The W3C standard header that carries the trace ID and span ID over HTTP (Chapter 1, Hurdle 4).
  • Backend: The server that collects and displays telemetry records (Chapter 1).
  • Context propagation: Carrying trace identification across process and service boundaries (Hurdle 4).
  • OTLP: OpenTelemetry’s standard telemetry transport protocol (Chapter 8).

References

OBI

The source locations cited in this book are as follows.

TopicFile
Searching for RET instructionspkg/internal/goexec/instructions_amd64.go
ELF parsing and locating moduledatapkg/internal/goexec/instructions.go
Attaching uprobespkg/ebpf/instrumenter.go
Macros for argument registers and the g pointerbpf/bpfcore/utils.h
goroutine identifiersbpf/common/go_addr_key.h
Parent-child tracking of goroutinesbpf/gotracer/go_runtime.c, bpf/gotracer/go_common.h
Header injectionbpf/gotracer/go_nethttp.c
Offset resolution and reading build infopkg/internal/goexec/structmembers.go, pkg/internal/goexec/gofile.go
Offset tablepkg/internal/goexec/offsets.json
List of instrumented symbolspkg/internal/ebpf/gotracer/gotracer.go

Upstream Go

eBPF

Talk

The program output in this book was captured on go1.26.5 linux/amd64 and includes values, such as addresses, that change from run to run. The OBI code is as of release v0.11.0 (August 17, 2026). Values such as register assignments, field offsets, and nesting limits can change with the Go version or the OBI release. When you cite implementation details, double-check them against the source for the version you are targeting.