Effective in 2026, to align with our trunk stable development model and ensure platform stability for the ecosystem, we will publish source code to AOSP in Q2 and Q4. For building and contributing to AOSP, we recommend utilizing android-latest-release instead of aosp-main. The android-latest-release manifest branch will always reference the most recent release pushed to AOSP. For more information, see Changes to AOSP.

User Guide

You can run simulations using the provided Web Demo or by calling the REST API directly.

Input and Output

Input and output files use the Cloud Storage bucket from the Terraform setup.

The input directory must contain metrics_config.zip and publisher_config.zip files. You can define the path to it as required.

The bucket for outputs contains a simulations directory, which stores each simulation by its ID. Each simulation directory contains an input folder with the copied input files and an output folder. The output folder contains the bugreport, the logcat file, and generated simulator files.

Use the Web Demo

The platform includes a Flutter-based web application for demonstration purposes that lets you view, create, and manage simulations. You are encouraged to build your own user interface tailored to your needs.

The demo app is deployed to App Engine and requires users to sign in with a Google Account. This is protected using an OAuth 2.0 Client ID configured in your Google Cloud project. The signed-in account must have IAM permissions to invoke the deployed Cloud Functions. See Manage access to Cloud Functions for instructions on granting the necessary permissions to user accounts, such as the Cloud Functions Invoker role (roles/cloudfunctions.invoker).

User Workflow

Sign in: You sign in with your Google Account, authenticated using the OAuth 2.0 process.
View simulations: The main page lists all past and current simulations by querying the Firestore database, which holds all execution information.
Create a simulation: You navigate to a form to schedule a new simulation by clicking the + action button in the lower-right corner. You provide several parameters, including the input path, build ID, and instance type. For more information, see Create a Simulation.
Monitor status: The simulation list updates to show the status of the new simulation (PENDING, RUNNING, COMPLETED, etc.).
View results: After a simulation completes, you can view the generated reports and artifacts. The input files, output reports, logs, Logcat, and Bugreports are stored in Cloud Storage.
Delete a simulation: You can cancel a scheduled or running simulation.

API Usage

For automation and integration with other systems, you can use the REST API.

The placeholder CLOUD_FUNCTION_URL used in the Authentication section and in endpoint definitions refers to the base URL of the Cloud Function being invoked. You can find function URLs in the Google Cloud console on the Cloud Functions page; the URL for each function is shown on the Trigger tab of its Function details page. Alternatively, you can find these URLs in the Terraform outputs that are printed after you run an apply command.

Authentication

All API requests must be authenticated with an Identity Token that proves the caller's identity. The identity (user or service account) must have Cloud Functions Invoker permissions on the target function.

1. User Invocation (Local and CLI) When invoking the API from a local machine or a non-Google Cloud environment, you must use a Google-issued Identity Token obtained for a user account.
```
TOKEN=$(gcloud auth print-identity-token)
```
2. Service Account Invocation (Within Google Cloud) When invoking the API from a Google Cloud resource (e.g., a Compute Engine VM, another Cloud Function, or a Kubernetes cluster), you should use the identity of the resource's attached Service Account. The token should be fetched from the resource's metadata server.
```
TOKEN=$(curl -s "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/identity?audience=CLOUD_FUNCTION_URL" -H "Metadata-Flavor: Google")
```

Include the retrieved token in the Authorization header of your requests as a Bearer token.

Endpoints

User-facing endpoints of the Cloud Telemetry Simulation stack let you create and delete simulations or read simulation information from the database.

Create a Simulation

This endpoint creates a new simulation request and schedules it for execution.

Endpoint: POST https://CLOUD_FUNCTION_URL/simulation-orchestrator-receive-request
Request Body:
```
{
  "build_id": "latest",
  "file_path": "inputs/my-test-case/",
  "instance_type": "n1-standard-8",
  "owner": "user@example.com",
  "max_simulation_time": 300,
  "max_report_count": 5
}
```
- build_id (string): The tag of the agent Docker image to use (e.g., "latest"). Important: This must match a tag defined in the infrastructure's allowed image map (e.g., "latest", "stable"). The system rejects unknown tags if a SHA256 map is defined in Terraform.
- file_path (string): The path within the GCS bucket to the folder containing metrics_config.zip and publisher_config.zip.
- instance_type (string): The Compute Engine machine type. This type must support nested virtualization, such as the n1, n2, or t2d series. For more information, see the nested virtualization overview.
- owner (string): The email of the user initiating the simulation.
- max_simulation_time (integer): The maximum time in seconds that the simulation runs.
- max_report_count (integer): The number of telemetry reports after which the simulation finishes.
Success Response (200 OK):
```
{ "id": "sim-a1b2c3d4e5f6" }
```

