docker/README.md
Official Docker images for BTrace - a safe, dynamic tracing tool for the Java platform.
# Copy BTrace into your application image
FROM btrace/btrace:2.3.0 AS btrace
FROM bellsoft/liberica-openjdk-debian:11-cds
COPY --from=btrace /opt/btrace /opt/btrace
ENV BTRACE_HOME=/opt/btrace PATH="${PATH}:/opt/btrace/bin"
# Your application...
btrace/btrace:latest (~25MB)Debian-based - Full distribution with all tools and shell access
FROM btrace/btrace:2.3.0
btrace/btrace:latest-alpine (~15MB)Alpine-based - Smaller footprint for cloud environments
FROM btrace/btrace:2.3.0-alpine
btrace/btrace:latest-distroless (~10MB)Distroless - Minimal attack surface for security-focused deployments
-javaagentFROM btrace/btrace:2.3.0-distroless AS btrace
FROM gcr.io/distroless/java11
COPY --from=btrace /opt/btrace/libs /opt/btrace/libs
Most common - copy BTrace into your application image:
FROM btrace/btrace:2.3.0 AS btrace
FROM bellsoft/liberica-openjdk-debian:11-cds
WORKDIR /app
COPY target/myapp.jar /app/
COPY --from=btrace /opt/btrace /opt/btrace
ENV BTRACE_HOME=/opt/btrace
ENV PATH="${PATH}:${BTRACE_HOME}/bin"
ENTRYPOINT ["java", "-jar", "myapp.jar"]
Usage:
docker build -t myapp:latest .
docker run -d --name myapp myapp:latest
docker exec myapp btrace <PID> /scripts/trace.btrace
Run BTrace as a sidecar container:
apiVersion: v1
kind: Pod
metadata:
name: myapp-with-btrace
spec:
shareProcessNamespace: true # Required!
containers:
- name: myapp
image: myapp:latest
- name: btrace-sidecar
image: btrace/btrace:2.3.0-alpine
command: ["/bin/sh", "-c", "while true; do sleep 30; done"]
volumeMounts:
- name: btrace-scripts
mountPath: /scripts
volumes:
- name: btrace-scripts
configMap:
name: btrace-scripts
Usage:
kubectl exec myapp-with-btrace -c btrace-sidecar -- \
sh -c 'btrace $(pgrep -f myapp) /scripts/trace.btrace'
Extend BTrace image for development:
FROM btrace/btrace:2.3.0-alpine
COPY target/myapp.jar /app/myapp.jar
COPY scripts/*.btrace /scripts/
ENTRYPOINT ["btracer"]
CMD ["-v", "-o", "/tmp/btrace-output.txt", "/app/myapp.jar"]
Minimal image with BTrace agent:
FROM btrace/btrace:2.3.0-distroless AS btrace
FROM gcr.io/distroless/java11
WORKDIR /app
COPY --from=build /app/target/myapp.jar /app/
COPY --from=btrace /opt/btrace/libs /opt/btrace/libs
ENTRYPOINT ["java", \
"-javaagent:/opt/btrace/libs/btrace-agent.jar=script=/scripts/trace.btrace", \
"-Xbootclasspath/a:/opt/btrace/libs/btrace-boot.jar", \
"-jar", "/app/myapp.jar"]
Local development with BTrace:
version: '3.8'
services:
myapp:
image: myapp:latest
ports:
- "8080:8080"
btrace:
image: btrace/btrace:2.3.0-alpine
network_mode: "service:myapp"
pid: "service:myapp"
volumes:
- ./scripts:/scripts
- ./output:/output
command: >
sh -c 'sleep 5; btrace $(pgrep -f myapp) /scripts/trace.btrace'
| Variant | Size | Shell | Scripts | Use Case |
|---|---|---|---|---|
| latest | ~25MB | ✓ | ✓ | Development, debugging |
| alpine | ~15MB | ✓ | ✓ | Kubernetes sidecar |
| distroless | ~10MB | ✗ | ✗ | Production agent mode |
Recommendations:
btrace:latest for full toolingbtrace:latest-alpine for size efficiencybtrace:latest-distroless for security| Variable | Default | Description |
|---|---|---|
BTRACE_HOME | /opt/btrace | BTrace installation directory |
BTRACE_OPTS | (empty) | Additional BTrace command options |
JAVA_HOME | (auto-detected) | Java installation path |
BTRACE_VERBOSE | false | Print version info on startup |
# Copy script into container
docker cp troubleshoot.btrace myapp:/tmp/
# Find Java process PID
docker exec myapp jps -l
# Attach BTrace
docker exec myapp btrace <PID> /tmp/troubleshoot.btrace
# View output
docker exec myapp cat /tmp/btrace-output.txt
# Deploy scripts as ConfigMap
kubectl create configmap btrace-scripts \
--from-file=monitor.btrace=./scripts/monitor.btrace
# Deploy application with sidecar
kubectl apply -f app-with-btrace-sidecar.yaml
# Stream output
kubectl logs -f myapp-pod -c btrace-sidecar
# Update script without restart
kubectl create configmap btrace-scripts \
--from-file=monitor.btrace=./scripts/updated.btrace \
--dry-run=client -o yaml | kubectl apply -f -
FROM btrace/btrace:2.3.0 AS btrace
FROM bellsoft/liberica-openjdk-debian:11-cds
COPY --from=btrace /opt/btrace /opt/btrace
ENV BTRACE_HOME=/opt/btrace PATH="${PATH}:${BTRACE_HOME}/bin"
COPY target/myapp.jar /app/
COPY scripts/profile-*.btrace /scripts/
ENTRYPOINT ["btracer", \
"-v", "-o", "/tmp/profile.txt", \
"/scripts/profile-methods.btrace", \
"-jar", "/app/myapp.jar"]
Use specific version tags in production:
FROM btrace/btrace:2.3.0 # Good
FROM btrace/btrace:latest # Avoid in production
Multi-stage builds minimize size:
FROM btrace/btrace:2.3.0 AS btrace
FROM your-app-image
COPY --from=btrace /opt/btrace /opt/btrace
Enable process namespace sharing in Kubernetes:
spec:
shareProcessNamespace: true # Required!
Store scripts in ConfigMaps:
kubectl create configmap btrace-scripts --from-file=./scripts/
Use appropriate security contexts:
securityContext:
runAsNonRoot: true
readOnlyRootFilesystem: true
capabilities:
drop: ["ALL"]
add: ["SYS_PTRACE"] # Required
Monitor BTrace overhead:
# Ensure process namespace sharing
docker run --pid=container:target-container btrace/btrace:latest
# Kubernetes: verify shareProcessNamespace
kubectl get pod myapp -o yaml | grep shareProcessNamespace
# Verify installation
docker exec myapp ls -la $BTRACE_HOME
docker exec myapp env | grep BTRACE
# Ensure JDK (not JRE) is installed
docker exec myapp java -version
docker exec myapp which javac
# Java 9+ requires module exports
ENV JAVA_OPTS="--add-exports jdk.internal.jvmstat/sun.jvmstat.monitor=ALL-UNNAMED"
# Build BTrace distribution first
./gradlew :btrace-dist:build
# Build Docker images
./gradlew :btrace-dist:buildDockerImages
# Or build manually
VERSION=2.3.0-SNAPSHOT # Set this to your BTrace version
cd docker
docker build -t btrace/btrace:local -f Dockerfile ../btrace-dist/build/resources/main/v${VERSION}
docker build -t btrace/btrace:local-alpine -f Dockerfile.alpine ../btrace-dist/build/resources/main/v${VERSION}
docker build -t btrace/btrace:local-distroless -f Dockerfile.distroless ../btrace-dist/build/resources/main/v${VERSION}
Note: Native DTrace library (libbtrace.so) is x86-only. DTrace features are not available on ARM platforms.
BTrace is licensed under GPL-2.0-only WITH Classpath-exception-2.0.
For questions and support: