Kullanıcı kılavuzu

Simülasyonları, sağlanan web demosunu kullanarak veya doğrudan REST API'yi çağırarak çalıştırabilirsiniz.

Giriş ve çıkış

Giriş ve çıkış dosyaları, Terraform kurulumundaki Cloud Storage paketini kullanır.

Giriş dizini metrics_config.zip ve publisher_config.zip dosyalarını içermelidir. Yolu gerektiği gibi tanımlayabilirsiniz.

Çıkışlar için kullanılan pakette, her simülasyonu kimliğine göre depolayan bir simulations dizini bulunur. Her simülasyon dizini, kopyalanan giriş dosyalarını içeren bir inputs klasörü ve bir outputs klasörü içerir. outputs klasöründe hata raporu, logcat dosyası ve oluşturulan simülatör dosyaları bulunur.

Web demosunu kullanma

Platformda, simülasyonları görüntülemenize, oluşturmanıza ve yönetmenize olanak tanıyan, tanıtım amaçlı Flutter tabanlı bir web uygulaması bulunur. İhtiyaçlarınıza göre uyarlanmış kendi kullanıcı arayüzünüzü oluşturmanız önerilir.

Demo uygulaması App Engine'e dağıtılır ve Google Hesabı ile oturum açmanızı gerektirir. Bu, Google Cloud projenizde yapılandırılmış bir OAuth 2.0 istemci kimliği kullanılarak korunur. Oturum açılan hesabın, dağıtılan Cloud Functions işlevlerini çağırmak için IAM izinlerine sahip olması gerekir. Kullanıcı hesaplarına Cloud Functions Çağırıcısı rolü (roles/cloudfunctions.invoker) gibi gerekli izinleri verme talimatları için IAM ile erişim yetkisi verme başlıklı makaleyi inceleyin.

Kullanıcı iş akışı

  1. OAuth 2.0 işlemi kullanılarak kimliği doğrulanmış Google Hesabınızla oturum açın.
  2. Tüm yürütme bilgilerini barındıran Firestore veritabanını sorgulayarak tüm simülasyonları listeleyen ana sayfada simülasyonları görüntüleyin.
  3. Sağ alt köşedeki + işlem düğmesini tıklayarak yeni bir simülasyon planlamak için forma gidin. Giriş yolu, derleme kimliği ve örnek türü gibi çeşitli parametreler sağlarsınız. Daha fazla bilgi için Simülasyon oluşturma başlıklı makaleyi inceleyin.
  4. Simülasyon listesi güncellemelerinde izleme durumunu kontrol edin. Burada yeni simülasyonun durumu gösterilir (ör. PENDING, RUNNING, COMPLETED).
  5. Simülasyon tamamlandıktan sonra oluşturulan raporları ve yapıları görüntüleyin. Giriş dosyaları, çıkış raporları, günlükler, Logcat ve hata raporları Cloud Storage'da depolanır.
  6. İsteğe bağlı: Planlanmış veya çalışan bir simülasyonu iptal edin.

API kullanımı

Otomasyon ve diğer sistemlerle entegrasyon için REST API'yi kullanabilirsiniz.

Kimlik doğrulama bölümünde ve uç nokta tanımlarında kullanılan CLOUD_FUNCTION_URL yer tutucusu, çağrılan Cloud Functions işlevinin ana URL'sini ifade eder. İşlev URL'lerini Google Cloud Console'daki Cloud Functions sayfasında bulabilirsiniz. Her işlevin URL'si, İşlev ayrıntıları sayfasının Tetikleyici sekmesinde gösterilir. Alternatif olarak, bu URL'leri bir apply komutu çalıştırdıktan sonra yazdırılan Terraform çıkışlarında bulabilirsiniz.

Kimlik doğrulama

Tüm API isteklerinin, arayanın kimliğini kanıtlayan bir kimlik jetonuyla kimlik doğrulaması yapılmalıdır. Kimliğin (kullanıcı veya hizmet hesabı), hedef işlevde Cloud Functions Çağırıcısı izinlerine sahip olması gerekir.

  1. Kullanıcı çağrısı (yerel ve CLI): API'yi yerel bir makineden veya Google Cloud dışı bir ortamdan çağırırken bir kullanıcı hesabı için alınmış Google tarafından verilen kimlik jetonunu kullanmanız gerekir.

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

  2. Hizmet hesabı çağrısı (Google Cloud içinde): API'yi bir Google Cloud kaynağından (ör. Compute Engine sanal makinesi, başka bir Cloud Functions işlevi veya Kubernetes kümesi) çağırırken kaynağın ekli hizmet hesabının kimliğini kullanın. Jeton, kaynağın meta veri sunucusundan alınmalıdır.

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