Delete a Simulation

This endpoint cancels a pending or running simulation and deletes its associated resources.

Endpoint: POST https://CLOUD_FUNCTION_URL/simulation-orchestrator-delete-simulation
Headers:
- Content-Type: application/json
Request Body:
```
{ "id": "sim-a1b2c3d4e5f6" }
```
Success Response (200 OK): An empty JSON object {}.

Read Simulation Data

To read simulation data, you can interact with the simulation-reader function. These endpoints use the GET method to retrieve history, status, and system configuration.

1. List simulations

Retrieves a paginated list of simulations with support for filtering and sorting.

Endpoint: GET https://CLOUD_FUNCTION_URL/simulation-reader/simulations
Query Parameters (all optional):
- status (string): Filter by simulation status (running, Simulation request received, cancelled, or completed).
- owner (string): Filter by the owner's email.
- sort_by (string): Field to sort by (received_at, status_updated_at, started_at). Defaults to received_at.
- sort_order (string): Sort direction, asc or desc. Defaults to desc.
- page_size (integer): Number of results per page. Defaults to 20.
- page_token (string): Token for fetching the next page of results.

Example Request:

curl -H "Authorization: Bearer $TOKEN"
"https://CLOUD_FUNCTION_URL/simulation-reader/simulations?status=completed&owner=user@example.com&sort_by=status_updated_at"

Success Response (200 OK):

Returns a JSON object containing an array of simulations and an optional next_page_token.

{
  "simulations": [
    {
      "id": "1234-abcd",
      "owner": "some@email.com",
      "status": "completed",
      "status_updated_at": "2025-12-05T14:50:00.952Z",
      "received_at": "2025-12-05T14:46:43.106Z",
      "started_at": "2025-12-05T14:47:05.848Z",
      "ended_at": "0001-01-01T00:00:00Z",
      "instance_id": "sim-1234-abcd",
      "ip": "10.156.15.230",
      "build_id": "europe-west3-docker.pkg.dev/your-project/simulation/simulation-agent:latest",
      "instance_type": "n1-standard-8",
      "file_path": "gs://your-project-simulation_files/path/",
      "max_simulation_time": 60,
      "max_report_count": 1
    },
    {
      "id": "5678-efgh",
      "owner": "some@email.com",
      "status": "completed",
      "status_updated_at": "2025-11-07T14:49:54.25Z",
      "received_at": "2025-11-07T14:46:54.959Z",
      "started_at": "2025-11-07T14:47:13.714Z",
      "ended_at": "0001-01-01T00:00:00Z",
      "instance_id": "sim-5678-efgh",
      "ip": "10.156.15.221",
      "build_id": "europe-west3-docker.pkg.dev/your-project/simulation/simulation-agent:latest",
      "instance_type": "n1-standard-8",
      "file_path": "gs://your-project-simulation_files/path/",
      "max_simulation_time": 60,
      "max_report_count": 1
    }
  ],
  "next_page_token": "M7bydGsAptLncj8SOCb1"
}

2. Get a specific simulation

Retrieves the full details of a specific simulation by its ID.

Endpoint:

GET https://CLOUD_FUNCTION_URL/simulation-reader/simulations/[SIMULATION_ID]

Success Response (200 OK): Returns a JSON object containing the details of the requested simulation.

{
  "id": "1234-abcd",
  "owner": "some@email.com",
  "status": "completed",
  "status_updated_at": "2025-12-05T14:50:00.952Z",
  "received_at": "2025-12-05T14:46:43.106Z",
  "started_at": "2025-12-05T14:47:05.848Z",
  "ended_at": "0001-01-01T00:00:00Z",
  "instance_id": "sim-1234-abcd",
  "ip": "10.156.15.230",
  "build_id": "europe-west3-docker.pkg.dev/your-project/simulation/simulation-agent:latest",
  "instance_type": "n1-standard-8",
  "file_path": "gs://your-project-simulation_files/path/",
  "max_simulation_time": 60,
  "max_report_count": 1
}

3. Get system metrics and configuration

These endpoints provide insight into the current load and configuration of the simulation infrastructure.

Get Running Count: Returns the count of running simulations.