feat: Add RIE-based remote debugging infrastructure for bottlecap (#908)

https://datadoghq.atlassian.net/browse/SVLS-7833

Implements comprehensive remote debugging support for the bottlecap
Lambda
  extension using Docker and GDB/LLDB, enabling developers to debug the
  extension in a local Lambda-like environment.

  **Core Changes:**

  1. Build System Improvements:
- Fix DEBUG flag not being passed to Docker build in
compile_bottlecap.sh
- Add DEBUG build arg validation and normalization (defaults to release
mode)
- Dockerfile now conditionally builds release vs debug based on DEBUG
flag
- Add explicit [profile.dev] configuration in Cargo.toml with debug
symbols

  2. Extension Debugging Support:
- Add DD_DEBUG_WAIT_FOR_ATTACH environment variable to pause startup
     - Allows debugger attachment before extension initialization
     - Configurable wait period for comfortable debugger setup

  3. Local Testing Infrastructure (local_tests/bottlecap/):
- Custom Lambda Runtime Interface Emulator (RIE) binaries for arm64/x86
     - Dockerfile with debug tools (gdb, gdbserver, lldb, procps)
     - Extended Lambda timeout to 900s (15 min) for debugging sessions
     - Simple Python test handler for triggering invocations

  4. Developer Workflow Automation:
- Makefile with targets: build, start, attach, invoke, logs, status,
shell, stop
     - Support for both post-startup and startup debugging workflows
     - Port mappings: 9000 (Lambda) and 2345 (GDB remote)

  5. Documentation:
     - DEBUG_GUIDE.md
     - README.md
     - Examples for RustRover IDE configuration

  **Technical Details:**

- Fixes critical bug where DEBUG=0 was set in shell but never passed to
docker buildx
- Dockerfile now correctly uses ${BUILD_MODE} to select target/release
or target/debug
- Debug builds include full symbols (debuginfo=2, strip=false,
opt-level=0)
  - Container runs with --cap-add=SYS_PTRACE for gdbserver attachment
- Path mapping: /tmp/dd/bottlecap → local bottlecap/ for source
debugging

  **Usage:**

  ```bash
  # Build with debug symbols and start debugging
  make build
  make start
  make invoke              # Start extension (runs on-demand)
  make attach              # Attach gdbserver
  # Connect RustRover to localhost:2345

  # Or debug from initialization
  make start DEBUG_WAIT=15
  make invoke &
  make attach              # Within 15 seconds

This enables efficient local debugging of Lambda extension logic
including
initialization, event processing, telemetry handling, and flushing
behavior.

Author: litianningdatadog

.gitlab/scripts/compile_bottlecap.sh

@@ -31,6 +31,13 @@ else
     printf "Fips compile requested: ${FIPS}\n"
 fi
 
+if [ -z "$DEBUG" ] || [ "$DEBUG" != "1" ]; then
+    printf "[WARNING] No DEBUG provided or DEBUG != 1, defaulting to release mode\n"
+    DEBUG=0
+else
+    printf "Debug mode requested: ${DEBUG}\n"
+fi
+
 if [ "$ALPINE" = "0" ]; then
     COMPILE_IMAGE=Dockerfile.bottlecap.compile
 else
@@ -67,6 +74,7 @@ docker_build() {
         -f ./images/${file} \
         --build-arg PLATFORM=$PLATFORM \
         --build-arg FIPS="${FIPS}" \
+        --build-arg DEBUG="${DEBUG}" \
         . -o $BINARY_PATH
 
     # Copy the compiled binary to the target directory with the expected name

bottlecap/Cargo.toml

@@ -81,6 +81,11 @@ tempfile = "3.20"
 [[bin]]
 name = "bottlecap"
 
+[profile.dev]
+debug = true   # same as debuginfo=2 and no stripping
+strip = false
+opt-level = 0
+
 [profile.release]
 opt-level = "z"  # Optimize for size.
 lto = true

bottlecap/src/bin/bottlecap/main.rs

@@ -256,6 +256,17 @@ async fn main() -> anyhow::Result<()> {
     log_fips_status(&aws_config.region);
     let version_without_next = EXTENSION_VERSION.split('-').next().unwrap_or("NA");
     debug!("Starting Datadog Extension v{version_without_next}");
+
+    // Debug: Wait for debugger to attach if DD_DEBUG_WAIT_FOR_ATTACH is set
+    if let Ok(wait_secs) = env::var("DD_DEBUG_WAIT_FOR_ATTACH") {
+        if let Ok(secs) = wait_secs.parse::<u64>() {
+            debug!("DD_DEBUG_WAIT_FOR_ATTACH: Waiting {secs} seconds for debugger to attach...");
+            debug!("Connect your debugger to port 2345 now!");
+            tokio::time::sleep(tokio::time::Duration::from_secs(secs)).await;
+            debug!("DD_DEBUG_WAIT_FOR_ATTACH: Continuing execution...");
+        }
+    }
+
     prepare_client_provider()?;
     let client = create_reqwest_client_builder()
         .map_err(|e| anyhow::anyhow!("Failed to create client builder: {e:?}"))?

images/Dockerfile.bottlecap.compile

@@ -2,6 +2,7 @@ FROM public.ecr.aws/lambda/provided:al2 AS compiler
 ARG PLATFORM
 
 ARG FIPS
+ARG DEBUG
 
 # Install dependencies
 RUN --mount=type=cache,target=/var/cache/yum \
@@ -35,11 +36,18 @@ RUN --mount=type=cache,target=/usr/local/cargo/git \
     else \
         export FEATURES=default; \
     fi; \
+    if [ "${DEBUG}" = "0" ]; then \
+        export BUILD_MODE=release; \
+        export BUILD_FLAG="--release"; \
+    else \
+        export BUILD_MODE=debug; \
+        export BUILD_FLAG=""; \
+    fi; \
     # The `libddwaf` crate links against static objects that require `libclang_rt.builtins`, but
     # this is not presented to the linker by default on this platform, so we force it in.
     export RUSTFLAGS="${RUSTFLAGS:-} -Clinker=clang -L$(dirname $(clang --print-file-name="libclang_rt.builtins-$(uname -m).a")) -lclang_rt.builtins-$(uname -m)"; \
-    cargo +stable build --verbose --locked --no-default-features --features="${FEATURES}" --release && \
-    mkdir -p /tmp/out && cp "/tmp/dd/bottlecap/target/release/bottlecap" /tmp/out/bottlecap
+    cargo +stable build --verbose --locked --no-default-features --features="${FEATURES}" ${BUILD_FLAG} && \
+    mkdir -p /tmp/out && cp "/tmp/dd/bottlecap/target/${BUILD_MODE}/bottlecap" /tmp/out/bottlecap
 
 # Use smallest image possible
 FROM scratch

local_tests/bottlecap/DEBUG_GUIDE.md

@@ -0,0 +1,269 @@
+# Debugging Bottlecap Extension Guide
+
+This guide explains how to debug the bottlecap Lambda extension running in a local Docker container using RustRover (or any GDB-compatible debugger).
+
+## Overview
+
+The bottlecap extension is a Rust-based AWS Lambda extension. Unlike traditional processes that start when the container starts, Lambda extensions only initialize when Lambda is invoked for the first time.
+
+**Key Insight**: You must trigger at least one Lambda invocation (`make invoke`) before the extension process exists and can be debugged. The debugging sequence is: build → start → **invoke** → attach → debug.
+
+This guide covers two debugging approaches:
+
+1. **Post-Startup Debugging**: Attach after the extension has started (recommended for most cases)
+2. **Startup Debugging**: Debug from extension initialization using a wait period
+
+## Prerequisites
+
+- Docker running on your machine
+- RustRover or CLion IDE (or any GDB-compatible debugger)
+- The bottlecap extension built with debug symbols (`DEBUG=1`)
+- RIE binary: The setup uses a custom Lambda Runtime Interface Emulator.
+
+## Understanding Lambda Extension Lifecycle
+
+Lambda extensions are **on-demand processes** that behave differently from traditional Docker processes:
+
+1. **Container starts** (`make start`): The Lambda RIE starts, but the extension does NOT run yet
+2. **First invocation** (`make invoke`): Lambda initializes and starts the extension process
+3. **Extension registers**: The extension registers with Lambda Runtime API and enters its event loop
+4. **Ready for debugging**: Only now does the datadog-agent process exist and can be attached
+
+This means:
+- Running `docker ps` shows the container, but the extension process isn't visible yet
+- `make attach` will fail if no invocation has occurred
+- You must always invoke Lambda first to start the extension before debugging
+
+## Method 1: Post-Startup Debugging (Recommended)
+
+This approach lets you attach the debugger after the extension has started and is ready to process invocations.
+
+### Step 1: Build and Start the Container
+
+```bash
+cd local_tests/bottlecap
+
+# Build the extension with debug symbols
+make build
+
+# Start the container
+make start
+```
+
+### Step 2: Trigger First Invocation
+
+The extension only starts when Lambda is invoked for the first time:
+
+```bash
+# In one terminal, monitor logs
+make logs
+
+# In another terminal, trigger invocation
+make invoke
+```
+
+Watch the logs for:
+```
+DD_EXTENSION | DEBUG | Starting Datadog Extension v88
+DD_EXTENSION | DEBUG | Datadog Next-Gen Extension ready in 49ms
+```
+
+### Step 3: Attach the Debugger
+
+Once the extension is running, attach gdbserver:
+
+```bash
+make attach
+```
+
+You should see:
+```
+Attached; pid = 12
+Listening on port 2345
+```
+
+### Step 4: Connect RustRover
+
+1. In RustRover, go to **Run → Edit Configurations**
+2. Click **+** and select **Remote Debug**
+3. Configure:
+   - **Name**: `Bottlecap Remote Debug`
+   - **Target**: `localhost:2345`
+   - **Symbol file**: `<PROJECT_ROOT>/.binaries/bottlecap-arm64`
+   - Leave **Sysroot** empty
+4. Click **OK**
+
+5. Set breakpoints in your code (e.g., in `main.rs` or event handlers)
+
+6. Start debugging: **Run → Debug 'Bottlecap Remote Debug'**
+
+### Step 5: Trigger More Invocations
+
+With the debugger attached and breakpoints set, trigger Lambda invocations to hit your breakpoints:
+
+```bash
+# Trigger invocation
+make invoke
+
+# Or trigger multiple times
+for i in {1..5}; do make invoke; sleep 1; done
+```
+
+## Method 2: Startup Debugging
+
+This approach is useful when you need to debug the extension initialization code itself.
+
+### Step 1: Start with Debug Wait
+
+```bash
+cd local_tests/bottlecap
+
+# Build
+make build
+
+# Start with 15-second wait for debugger
+make start DEBUG_WAIT=15
+```
+
+This will display:
+```
+Container 'bottlecap-lambda' started. Use 'make logs' to view logs.
+Debug mode: Extension will wait 15 seconds for debugger on first invocation
+```
+
+### Step 2: Trigger Invocation to Start Extension
+
+```bash
+# In one terminal, watch logs
+make logs
+
+# In another terminal, trigger the first invocation
+# This starts the extension which will wait for 15 seconds
+make invoke &
+```
+
+Watch the logs for:
+```
+DD_EXTENSION | DEBUG | Starting Datadog Extension v88
+DD_EXTENSION | DEBUG | DD_DEBUG_WAIT_FOR_ATTACH: Waiting 15 seconds for debugger to attach...
+DD_EXTENSION | DEBUG | Connect your debugger to port 2345 now!
+```
+
+### Step 3: Quickly Attach and Connect
+
+You have 15 seconds to attach gdbserver and connect your debugger:
+
+```bash
+# Attach gdbserver (in a new terminal)
+make attach
+```
+
+Then immediately connect RustRover as described in Method 1, Step 4.
+
+### Step 4: Debug Initialization
+
+The extension is now paused during initialization. You can:
+- Step through the initialization code
+- Set breakpoints in event handlers
+- Continue execution to let the extension finish starting
+
+After the wait period expires, you'll see:
+```
+DD_EXTENSION | DEBUG | DD_DEBUG_WAIT_FOR_ATTACH: Continuing execution...
+```
+
+## Common Debugging Scenarios
+
+### Debug a Specific Invocation Handler
+
+1. Start container: `make start`
+2. Trigger first invocation to start extension: `make invoke`
+3. Attach debugger: `make attach`
+4. Set breakpoint in the handler (e.g., `main.rs:1143` in `handle_next_invocation`)
+5. Connect RustRover debugger
+6. Trigger another invocation: `make invoke`
+
+### Debug Telemetry Event Processing
+
+1. Start container: `make start DEBUG_WAIT=15`
+2. Trigger invocation to start extension: `make invoke &`
+3. Quickly attach: `make attach`
+4. Set breakpoints in `handle_event_bus_event` (main.rs:1020)
+5. Connect debugger
+6. Let execution continue - breakpoints will hit as telemetry events arrive
+
+### Debug Metrics/Logs/Traces Flushing
+
+1. Start container normally: `make start`
+2. Trigger invocation: `make invoke`
+3. Attach: `make attach`
+4. Set breakpoints in flushing code (main.rs:925 `blocking_flush_all`)
+5. Connect debugger
+6. Trigger more invocations to hit flush logic
+
+## Troubleshooting
+
+### "the input device is not a TTY" Error
+
+This happens when running `make attach` from a non-interactive shell. The command requires TTY for gdbserver interaction. Run from a normal terminal session.
+
+### Extension Process Not Found
+
+If `make attach` can't find the datadog-agent process:
+- Ensure you triggered at least one invocation: `make invoke`
+- Check logs: `make logs` - look for "Starting Datadog Extension"
+- Verify container is running: `make status`
+
+### Debugger Can't Connect to Port 2345
+
+- Check the container exposes port 2345: `docker ps` should show `0.0.0.0:2345->2345/tcp`
+- Verify gdbserver is listening: `make attach` should show "Listening on port 2345"
+- Check firewall settings
+
+### Extension Exits Immediately
+
+Lambda RIE may be shutting down the environment. Check:
+- Container logs: `make logs`
+- Ensure you're using the correct RIE binary
+- The container must use the RIE from `local_tests/rie/bottlecap/arm64/rie`
+
+### Timeout During Startup Debug Wait
+
+If 15 seconds isn't enough:
+- Increase the wait time: `make start DEBUG_WAIT=30`
+- Or skip startup debugging and use post-startup method
+
+### Lambda Invocation Times Out After 1 Second
+
+If you see "Task timed out after 1.00 seconds" when running `make invoke`:
+- **Root cause**: The `AWS_LAMBDA_FUNCTION_TIMEOUT` environment variable in the Dockerfile was set to 1 second
+- **Fix**: The Dockerfile has been updated to use 900 seconds (15 minutes) to allow comfortable debugging
+- **Verify**: Check `Dockerfile` line 7 shows `AWS_LAMBDA_FUNCTION_TIMEOUT=900`
+- **Why 15 minutes**: This is AWS Lambda's maximum timeout, giving you plenty of time to step through code, inspect variables, and debug complex logic without the invocation timing out
+
+## Key Code Locations for Breakpoints
+
+- **Extension main entry**: `bottlecap/src/bin/bottlecap/main.rs:251` (`main()`)
+- **Extension registration**: `main.rs:270` (`extension::register`)
+- **Event loop (OnDemand mode)**: `main.rs:697` (OnDemand loop)
+- **Invocation handling**: `main.rs:1143` (`handle_next_invocation`)
+- **Event processing**: `main.rs:1020` (`handle_event_bus_event`)
+- **Flushing**: `main.rs:925` (`blocking_flush_all`)
+
+## Additional Resources
+
+- [GDB Remote Debugging](https://sourceware.org/gdb/current/onlinedocs/gdb/Remote-Debugging.html)
+- [RustRover Remote Debug Guide](https://www.jetbrains.com/help/rust/remote-debug.html)
+- [AWS Lambda Extensions API](https://docs.aws.amazon.com/lambda/latest/dg/runtimes-extensions-api.html)
+
+## Clean Up
+
+When done debugging:
+
+```bash
+# Stop the container
+make stop
+
+# View help for other commands
+make help
+```

local_tests/bottlecap/Dockerfile

@@ -0,0 +1,46 @@
+FROM public.ecr.aws/lambda/python:3.9
+
+# Build argument for parent directory name
+ARG TARGET=bottlecap
+
+# Set to 900 (15 minutes) for debugging - Lambda max timeout
+ENV AWS_LAMBDA_FUNCTION_TIMEOUT=900
+ENV LOG_LEVEL=debug
+ENV DD_LOG_LEVEL=debug
+# Enforce flushing
+ENV DD_FLUSHING_STRATEGY=continuously,1
+
+
+# ---- Add remote dev tooling ----
+# SSH server, LLDB, GDB, procps (ps/top), curl, git
+RUN yum -y install lldb gdb gdb-gdbserver procps-ng tar gzip zip curl git shadow-utils sysvinit-tools\
+    &&  \
+    yum -y install \
+          fontconfig \
+          freetype \
+          libXrender \
+          libXext \
+          libXi \
+          libXtst \
+          libX11 \
+          alsa-lib \
+          which \
+    && yum clean all
+
+# Optional: install Rust toolchain (useful if you want to build inside the container)
+RUN curl https://sh.rustup.rs -sSf | bash -s -- -y
+ENV PATH=/root/.cargo/bin:$PATH
+
+
+# The first path is where the custom RIE lives.
+COPY local_tests/rie/${TARGET}/arm64/rie /usr/local/bin/aws-lambda-rie
+
+# The first path is the location of your local agent binary
+COPY .binaries/bottlecap-arm64 /opt/extensions/datadog-agent
+
+# Copy the lambda function to the container
+COPY local_tests/${TARGET}/index.py ${LAMBDA_TASK_ROOT}/
+
+CMD ["index.handler"]
+
+ENTRYPOINT ["/entrypoint.sh"]