Skip to content

The easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:

Support MB_MONITOR_PERFORMANCE to write as files to a directory (#69582)

Nathan Voxland3dcbfef5c521
diff --git a/src/metabase/cmd/resources/other-env-vars.md b/src/metabase/cmd/resources/other-env-vars.md
index 4b2bfd4ddc9..a6d84f0bdb8 100644
--- a/src/metabase/cmd/resources/other-env-vars.md
+++ b/src/metabase/cmd/resources/other-env-vars.md
@@ -329,13 +329,26 @@ Default: `""`
When set, starts a Java Flight Recorder (JFR) recording at startup that can be analyzed with JDK Mission Control or other JFR tools.
-- `"true"` generates a timestamped output file like `metabase-2026_01_15.jfr`
-- Any other non-empty value is used as the output filename (`.jfr` extension is appended if missing)
+- `"true"` generates a timestamped output file like `metabase-20260115_143000.jfr`
+- A value ending in `.jfr` is used as the output filename
+- Any other non-empty value is treated as a directory path. A new timestamped JFR file is written to that directory every 30 minutes (e.g., `metabase-20260115_143000.jfr`). Data is only written at the end of each 30-minute interval.
- `""` or `"false"` disables monitoring (the default)
The performance recording stores only method signature calls and other code execution metrics.
It does not store any sensitive information such as environment variables, system properties, or other machine information.
+### `MB_MONITOR_PERFORMANCE_SAVE_RATE`
+
+Type: integer<br>
+Default: mode-specific (5 minutes for single-file mode, 30 minutes for rolling mode)
+
+Override the interval (in minutes) at which JFR recording data is saved to disk. Only applies when [MB_MONITOR_PERFORMANCE](#mb_monitor_performance) is enabled.
+
+- In single-file mode, the default is `5` minutes.
+- In rolling directory mode, the default is `30` minutes.
+
+Setting this value overrides the default for whichever mode is active.
+
### `MB_NO_SURVEYS`
Type: boolean<br>
diff --git a/src/metabase/config/core.clj b/src/metabase/config/core.clj
index 4cba8c00294..e77f11a331f 100644
--- a/src/metabase/config/core.clj
+++ b/src/metabase/config/core.clj
@@ -64,7 +64,8 @@
:mb-log-team-attribution "false"
:mb-qp-cache-backend "db"
:mb-jetty-async-response-timeout (str (* 10 60 1000)) ; 10m
- :mb-monitor-performance ""})
+ :mb-monitor-performance ""
+ :mb-monitor-performance-save-rate ""})
;; separate map for EE stuff so merge conflicts aren't annoying.
(def ^:private ee-app-defaults
diff --git a/src/metabase/core/perf.clj b/src/metabase/core/perf.clj
index e8a5b3e6a91..d8f65c378a5 100644
--- a/src/metabase/core/perf.clj
+++ b/src/metabase/core/perf.clj
@@ -7,17 +7,18 @@
[metabase.config.core :as config]
[metabase.util.log :as log])
(:import
- (java.nio.file Files)
+ (java.nio.file Files Path)
(java.nio.file.attribute FileAttribute)
- (java.time LocalDate)
+ (java.time LocalDateTime)
(java.time.format DateTimeFormatter)
- (java.util.concurrent ScheduledThreadPoolExecutor TimeUnit)
+ (java.util.concurrent ScheduledThreadPoolExecutor ThreadFactory TimeUnit)
(jdk.jfr Configuration Recording)))
(set! *warn-on-reflection* true)
(defonce ^:private recording-atom (atom nil))
(defonce ^:private dump-executor-atom (atom nil))
+(defonce ^:private rolling-dir-atom (atom nil))
(def ^:private sensitive-events
"JFR events that may contain sensitive information and should be disabled."
@@ -26,21 +27,41 @@
"jdk.SystemProcess"
"jdk.JVMInformation"])
+(def ^:private timestamp-formatter
+ (DateTimeFormatter/ofPattern "yyyyMMdd_HHmmss"))
+
+(defn- generate-timestamped-filename
+ "Generate a timestamped JFR filename like `metabase-20260115_143000.jfr`."
+ []
+ (str "metabase-"
+ (.format (LocalDateTime/now) timestamp-formatter)
+ ".jfr"))
+
(defn- resolve-output-path
"Determine the output path for the JFR recording file.
- - `\"true\"` generates a timestamped filename like `metabase-2026_01_15.jfr`
- - Any other value is used as a filename (`.jfr` is appended if missing)"
- ^java.nio.file.Path [setting-value]
+ - `\"true\"` generates a timestamped filename like `metabase-20260115_143000.jfr`
+ - Any value ending in `.jfr` is used as-is"
+ ^Path [setting-value]
(let [filename (if (= "true" setting-value)
- (str "metabase-"
- (.format (LocalDate/now)
- (DateTimeFormatter/ofPattern "yyyy_MM_dd"))
- ".jfr")
- (if (str/ends-with? setting-value ".jfr")
- setting-value
- (str setting-value ".jfr")))]
- (.. (java.nio.file.Path/of filename (into-array String []))
- (toAbsolutePath))))
+ (generate-timestamped-filename)
+ setting-value)
+ ^Path path (Path/of filename (into-array String []))]
+ (.toAbsolutePath path)))
+
+(defn- save-rate-minutes
+ "Read the save rate from MB_MONITOR_PERFORMANCE_SAVE_RATE (in minutes), falling back to `default-minutes`."
+ [default-minutes]
+ (or (config/config-int :mb-monitor-performance-save-rate)
+ default-minutes))
+
+(defn- directory-mode?
+ "Returns true if the setting value should be treated as a directory for rolling JFR files.
+ Directory mode is any value that is not \"true\", \"false\", blank, or ending in \".jfr\"."
+ [setting-value]
+ (and (not (str/blank? setting-value))
+ (not= "false" setting-value)
+ (not= "true" setting-value)
+ (not (str/ends-with? setting-value ".jfr"))))
(defn- disable-sensitive-events!
"Disable JFR events that may contain sensitive information."
@@ -51,45 +72,92 @@
(defn- start-periodic-dump!
"Starts a background thread that periodically dumps the JFR recording to disk.
This ensures data survives hard kills (SIGKILL, OOM) where shutdown hooks don't run."
- [^Recording recording ^java.nio.file.Path output-path interval-seconds]
+ [^Recording recording ^Path output-path interval-minutes]
(let [executor (ScheduledThreadPoolExecutor. 1
- (reify java.util.concurrent.ThreadFactory
+ (reify ThreadFactory
(newThread [_ r]
(doto (Thread. r "jfr-periodic-dump")
(.setDaemon true)))))]
(.scheduleAtFixedRate executor
^Runnable (fn [] (.dump recording output-path))
- (long interval-seconds)
- (long interval-seconds)
- TimeUnit/SECONDS)
+ interval-minutes
+ interval-minutes
+ TimeUnit/MINUTES)
+ (reset! dump-executor-atom executor)))
+
+(defn- create-recording!
+ "Create and start a new JFR recording with standard settings."
+ ^Recording []
+ (let [config (Configuration/getConfiguration "profile")
+ recording (Recording. config)]
+ (.setToDisk recording true)
+ (.setMaxSize recording 0)
+ (.setMaxAge recording nil)
+ (disable-sensitive-events! recording)
+ (.start recording)
+ recording))
+
+(defn- start-rolling-mode!
+ "Start rolling directory mode. Every `interval-minutes`, dumps the current recording
+ to a timestamped file in `dir-path` and starts a new recording. Data is only written
+ to disk at the end of each interval."
+ [^Path dir-path interval-minutes]
+ (Files/createDirectories dir-path (into-array FileAttribute []))
+ (let [recording (create-recording!)
+ _ (reset! recording-atom recording)
+ _ (reset! rolling-dir-atom dir-path)
+ executor (ScheduledThreadPoolExecutor. 1
+ (reify ThreadFactory
+ (newThread [_ r]
+ (doto (Thread. r "jfr-rolling-dump")
+ (.setDaemon true)))))]
+ (.scheduleAtFixedRate
+ executor
+ ^Runnable (fn []
+ (try
+ (let [^Recording old-recording @recording-atom
+ ^String filename (generate-timestamped-filename)
+ output-file (.resolve dir-path filename)
+ new-recording (create-recording!)]
+ (.stop old-recording)
+ (.dump old-recording output-file)
+ (.close old-recording)
+ (reset! recording-atom new-recording)
+ (log/infof "Performance info written to: %s" (str output-file)))
+ (catch Throwable e
+ (log/warn e "Error during rolling performance dump"))))
+ interval-minutes
+ interval-minutes
+ TimeUnit/MINUTES)
(reset! dump-executor-atom executor)))
(defn maybe-enable-monitoring!
"If `MB_MONITOR_PERFORMANCE` is set, starts a JFR recording.
- - Value `\"true\"` auto-generates a timestamped filename
- - Any other non-empty/non-`\"false\"` string is used as filename
- - Recording uses the `\"profile\"` configuration with `dumpOnExit=true`"
+ - Value `\"true\"` auto-generates a timestamped filename (includes date+time)
+ - Value ending in `.jfr` is used as the output filename
+ - `\"\"` or `\"false\"` disables monitoring
+ - Any other value is treated as a directory for rolling 30-minute JFR files"
[]
(try
(let [setting (config/config-str :mb-monitor-performance)]
(when (and (not (str/blank? setting))
(not= "false" setting))
- (let [output-path (resolve-output-path setting)
- parent-dir (.getParent output-path)
- config (Configuration/getConfiguration "profile")
- recording (Recording. config)]
- (when parent-dir
- (Files/createDirectories parent-dir (into-array FileAttribute [])))
- (.setToDisk recording true)
- (.setDumpOnExit recording true)
- (.setMaxSize recording 0)
- (.setMaxAge recording nil)
- (.setDestination recording output-path)
- (disable-sensitive-events! recording)
- (.start recording)
- (reset! recording-atom recording)
- (start-periodic-dump! recording output-path 60)
- (log/infof "Performance monitoring started. Output file: %s" (str output-path)))))
+ (if (directory-mode? setting)
+ ;; Rolling directory mode: new file every 30 minutes
+ (let [^Path dir-path (.toAbsolutePath (Path/of setting (into-array String [])))]
+ (start-rolling-mode! dir-path (save-rate-minutes 30))
+ (log/infof "Performance monitoring started in rolling mode. Output directory: %s" (str dir-path)))
+ ;; Single file mode
+ (let [output-path (resolve-output-path setting)
+ parent-dir (.getParent output-path)]
+ (when parent-dir
+ (Files/createDirectories parent-dir (into-array FileAttribute [])))
+ (let [recording (create-recording!)]
+ (.setDumpOnExit recording true)
+ (.setDestination recording output-path)
+ (reset! recording-atom recording)
+ (start-periodic-dump! recording output-path (save-rate-minutes 5))
+ (log/infof "Performance monitoring started. Output file: %s" (str output-path)))))))
(catch Throwable e
(log/warn e "Failed to start performance monitoring"))))
@@ -102,6 +170,12 @@
(.shutdownNow executor)
(reset! dump-executor-atom nil))
(.stop recording)
+ ;; In rolling mode, dump the final partial recording before closing
+ (when-let [^Path dir-path @rolling-dir-atom]
+ (let [^String filename (generate-timestamped-filename)
+ output-file (.resolve dir-path filename)]
+ (.dump recording output-file))
+ (reset! rolling-dir-atom nil))
(.close recording)
(reset! recording-atom nil)
(log/info "Performance monitoring stopped")
diff --git a/test/metabase/core/perf_test.clj b/test/metabase/core/perf_test.clj
index e34e1a21293..2111aabd555 100644
--- a/test/metabase/core/perf_test.clj
+++ b/test/metabase/core/perf_test.clj
@@ -1,6 +1,7 @@
(ns metabase.core.perf-test
(:require
[clojure.test :refer [deftest is testing]]
+ [metabase.config.core :as config]
[metabase.core.perf :as perf])
(:import
(java.nio.file Path)))
@@ -8,14 +9,35 @@
(set! *warn-on-reflection* true)
(deftest ^:parallel resolve-output-path-test
- (testing "\"true\" generates a timestamped filename"
+ (testing "\"true\" generates a timestamped filename with date and time"
(let [^Path path (#'perf/resolve-output-path "true")]
(is (instance? Path path))
(is (.isAbsolute path))
- (is (re-matches #".*metabase-\d{4}_\d{2}_\d{2}\.jfr" (str path)))))
+ (is (re-matches #".*metabase-\d{8}_\d{6}\.jfr" (str path)))))
(testing "custom filename is used as-is when it has .jfr extension"
(let [^Path path (#'perf/resolve-output-path "my-profile.jfr")]
- (is (= "my-profile.jfr" (str (.getFileName path))))))
- (testing ".jfr extension is appended when missing"
- (let [^Path path (#'perf/resolve-output-path "my-profile")]
(is (= "my-profile.jfr" (str (.getFileName path)))))))
+
+(deftest save-rate-minutes-test
+ (testing "returns custom value when env var is set"
+ (with-redefs [config/config-int (constantly 10)]
+ (is (= 10 (#'perf/save-rate-minutes 5)))
+ (is (= 10 (#'perf/save-rate-minutes 30)))))
+ (testing "falls back to default when env var is nil"
+ (with-redefs [config/config-int (constantly nil)]
+ (is (= 5 (#'perf/save-rate-minutes 5)))
+ (is (= 30 (#'perf/save-rate-minutes 30))))))
+
+(deftest ^:parallel directory-mode?-test
+ (testing "blank string is not directory mode"
+ (is (not (#'perf/directory-mode? ""))))
+ (testing "\"false\" is not directory mode"
+ (is (not (#'perf/directory-mode? "false"))))
+ (testing "\"true\" is not directory mode"
+ (is (not (#'perf/directory-mode? "true"))))
+ (testing ".jfr file is not directory mode"
+ (is (not (#'perf/directory-mode? "my-profile.jfr"))))
+ (testing "plain string is directory mode"
+ (is (#'perf/directory-mode? "/tmp/perf-data")))
+ (testing "relative path is directory mode"
+ (is (#'perf/directory-mode? "perf-data"))))