84codes
diff --git a/‎.github/workflows/ci.yml‎
Lines changed: 4 additions & 2 deletions b/‎.github/workflows/ci.yml‎
Lines changed: 4 additions & 2 deletions
diff --git a/‎CHANGELOG.md‎
Lines changed: 1 addition & 0 deletions b/‎CHANGELOG.md‎
Lines changed: 1 addition & 0 deletions
diff --git a/‎bin/compile‎
Lines changed: 12 additions & 2 deletions b/‎bin/compile‎
Lines changed: 12 additions & 2 deletions
diff --git a/‎bin/report‎
Lines changed: 30 additions & 8 deletions b/‎bin/report‎
Lines changed: 30 additions & 8 deletions
diff --git a/‎bin/support/bash_functions.sh‎
Lines changed: 227 additions & 24 deletions b/‎bin/support/bash_functions.sh‎
Lines changed: 227 additions & 24 deletions
@@ -18,8 +18,10 @@ jobs:
         uses: actions/checkout@v4
       - name: Run ShellCheck bin top level
         run: |
-            shellcheck bin/support/bash_functions.sh bin/support/download_ruby -x &&
-            shellcheck bin/compile bin/detect bin/release bin/test bin/test-compile -x
+            # All bash files that don't end in '.rb'
+            # https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddefpathspecapathspec
+            git ls-files -z --cached --others --exclude-standard ':(exclude)*.rb' 'bin/*' '*/bin/*' '*.sh' | \
+              xargs -0 shellcheck --check-sourced --color=always
 
   integration-test:
       runs-on: ubuntu-24.04
 
@@ -2,6 +2,7 @@
 
 ## [Unreleased]
 
