Skip to content

build: update debug build to add EBPF #215

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
chuck-bear wants to merge 1 commit into
base: main
Choose a base branch
from
Open

build: update debug build to add EBPF #215

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 19 additions & 2 deletions Dockerfile.debug
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,11 @@ COPY --from=planner /app/recipe.json recipe.json
ARG BUILD_PROFILE=release
ENV BUILD_PROFILE=$BUILD_PROFILE

# Build flags for profiling-friendly binaries.
# Defaults enable call-stack unwinding and symbol data for better eBPF flamegraphs.
ARG RUSTFLAGS="-C force-frame-pointers=yes -C debuginfo=1 -C symbol-mangling-version=v0"
Comment on lines +22 to +23
Copy link

Copilot AI Feb 17, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The RUSTFLAGS default enables frame pointers and debug info for all builds using Dockerfile.debug, including the standard docker-build-debug target. These flags increase binary size and may impact performance. If the intention is to only enable these for profiling builds, consider making RUSTFLAGS conditional via a build argument, or use empty defaults and only set these flags via --build-arg in the docker-build-debug-profiling target.

Suggested change
# Defaults enable call-stack unwinding and symbol data for better eBPF flamegraphs.
ARG RUSTFLAGS="-C force-frame-pointers=yes -C debuginfo=1 -C symbol-mangling-version=v0"
# Override via --build-arg RUSTFLAGS="..." in profiling builds (default is empty).
ARG RUSTFLAGS=""

Copilot uses AI. Check for mistakes.
Copy link
Contributor

@fridrik01 fridrik01 Feb 18, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this is valid, RUSTFLAGS should be empty by default and only specified via --build-arg in the docker-build-debug-profiling make target

ENV RUSTFLAGS=$RUSTFLAGS

# Builds dependencies with debug profile (faster linking, keeps symbols)
RUN cargo chef cook --profile $BUILD_PROFILE --recipe-path recipe.json

Expand All @@ -31,9 +36,20 @@ RUN cp /app/target/release/bera-reth /app/bera-reth
# Use Ubuntu as the release image
FROM ubuntu:24.04 AS runtime

# Install runtime dependencies
# Install runtime dependencies and eBPF observability tooling.
# Note: eBPF tooling requires extra container privileges at runtime
# (for example: --privileged, or CAP_BPF + CAP_PERFMON + CAP_SYS_ADMIN,
# and usually --pid=host with host /sys mounted).
RUN apt-get update && \
apt-get install -y ca-certificates libssl-dev && \
apt-get install -y \
ca-certificates \
libssl-dev \
linux-tools-common \
Copy link

Copilot AI Feb 17, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The package "linux-tools-common" is a meta-package that typically requires kernel-specific versions (like linux-tools-generic or linux-tools-$(uname -r)) to actually provide the perf binary. Installing only linux-tools-common may not provide the actual perf tool needed for eBPF profiling. Consider adding "linux-tools-generic" or documenting that the image must be run with host kernel tools mounted.

Suggested change
linux-tools-common \
linux-tools-common \
linux-tools-generic \

Copilot uses AI. Check for mistakes.
bpftrace \
bpfcc-tools \
procps \
psmisc \
strace && \
Comment on lines +47 to +52
Copy link

Copilot AI Feb 17, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The eBPF tooling packages (bpftrace, bpfcc-tools, linux-tools-common, strace) are now installed in all debug builds, even when using the docker-build-debug target without the -profiling suffix. These tools significantly increase image size and attack surface. Consider using multi-stage builds or build arguments to conditionally install these tools only for the debug-profiling variant, or create a separate Dockerfile.debug-profiling that extends from the base debug image and adds only the eBPF tools.

