Add benchmark for FHIR Engine sync api (#2830)

* Benchmark sync download api

* Add FHIR_SERVER_BASE_URL to properties

* Benchmark sync upload api

* Separate benchmarks for the different upload strategies

that is, BundleRequest and IndividualRequest upload strategies

* Add Sync api benchmarks to the macrobenchmark module

* Update docs on how to setup for sync benchmarking

Author: LZRS

benchmark-populate-server.sh

@@ -0,0 +1,34 @@
+POPULATION="${1}"
+SERVER_URL="${2}"
+SCRIPT_DIR=$(dirname "$0")
+SYNTHEA_DIR="$SCRIPT_DIR"/synthea
+
+if [ ! -d "$SYNTHEA_DIR" ]; then
+  # build Synthea according to https://github.com/synthetichealth/synthea
+  git clone https://github.com/synthetichealth/synthea.git "$SYNTHEA_DIR"
+fi
+
+rm -rf "$SYNTHEA_DIR"/output
+
+cd "$SYNTHEA_DIR" || exit
+# generate valid R4 resources in output/fhir
+./run_synthea -m pregnancy -p "$POPULATION" -s 12345 --exporter.fhir.included_resources Patient --exporter.years_of_history 1 --exporter.fhir.use_us_core_ig false --exporter.fhir.transaction_bundle true --exporter.practitioner.fhir.export true --exporter.hospital.fhir.export true
+
+cd - || exit
+# Upload hospital information
+for filename in "$SYNTHEA_DIR"/output/fhir/hospital*.json; do
+  echo "Uploading $filename"
+  curl "$SERVER_URL"/fhir --data-binary "@$filename" -H "Content-Type: application/fhir+json"  > /dev/null
+done
+
+# Upload practitioner information
+for filename in "$SYNTHEA_DIR"/output/fhir/practitioner*.json; do
+  echo "Uploading $filename"
+  curl "$SERVER_URL"/fhir --data-binary "@$filename" -H "Content-Type: application/fhir+json"  > /dev/null
+done
+
+# Upload fhir patients data
+for filename in "$SYNTHEA_DIR"/output/fhir/*.json; do
+  echo "Uploading $filename"
+  curl "$SERVER_URL"/fhir --data-binary "@$filename" -H "Content-Type: application/fhir+json"  > /dev/null
+done

benchmark-start-server.sh

@@ -0,0 +1,15 @@
+CONTAINER_ID=$(docker ps --quiet --all --no-trunc --filter "name=sync-hapi-fhir-server")
+if [ -n "$CONTAINER_ID" ]; then
+    docker container stop "$CONTAINER_ID" > /dev/null
+    docker container rm "$CONTAINER_ID" > /dev/null
+fi
+
+docker run -e JAVA_TOOL_OPTIONS="-Xmx1g" -p 8080:8080 --detach --name sync-hapi-fhir-server hapiproject/hapi:latest
+sleep 3
+
+# Checks for whether the container started successfully
+if [ -z "$(docker ps --quiet --no-trunc --filter "name=sync-hapi-fhir-server")" ]; then
+  echo "Failed to start Hapi server"
+  exit 1
+fi
+

benchmark-stop-server.sh

@@ -0,0 +1,3 @@
+# Stop container instance
+CONTAINER_ID=$(docker ps --quiet --no-trunc --filter "name=sync-hapi-fhir-server")
+docker container stop "$CONTAINER_ID"

buildSrc/src/main/kotlin/FirebaseTestLabConfig.kt

@@ -67,6 +67,9 @@ fun Project.configureFirebaseTestLabForMacroBenchmark() {
       },
     )
     instrumentationApk.set(project.provider { "$buildDir/outputs/apk/benchmark/*.apk" })
+    testTargets.set(
+      listOf("notClass com.google.android.fhir.engine.macrobenchmark.FhirEngineSyncApiBenchmark"),
+    )
   }
 }
 

buildSrc/src/main/kotlin/LocalProperties.kt

@@ -0,0 +1,38 @@
+/*
+ * Copyright 2025 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *       http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import java.io.File
+import java.io.FileInputStream
+import java.io.InputStreamReader
+import java.util.Properties
+import org.gradle.api.Project
+
+/**
+ * Retrieve the project local properties if they are available. If there is no local properties file
+ * then an empty set of properties is returned.
+ */
+fun Project.gradleLocalProperties(file: String = "local.properties"): Properties {
+  val properties = Properties()
+  val localProperties = File(rootDir, file)
+  if (localProperties.isFile) {
+    InputStreamReader(FileInputStream(localProperties), Charsets.UTF_8).use { reader ->
+      properties.load(reader)
+    }
+  } else {
+    println("Gradle local properties file not found at $localProperties")
+  }
+  return properties
+}

docs/use/FEL/Benchmarking.md

@@ -57,6 +57,7 @@ In Android Studio, set your build variants to `release` and run your benchmark a
 ![gutter test action](https://developer.android.com/static/topic/performance/images/benchmark_images/microbenchmark_run.png)
 
 The results will be similar to this:
+
 ```
 1,297,374       ns        5345 allocs    trace    EngineDatabaseBenchmark.createAndGet
 1,114,474,793   ns     4922289 allocs    trace    FhirSyncWorkerBenchmark.oneTimeSync_50patients
@@ -104,19 +105,82 @@ The Microbenchmark results can be accessed through the following steps
 
 ## Macrobenchmark module
 
-The _FHIR Engine Library_ macrobenchmark tests are located in the module `:engine:benchmarks:macrobenchmark`
+The _FHIR Engine Library_ macrobenchmark tests are located in the module `:engine:benchmarks:macrobenchmark`.
 
-### Prerequisite
+### Set Up
 
-Requires the _FHIR Engine Library_ Benchmark App configured with the relevant benchmark data described in the section for the _FHIR Engine Library_ Benchmark App
+1. Set up the _FHIR Engine Library_ Benchmark App with [the relevant data](#configuration)
 
-### Running
+2. Start the local Hapi server
 
-To run, use the command
+   Execute
 
-```shell
-./gradlew :engine:benchmarks:macrobenchmark:connectedCheck
-```
+    ```shell
+    sh benchmark-start-server.sh
+    ```
+
+   The script uses [Docker](https://docs.docker.com/engine/install/)
+   to start up a container with the [image](https://hub.docker.com/r/hapiproject/hapi) from Hapi.
+
+   It runs the docker image with the default configuration, mapping port 8080 from the container to port 8080 in the host.
+
+   Once running, you can access <http://localhost:8080/> in the browser to access the HAPI FHIR server's UI
+   or use <http://localhost:8080/fhir/> as the base URL for your REST requests
+3. Populate the Hapi server with data generated from Synthea
+
+   Execute
+
+    ```shell
+    sh benchmark-populate-server.sh 100 0.0.0.0:8080
+    ```
+
+   This generates Synthea data for a population of 100 patients and uploads the data to the local Hapi
+   server started at port 8080
+4. Check that the Android device and the host computer are connected to the same network
+5. Get the host machine's domain or LAN IP address
+
+   For mac
+
+    ```shell
+    hostname
+    ```
+
+   For linux
+
+    ```shell
+    hostname -I | awk '{print $1}'
+    ```
+
+6. Update `local.properties` file, located in the root folder, with the server url
+
+    ```properties
+    FHIR_SERVER_BASE_URL=http://192.168.0.24:8080/fhir/
+    ```
+
+   replacing `192.168.0.24` with your domain/address
+7. Run Gradle sync
+8. [Run the Macrobenchmark](https://developer.android.com/topic/performance/benchmarking/macrobenchmark-overview#run-benchmark) tests in the `engine:benchmarks:macrobenchmark` module
+
+   Execute
+
+   ```shell
+   ./gradlew :engine:benchmarks:macrobenchmark:connectedCheck
+   ```
+
+   The JSON results are automatically copied from the device to the host. These are written on the host machine in the location
+   `engine/benchmarks/macrobenchmark/build/outputs/connected_android_test_additional_output/benchmark/connected/device_id/`
+
+9. After all the tests are complete, you can stop the benchmark server
+
+   ```shell
+   sh benchmark-populate-server.sh
+   ```
+
+For reliable benchmarks:
+
+* Use physical devices: Emulators won’t give you consistent, real-world data.
+* Kill all background services: Anything running outside your app adds noise.
+* Lock the device state: Keep the brightness, network and battery levels consistent.
 
 ### Continuous Integration (CI)
 

engine/benchmarks/app/build.gradle.kts

@@ -17,6 +17,11 @@ android {
     versionName = "1.0"
 
     testInstrumentationRunner = Dependencies.androidJunitRunner
+
+    val baseUrlKey = "FHIR_SERVER_BASE_URL"
+    val fhirServerBaseUrl =
+      gradleLocalProperties().getProperty(baseUrlKey) ?: properties[baseUrlKey]?.toString() ?: ""
+    buildConfigField(type = "String", name = baseUrlKey, "\"$fhirServerBaseUrl\"")
   }
 
   buildTypes {
@@ -41,7 +46,10 @@ android {
     targetCompatibility = JavaVersion.VERSION_11
   }
   kotlinOptions { jvmTarget = "11" }
-  buildFeatures { compose = true }
+  buildFeatures {
+    compose = true
+    buildConfig = true
+  }
 
   packaging { resources.excludes.addAll(listOf("META-INF/ASL-2.0.txt", "META-INF/LGPL-3.0.txt")) }
 
@@ -65,6 +73,8 @@ dependencies {
   implementation(libs.androidx.navigation.compose)
   implementation(libs.bundles.androidx.tracing)
   implementation(libs.kotlinx.serialization.json)
+  implementation(libs.androidx.work.runtime)
+  implementation(libs.androidx.datastore.preferences)
 
   testImplementation(libs.junit)
   androidTestImplementation(libs.androidx.test.ext.junit)

engine/benchmarks/app/src/main/java/com/google/android/fhir/engine/benchmarks/app/MainActivity.kt

@@ -16,6 +16,7 @@
 
 package com.google.android.fhir.engine.benchmarks.app
 
+import android.app.Application
 import android.os.Bundle
 import androidx.activity.ComponentActivity
 import androidx.activity.compose.setContent
@@ -54,12 +55,18 @@ class MainActivity : ComponentActivity() {
   override fun onCreate(savedInstanceState: Bundle?) {
     super.onCreate(savedInstanceState)
     enableEdgeToEdge()
-    setContent { AndroidfhirTheme { AndroidfhirApp(resourcesDataProvider, fhirEngine) } }
+    setContent {
+      AndroidfhirTheme { AndroidfhirApp(application, resourcesDataProvider, fhirEngine) }
+    }
   }
 }
 
 @Composable
-fun AndroidfhirApp(resourcesDataProvider: ResourcesDataProvider, fhirEngine: FhirEngine) {
+fun AndroidfhirApp(
+  application: Application,
+  resourcesDataProvider: ResourcesDataProvider,
+  fhirEngine: FhirEngine,
+) {
   val navController = rememberNavController()
   NavHost(navController, startDestination = Screen.HomeScreen) {
     composable<Screen.HomeScreen> {
@@ -112,7 +119,7 @@ fun AndroidfhirApp(resourcesDataProvider: ResourcesDataProvider, fhirEngine: Fhi
             object : ViewModelProvider.Factory {
               override fun <T : ViewModel> create(modelClass: Class<T>): T {
                 @Suppress("UNCHECKED_CAST")
-                return SyncApiViewModel(resourcesDataProvider, fhirEngine) as T
+                return SyncApiViewModel(application, resourcesDataProvider, fhirEngine) as T
               }
             },
         )

engine/benchmarks/app/src/main/java/com/google/android/fhir/engine/benchmarks/app/MainApplication.kt

@@ -37,10 +37,11 @@ class MainApplication : Application() {
 
     FhirEngineProvider.init(
       FhirEngineConfiguration(
-        enableEncryptionIfSupported = true,
+        enableEncryptionIfSupported = !BuildConfig.DEBUG,
         RECREATE_AT_OPEN,
         ServerConfiguration(
-          "https://hapi.fhir.org/baseR4/",
+          //          "https://hapi.fhir.org/baseR4/"
+          BuildConfig.FHIR_SERVER_BASE_URL,
           httpLogger =
             HttpLogger(
               HttpLogger.Configuration(