Guida dell'utente

Puoi eseguire le simulazioni utilizzando la demo web fornita o chiamando direttamente l'API REST.

Input e output

I file di input e output utilizzano il bucket Cloud Storage della configurazione di Terraform.

La directory di input deve contenere i file metrics_config.zip e publisher_config.zip. Puoi definire il percorso in base alle tue esigenze.

Il bucket per gli output contiene una directory simulations, che archivia ogni simulazione in base al relativo ID. Ogni directory di simulazione contiene una cartella di input con i file di input copiati e una cartella di output. La cartella di output contiene il bugreport, il file logcat e i file del simulatore generati.

Utilizzare la demo web

La piattaforma include un'applicazione web basata su Flutter a scopo dimostrativo che consente di visualizzare, creare e gestire le simulazioni. Ti invitiamo a creare la tua interfaccia utente su misura per le tue esigenze.

L'app demo viene implementata in App Engine e richiede l'accesso con un Account Google. Questa operazione è protetta utilizzando un ID client OAuth 2.0 configurato nel tuo progetto Google Cloud. L'account con cui hai eseguito l'accesso deve disporre delle autorizzazioni IAM per richiamare le funzioni Cloud Functions di cui è stato eseguito il deployment. Consulta Autorizzare l'accesso con IAM per istruzioni su come concedere le autorizzazioni necessarie agli account utente, ad esempio il ruolo Invoker di Cloud Functions (roles/cloudfunctions.invoker).

Workflow utente

  1. Accedi con il tuo Account Google, autenticato tramite la procedura OAuth 2.0.
  2. Visualizza le simulazioni nella pagina principale, che elenca tutte le simulazioni interrogando il database Firestore, che contiene tutte le informazioni sull'esecuzione.
  3. Vai a un modulo per pianificare una nuova simulazione facendo clic sul pulsante di azione + nell'angolo in basso a destra. Fornisci diversi parametri, tra cui il percorso di input, l'ID build e il tipo di istanza. Per saperne di più, vedi Creare una simulazione.
  4. Controlla lo stato del monitor negli aggiornamenti dell'elenco delle simulazioni, che mostrano lo stato della nuova simulazione, ad esempio PENDING, RUNNING, COMPLETED.
  5. Al termine di una simulazione, visualizza i report e gli artefatti generati. I file di input, i report di output, i log, Logcat e Bugreport vengono archiviati in Cloud Storage.
  6. (Facoltativo) Annulla una simulazione pianificata o in esecuzione.

Utilizzo delle API

Per l'automazione e l'integrazione con altri sistemi, puoi utilizzare l'API REST.

Il segnaposto CLOUD_FUNCTION_URL utilizzato nella sezione Autenticazione e nelle definizioni degli endpoint si riferisce all'URL di base della funzione Cloud richiamata. Puoi trovare gli URL delle funzioni nella console Google Cloud nella pagina Cloud Functions; l'URL di ogni funzione viene visualizzato nella scheda Trigger della pagina Dettagli funzione. In alternativa, puoi trovare questi URL negli output di Terraform stampati dopo l'esecuzione di un comando apply.

Autenticazione