Copilot uses AI. Check for mistakes.
rm -rf /var/lib/apt/lists/*

# Copy bera-reth over from the build stage
Expand All @@ -49,5 +65,6 @@ EXPOSE 30303 30303/udp 9001 8545 8546 8551
# Set environment to show we're in debug mode
ENV RUST_LOG=debug
ENV BUILD_TYPE=release
ENV BPFTRACE_CACHE_USER_SYMBOLS=1

Comment on lines +68 to 69
Copy link

Copilot AI Feb 17, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The BPFTRACE_CACHE_USER_SYMBOLS environment variable is set to 1 for all debug builds, but the caching behavior may not be desirable in all debugging scenarios. This could cause stale symbol information if the binary is rebuilt or replaced during development. Consider documenting this setting or making it configurable through a build argument, especially since the base debug image now includes this even when not using profiling features.

Suggested change
ENV BPFTRACE_CACHE_USER_SYMBOLS=1
# Control bpftrace user symbol caching. Default is enabled (1) for performance.
# Override at build time with: --build-arg BPFTRACE_CACHE_USER_SYMBOLS=0
ARG BPFTRACE_CACHE_USER_SYMBOLS=1
ENV BPFTRACE_CACHE_USER_SYMBOLS=${BPFTRACE_CACHE_USER_SYMBOLS}

Copilot uses AI. Check for mistakes.
ENTRYPOINT ["/usr/local/bin/bera-reth"]
11 changes: 11 additions & 0 deletions Makefile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -50,6 +50,17 @@ docker-build-debug: ## Fast debug build using Docker multistage (no cross-compil
docker build --file Dockerfile.debug --tag $(DOCKER_IMAGE_NAME):debug \
--build-arg COMMIT=$(GIT_SHA) \
--build-arg VERSION=$(GIT_TAG) \
--build-arg BUILD_PROFILE=$(PROFILE) \
.

.PHONY: docker-build-debug-profiling
docker-build-debug-profiling: ## Build profiling-friendly debug image (frame pointers + debuginfo) for flamegraphs.
Copy link

Copilot AI Feb 17, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The new docker-build-debug-profiling target and the eBPF tooling additions are not documented in the README or visible documentation. Consider adding documentation about when to use the profiling-enabled debug image versus the standard debug image, including the required runtime privileges mentioned in the Dockerfile comments (--privileged or specific capabilities).

Suggested change
docker-build-debug-profiling: ## Build profiling-friendly debug image (frame pointers + debuginfo) for flamegraphs.
docker-build-debug-profiling: ## Build profiling-oriented debug image (frame pointers + debuginfo) for CPU profiling/eBPF flamegraphs.
# Use this target instead of `docker-build-debug` when you need high-fidelity profiling data,
# such as when generating flamegraphs or using eBPF-based profilers from inside the container.
# When running the resulting image with eBPF tooling, the container usually must be started
# with `--privileged` or with the necessary capabilities (e.g., perf/eBPF and related system
# capabilities) granted explicitly, depending on your Docker and host configuration.

Copilot uses AI. Check for mistakes.
@echo "Building profiling debug Docker image..."
docker build --file Dockerfile.debug --tag $(DOCKER_IMAGE_NAME):debug-profiling \
--build-arg COMMIT=$(GIT_SHA) \
--build-arg VERSION=$(GIT_TAG) \
--build-arg BUILD_PROFILE=$(PROFILE) \
--build-arg RUSTFLAGS="-C force-frame-pointers=yes -C debuginfo=1 -C symbol-mangling-version=v0" \
Copy link

Copilot AI Feb 17, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The RUSTFLAGS argument in the new docker-build-debug-profiling target duplicates the same default value already set in Dockerfile.debug (line 23). This creates maintenance burden as the flags would need to be updated in two places. Consider removing the --build-arg RUSTFLAGS line here to rely on the Dockerfile default, or document why this explicit override is necessary when the values are identical.

Suggested change
--build-arg RUSTFLAGS="-C force-frame-pointers=yes -C debuginfo=1 -C symbol-mangling-version=v0" \

Copilot uses AI. Check for mistakes.
.

.PHONY: docker-build-push-nightly
Expand Down
Loading