+- Add bash based failure metrics reporting for `bin/report`. This allows the buildpack to distinguish beteween types of failures that occur before Ruby code in the buildpack has executed (such as when bootstrapping). (https://github.com/heroku/heroku-buildpack-ruby/pull/1635)
 
 ## [v318] - 2025-08-11
 
 
@@ -12,10 +12,19 @@ BIN_DIR=$(cd "$(dirname "$0")" || exit; pwd) # absolute path
 # shellcheck source=bin/support/bash_functions.sh
 source "$BIN_DIR/support/bash_functions.sh"
 
+# Initialize metrics for bin/report
+build_data::init "${CACHE_DIR}"
+build_data::clear
+
 checks::ensure_supported_stack "${STACK:?Required env var STACK is not set}"
 
 bootstrap_ruby_dir=$(mktemp -d)
-"$BIN_DIR"/support/download_ruby "$BIN_DIR" "$bootstrap_ruby_dir"
+if "$BIN_DIR"/support/download_ruby "$BIN_DIR" "$bootstrap_ruby_dir"; then
+  :
+else
+  build_data::kv_string "failure_reason" "bootstrap_ruby_fail"
+  exit 1
+fi
 trap 'rm -rf "$bootstrap_ruby_dir"' EXIT
 
 export PATH="$bootstrap_ruby_dir/bin/:$PATH"
@@ -35,7 +44,8 @@ if detect_needs_java "$BUILD_DIR"; then
 
 EOM
 
+  build_data::kv_string "java_origin" "ruby_buildpack"
   compile_buildpack_v2 "$BUILD_DIR" "$CACHE_DIR" "$ENV_DIR" "https://buildpack-registry.s3.us-east-1.amazonaws.com/buildpacks/heroku/jvm.tgz" "heroku/jvm"
 fi
 
-"$bootstrap_ruby_dir"/bin/ruby "$BIN_DIR/support/ruby_compile" "$@"
+"$bootstrap_ruby_dir"/bin/ruby "$BIN_DIR/support/ruby_compile.rb" "$@"
@@ -1,13 +1,35 @@
 #!/usr/bin/env bash
+# Usage: bin/report <build-dir> <cache-dir> <env-dir>
+
+# Produces a build report containing metadata about the build, that's consumed by the build system.
+# This script is run for both successful and failing builds, so it should not assume the build ran
+# to completion (e.g. Python or other tools may not even have been installed).
+#
+# Metrics are collected from the part of the buildpack written in Ruby and the
+# part written in Bash (that is used to bootstrap Ruby). They both write to the
+# same JSON file on disk.
+#
+# Metadata must be emitted to stdout as valid un-nested json (values must not be objects or arrays).
+#
+# Example valid stdout:
+#   {
+#     "ruby_version": "X.Y.Z",
+#     "ruby_install_duration": 1.234
+#   }
+#
+# Failures in this script don't cause the overall build to fail (and won't appear in user
+# facing build logs) to avoid breaking builds unnecessarily / causing confusion. To debug
+# issues check the internal build system logs for `buildpack.report.failed` events, or
+# when developing run `make run` in this repo locally, which runs `bin/report` too.
 
 set -euo pipefail
 
 CACHE_DIR="${2}"
-REPORT_FILE="${CACHE_DIR}/.heroku/ruby/build_report.yml"
-
-# Whilst the release file is always written by the buildpack, some apps use
-# third-party slug cleaner buildpacks to remove this and other files, so we
-# cannot assume it still exists by the time the release step runs.
-if [[ -f "${REPORT_FILE}" ]]; then
-  cat "${REPORT_FILE}"
-fi
+# The absolute path to the root of the buildpack.
+BIN_DIR=$(cd "$(dirname "$0")" || exit; pwd) # absolute path
+
+# Initialize metrics for bin/report
+# shellcheck source=bin/support/bash_functions.sh
+source "$BIN_DIR/support/bash_functions.sh"
+build_data::init "${CACHE_DIR}"
+build_data::print_bin_report_json
@@ -1,5 +1,7 @@
 #!/usr/bin/env bash
 
+set -euo pipefail
+
 curl_retry_on_18() {
   local ec=18;
   local attempts=0;
@@ -25,6 +27,7 @@ detect_needs_java()
   local skip_java_install=1
 
   if which_java; then
+    build_data::kv_string "java_origin" "previously_installed"
     return $skip_java_install
   fi
 
@@ -64,45 +67,77 @@ compile_buildpack_v2()
 
     if [[ "$url" =~ \.tgz$ ]] || [[ "$url" =~ \.tgz\? ]]; then
       mkdir -p "$dir"
-      curl_retry_on_18 -s --fail --retry 3 --retry-connrefused --connect-timeout "${CURL_CONNECT_TIMEOUT:-3}" "$url" | tar xvz -C "$dir" >/dev/null 2>&1
+      if curl_retry_on_18 -s --fail --show-error --retry 3 --retry-connrefused --connect-timeout "${CURL_CONNECT_TIMEOUT:-3}" "$url" | tar xz -C "$dir"; then
+        :
+      else
+        echo "Failed to download $url"
+        build_data::kv_string "failure_reason" "compile_buildpack_v2_download_fail"
+        build_data::kv_string "failure_detail" "url: $url"
+        exit 1
+      fi
     else
-      git clone "$url" "$dir" >/dev/null 2>&1
+      if git clone --quiet "$url" "$dir"; then
+        :
+      else
+        echo "Failed to clone $url"
+        build_data::kv_string "failure_reason" "compile_buildpack_v2_download_fail"
+        build_data::kv_string "failure_detail" "url: $url"
+        exit 1
+      fi
     fi
     cd "$dir" || return
 
     if [ "$branch" != "" ]; then
-      git checkout "$branch" >/dev/null 2>&1
+      if git checkout "$branch" >/dev/null 2>&1; then
+        :
+      else
+        echo "Failed to checkout branch $branch"
+        build_data::kv_string "failure_reason" "compile_buildpack_v2_checkout_fail"
+        build_data::kv_string "failure_detail" "buildpack: $buildpack, branch: $branch"
+        exit 1
+      fi
     fi
 
     # we'll get errors later if these are needed and don't exist
     chmod -f +x "$dir/bin/{detect,compile,release}" || true
 
-    framework=$("$dir"/bin/detect "$build_dir")
+    if framework=$("$dir"/bin/detect "$build_dir"); then
+      :
+    else
+      echo "Couldn't detect any framework for this buildpack. Exiting."
+      build_data::kv_string "failure_reason" "compile_buildpack_v2_detect_fail"
+      build_data::kv_string "failure_detail" "buildpack: $buildpack"
 
-    # shellcheck disable=SC2181
-    if [ $? == 0 ]; then
-      echo "-----> Detected Framework: $framework"
-      "$dir"/bin/compile "$build_dir" "$cache_dir" "$env_dir"
+      exit 1
+    fi
 
-      # shellcheck disable=SC2181
-      if [ $? != 0 ]; then
-        exit 1
-      fi
+    echo "-----> Detected Framework: $framework"
+    if "$dir"/bin/compile "$build_dir" "$cache_dir" "$env_dir"; then
+      :
+    else
+      echo "Failed to compile with $buildpack"
+      build_data::kv_string "failure_reason" "compile_buildpack_v2_compile_fail"
+      build_data::kv_string "failure_detail" "buildpack: $buildpack"
+      exit 1
+    fi
 
-      # check if the buildpack left behind an environment for subsequent ones
-      if [ -e "$dir/export" ]; then
-        set +u # http://redsymbol.net/articles/unofficial-bash-strict-mode/#sourcing-nonconforming-document
-        # shellcheck disable=SC1091
-        source "$dir/export"
-        set -u # http://redsymbol.net/articles/unofficial-bash-strict-mode/#sourcing-nonconforming-document
-      fi
+    # check if the buildpack left behind an environment for subsequent ones
+    if [ -e "$dir/export" ]; then
+      set +u # http://redsymbol.net/articles/unofficial-bash-strict-mode/#sourcing-nonconforming-document
+      # shellcheck disable=SC1091
+      source "$dir/export"
+      set -u # http://redsymbol.net/articles/unofficial-bash-strict-mode/#sourcing-nonconforming-document
+    fi
 
-      if [ -x "$dir/bin/release" ]; then
-        "$dir"/bin/release "$build_dir" > "$1"/last_pack_release.out
+    if [ -x "$dir/bin/release" ]; then
+      if "$dir"/bin/release "$build_dir" > "$1"/last_pack_release.out; then
+        :
+      else
+        echo "Failed bin/release with $buildpack"
+        build_data::kv_string "failure_reason" "compile_buildpack_v2_release_fail"
+        build_data::kv_string "failure_detail" "buildpack: $buildpack"
+        exit 1
       fi
-    else
-      echo "Couldn't detect any framework for this buildpack. Exiting."
-      exit 1
     fi
   fi
 }
@@ -119,6 +154,8 @@ function checks::ensure_supported_stack() {
 			return 0
 			;;
 		heroku-18 | heroku-20)
+			build_data::kv_string "failure_reason" "stack_eol"
+			build_data::kv_string "failure_detail" "${stack} stack"
 			# This error will only ever be seen on non-Heroku environments, since the
 			# Heroku build system rejects builds using EOL stacks.
 			cat <<-EOF
@@ -133,6 +170,8 @@ function checks::ensure_supported_stack() {
 			exit 1
 			;;
 		*)
+			build_data::kv_string "failure_reason" "stack_unknown"
+			build_data::kv_string "failure_detail" "${stack} stack"
 			cat <<-EOF
 				Error: The '${stack}' stack isn't recognised.
 
@@ -147,3 +186,167 @@ function checks::ensure_supported_stack() {
 			;;
 	esac
 }
+
+## ==============================
+# Start of build_data section
+## ==============================
+
+# Contains functions for storing build data from the buildpack in bash.
+#
+# The format of the report file is JSON.
+#
+# Example:
+#   {
+#     "ruby_version": "3.3.3",
+#     "ruby_install_duration": 1.234
+#   }
+#
+# All keys get `ruby.` prepended to them in the backend automatically.
+
+# Variables shared by this whole module
+BUILD_DATA_FILE="/dev/null"
+# Exported for use by Ruby code
+HEROKU_RUBY_BUILD_REPORT_FILE="/dev/null"
+
+# Must be called before you can use any other methods
+#
+# Usage:
+# ```
+# build_data::init "${CACHE_DIR}"
+# ```
+build_data::init() {
+	local cache_dir="${1}"
+	BUILD_DATA_FILE="${cache_dir}/build-data/ruby.json"
+	HEROKU_RUBY_BUILD_REPORT_FILE="${BUILD_DATA_FILE}"
+
+	# Used later in the `HerokuBuildReport.set_global` call in `bin/support/ruby_compile`
+	export HEROKU_RUBY_BUILD_REPORT_FILE
+}
+
+# Clears any prior build data since it persists between builds
+#
+# Usage:
+# ```
+# build_data::init "${CACHE_DIR}"
+# build_data::clear
+# ```
+build_data::clear() {
+	mkdir -p "$(dirname "${BUILD_DATA_FILE}")"
+	echo "{}" >"${BUILD_DATA_FILE}"
+}
+
+# Adds a key-value pair to the report file without any attempt to quote or escape the value.
+#
+# Usage:
+# ```
+# build_data::kv_raw "ruby_version_major" "3"
+# build_data::kv_raw "ruby_version_default" "true"
+# ```
+build_data::kv_raw() {
+	local key="${1}"
+	local value="${2}"
+	build_report::_set "${key}" "${value}" "false"
+}
+
+# Adds a key-value pair to the report file, quoting the value.
+#
+# Usage:
+# ```
+# build_data::kv_string "ruby_version" "3.3.3"
+# ```
+build_data::kv_string() {
+	local key="${1}"
+	local value="${2}"
+	build_report::_set "${key}" "${value}" "true"
+}
+
+# Internal helper to write a key/value pair to the build data store. The buildpack shouldn't call this directly.
+# Takes a key, value, and a boolean flag indicating whether the value needs to be quoted.
+#
+# Usage:
+# ```
+# build_report::_set "foo_string" "quote me" "true"
+# build_report::_set "bar_number" "99" "false"
+# ```
+function build_report::_set() {
+	local key="${1}"
+	# Truncate the value to an arbitrary 200 characters since it will sometimes contain user-provided
+	# inputs which may be unbounded in size. Ideally individual call sites will perform more aggressive
+	# truncation themselves based on the expected value size, however this is here as a fallback.
+	# (Honeycomb supports string fields up to 64KB in size, however, it's not worth filling up the
+	# build data store or bloating the payload passed back to Vacuole/submitted to Honeycomb given the
+	# extra content in those cases is not normally useful.)
+	local value="${2:0:200}"
+	local needs_quoting="${3}"
+
+	if [[ "${needs_quoting}" == "true" ]]; then
+		# Values passed using `--arg` are treated as strings, and so have double quotes added and any JSON
+		# special characters (such as newlines, carriage returns, double quotes, backslashes) are escaped.
+		local jq_args=(--arg value "${value}")
+	else
+		# Values passed using `--argjson` are treated as raw JSON values, and so aren't escaped or quoted.
+		local jq_args=(--argjson value "${value}")
+	fi
+
+	local new_data_file_contents
+	new_data_file_contents="$(jq --arg key "${key}" "${jq_args[@]}" '. + { ($key): ($value) }' "${BUILD_DATA_FILE}")"
+	echo "${new_data_file_contents}" >"${BUILD_DATA_FILE}"
+}
+
+# Returns the current time since the UNIX Epoch, as a float with microseconds precision.
+#
+# Usage (2025-08-22 11:15 UTC):
+# ```
+# build_data::current_unix_realtime
+# # => 1755879324.771610
+# ```
+build_data::current_unix_realtime() {
+	# We use a subshell with `LC_ALL=C` to ensure the output format isn't affected by system locale.
+	(
+		LC_ALL=C
+		echo "${EPOCHREALTIME}"
+	)
+}
+
+# Adds a key=duration to the report file.
+#
+# Usage:
+# ```
+# start_time=$(build_data::current_unix_realtime)
+# sleep 1
+# build_data::kv_duration_since "ruby_install" "${start_time}"
+#
+# build_data::print_bin_report_json
+# # => { "ruby_install": 1.234 }
+# ```
+build_data::kv_duration_since() {
+	local key="${1}"
+	local start_time="${2}"
+	local end_time duration
+	end_time="$(build_data::current_unix_realtime)"
+	duration="$(awk -v start="${start_time}" -v end="${end_time}" 'BEGIN { printf "%f", (end - start) }')"
+
+	build_data::kv_raw "${key}" "${duration}"
+}
+
+# Prints the build data in JSON format.
+#
+# Usage:
+# ```
+# build_data::print_bin_report_json
+# # => { "ruby_install": 1.234 }
+# ```
+build_data::print_bin_report_json() {
+	if [ "${HEROKU_RUBY_BUILD_REPORT_FILE}" != "${BUILD_DATA_FILE}" ]; then
+		echo "Error: HEROKU_RUBY_BUILD_REPORT_FILE does not match BUILD_DATA_FILE"
+		echo "HEROKU_RUBY_BUILD_REPORT_FILE: ${HEROKU_RUBY_BUILD_REPORT_FILE}"
+		echo "BUILD_DATA_FILE: ${BUILD_DATA_FILE}"
+		exit 1
+	fi
+
+	jq --sort-keys '.' "${BUILD_DATA_FILE}"
+}
+
+## ==============================
+# End of build data section
+## ==============================
Original file line number	Diff line number	Diff line change
`@@ -2,6 +2,7 @@`
`2`	`2`
`3`	`3`	`## [Unreleased]`
`4`	`4`
	`5`	+- Add bash based failure metrics reporting for `bin/report`. This allows the buildpack to distinguish beteween types of failures that occur before Ruby code in the buildpack has executed (such as when bootstrapping). (https://github.com/heroku/heroku-buildpack-ruby/pull/1635)
`5`	`6`
`6`	`7`	`## [v318] - 2025-08-11`
`7`	`8`