Alınan jetonu, isteklerinizin Authorization başlığına Bearer jetonu olarak ekleyin.

Uç noktalar

Cloud Telemetry Simulation yığınının kullanıcıya yönelik uç noktaları, simülasyon oluşturup silmenize veya veritabanından simülasyon bilgilerini okumanıza olanak tanır.

Simülasyon oluşturma

Bu uç nokta, yeni bir simülasyon isteği oluşturur ve yürütülmek üzere planlar.

  • Uç nokta: POST https://CLOUD_FUNCTION_URL/simulation-orchestrator-receive-requests

  • İstek gövdesi:

    {
  "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 (dize): Kullanılacak temsilci Docker görüntüsünün etiketi (ör. latest).

    • file_path (dize): GCS paketinde metrics_config.zip ve publisher_config.zip içeren klasörün yolu.

    • instance_type (dize): Compute Engine makine türü. Bu tür, iç içe yerleştirilmiş sanallaştırmayı desteklemelidir (ör. n1, n2 veya t2d serisi). Daha fazla bilgi için iç içe yerleştirilmiş sanallaştırmaya genel bakış başlıklı makaleyi inceleyin.

    • owner (dize): Simülasyonu başlatan kullanıcının e-posta adresi.

    • max_simulation_time (tam sayı): Simülasyonun saniye cinsinden maksimum çalışma süresi.

    • max_report_count (tam sayı): Simülasyonun tamamlanması için gereken telemetri raporu sayısı.

  • Başarılı yanıt (200 OK):

    { "id": "sim-a1b2c3d4e5f6" }

Simülasyon silme

Bu uç nokta, beklemedeki veya çalışan bir simülasyonu iptal eder ve ilişkili kaynaklarını siler.

  • Uç nokta: POST https://CLOUD_FUNCTION_URL/simulation-orchestrator-delete-simulation
  • Başlıklar:
    • Content-Type: application/json

  • İstek gövdesi:

    { "id": "sim-a1b2c3d4e5f6" }

  • Başarılı yanıt (200 OK): Düz metin mesajı (Request accepted and is being processed).

Simülasyon verilerini okuma

Simülasyon verilerini okumak için simulation-reader işleviyle etkileşim kurabilirsiniz. Bu uç noktalar; geçmişi, durumu ve sistem yapılandırmasını almak için GET yöntemini kullanır.

Simülasyonları listeleme

Filtreleme ve sıralama desteğiyle simülasyonların sayfalandırılmış bir listesini alır.

  • Uç nokta: GET https://CLOUD_FUNCTION_URL/simulation-reader/simulations

  • Sorgu parametreleri (tümü isteğe bağlı):

    • status (dize): Simülasyon durumuna göre filtreleyin (running, Simulation request received, cancelled, completed veya failed).
    • owner (dize): Sahibin e-posta adresine göre filtreleyin.
    • sort_by (string): Sıralama ölçütü olarak kullanılacak alan (received_at, status_updated_at, started_at). Varsayılan değer: received_at.
    • sort_order (dize): Sıralama yönü, asc veya desc. Varsayılan değer: desc.
    • page_size (tamsayı): Sayfa başına sonuç sayısı. Varsayılan değer 20'dir.
    • page_token (dize): Sonraki sonuç sayfasını getirmek için kullanılan jeton.

  • Örnek istek:

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

  • Başarılı yanıt (200 OK):

    • Simülasyon dizisi ve isteğe bağlı bir next_page_token içeren bir JSON nesnesi döndürür.
    {
  "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"
}
Belirli bir simülasyonu alma

Belirli bir simülasyonun tüm ayrıntılarını kimliğine göre alır.

  • Uç nokta:

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

  • Başarılı yanıt (200 OK): İstenen simülasyonun ayrıntılarını içeren bir JSON nesnesi döndürür.

    {
  "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
}
Sistem metriklerini ve yapılandırmasını alma

Bu uç noktalar, simülasyon altyapısının mevcut yükü ve yapılandırması hakkında bilgi sağlar.

  • Çalışan simülasyon sayısını alma: Çalışan simülasyonların sayısını döndürür.

    • Uç nokta:

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

    • Başarılı yanıt (200 OK):

      {
  "count": 0
}

  • Get max concurrent VMs: Aynı anda çalışan sanal makinelerin yapılandırılmış maksimum sayısını döndürür.

    • Uç nokta:

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

    • Başarılı yanıt (200 OK):

      {
  "max_running_vms": 5
}