Tutte le richieste API devono essere autenticate con un token identità che dimostri l'identità del chiamante. L'identità (utente o service account) deve disporre delle autorizzazioni Invoker di Cloud Functions per la funzione di destinazione.

  1. Richiamo utente (locale e CLI): quando richiami l'API da una macchina locale o da un ambiente non Google Cloud, devi utilizzare un token ID emesso da Google ottenuto per un account utente.

    TOKEN=$(gcloud auth print-identity-token)

  2. Richiamo del service account (all'interno di Google Cloud): quando richiami l'API da una risorsa Google Cloud (ad esempio una VM Compute Engine, un'altra Cloud Function o un cluster Kubernetes), utilizza l'identità del service account collegato alla risorsa. Il token deve essere recuperato dal server di metadati della risorsa.

    TOKEN=$(curl -s "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/identity?audience=CLOUD_FUNCTION_URL" -H "Metadata-Flavor: Google")

Includi il token recuperato nell'intestazione Authorization delle tue richieste come token Bearer.

Endpoint

Gli endpoint rivolti agli utenti dello stack di simulazione di Cloud Telemetry ti consentono di creare ed eliminare simulazioni o leggere le informazioni di simulazione dal database.

Crea una simulazione

Questo endpoint crea una nuova richiesta di simulazione e la pianifica per l'esecuzione.

  • Endpoint: POST https://CLOUD_FUNCTION_URL/simulation-orchestrator-receive-request

  • Corpo della richiesta:

    {
  "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 (stringa): il tag dell'immagine Docker dell'agente da utilizzare, ad esempiolatest.

    • file_path (stringa): il percorso all'interno del bucket GCS della cartella contenente metrics_config.zip e publisher_config.zip.

    • instance_type (stringa): il tipo di macchina Compute Engine. Questo tipo deve supportare la virtualizzazione nidificata, ad esempio le serie n1, n2 o t2d. Per saperne di più, consulta la panoramica della virtualizzazione nidificata.

    • owner (stringa): l'email dell'utente che avvia la simulazione.

    • max_simulation_time (numero intero): il tempo massimo in secondi durante il quale viene eseguita la simulazione.

    • max_report_count (integer): il numero di report di telemetria dopo il quale la simulazione termina.

  • Risposta di successo (200 OK):

    { "id": "sim-a1b2c3d4e5f6" }

Elimina una simulazione

Questo endpoint annulla una simulazione in attesa o in esecuzione ed elimina le risorse associate.

  • Endpoint: POST https://CLOUD_FUNCTION_URL/simulation-orchestrator-delete-simulation
  • Intestazioni:
    • Content-Type: application/json

  • Corpo della richiesta:

    { "id": "sim-a1b2c3d4e5f6" }

  • Risposta di esito positivo (200 OK): un oggetto JSON vuoto {}.

Lettura dei dati di simulazione

Per leggere i dati di simulazione, puoi interagire con la funzione simulation-reader. Questi endpoint utilizzano il metodo GET per recuperare la cronologia, lo stato e la configurazione del sistema.

Elenco simulazioni

Recupera un elenco paginato di simulazioni con supporto per il filtro e l'ordinamento.

  • Endpoint: GET https://CLOUD_FUNCTION_URL/simulation-reader/simulations

  • Parametri di query (tutti facoltativi):

    • status (stringa): filtra in base allo stato della simulazione (running, Simulation request received, cancelled o completed).
    • owner (stringa): filtra in base all'email del proprietario.
    • sort_by (stringa): campo in base al quale ordinare (received_at, status_updated_at, started_at). Il valore predefinito è received_at.
    • sort_order (stringa): direzione dell'ordinamento, asc o desc. Il valore predefinito è desc.
    • page_size (integer): numero di risultati per pagina. Il valore predefinito è 20.
    • page_token (stringa): token per recuperare la pagina successiva dei risultati.

  • Esempio di richiesta:

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

  • Risposta di successo (200 OK):

    • Restituisce un oggetto JSON contenente un array di simulazioni e un next_page_token facoltativo.
    {
  "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"
}
Ottenere una simulazione specifica

Recupera i dettagli completi di una simulazione specifica in base al suo ID.

  • Endpoint:

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

  • Risposta di successo (200 OK): restituisce un oggetto JSON contenente i dettagli della simulazione richiesta.

    {
  "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
}
Ottenere metriche e configurazione del sistema

Questi endpoint forniscono informazioni sul carico e sulla configurazione attuali dell'infrastruttura di simulazione.

  • Get running count:restituisce il conteggio delle simulazioni in esecuzione.

    • Endpoint:

      GET https://CLOUD_FUNCTION_URL/simulation-reader/simulations/running/count

    • Risposta di successo (200 OK):

      {
  "count": 0
}

  • Get max concurrent VMs:restituisce il numero massimo configurato di VM in esecuzione contemporaneamente.

    • Endpoint:

      GET https://CLOUD_FUNCTION_URL/simulation-reader/config/max-running-vms

    • Risposta di successo (200 OK):

      {
  "max_running_vms": 5
}