Kullanıcı Rehberi

Sağlanan web demosunu kullanarak veya doğrudan REST API'yi çağırarak simülasyonlar ç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. Gerekirse bu dosyanın yolunu tanımlayabilirsiniz.

Çıkışların bulunduğu pakette, her simülasyonu kimliğine göre depolayan bir simulations dizini bulunur. Her simülasyon dizini, kopyalanan giriş dosyalarını içeren bir giriş klasörü ve bir çıkış klasörü içerir. Çıkış klasöründe bugreport, 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, gösterim 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 kullanıcıların Google Hesabı ile oturum açmasını gerektirir. Bu, Google Cloud projenizde yapılandırılan 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 gerekli izinleri verme (ör. Cloud Functions Çağırıcısı rolü (roles/cloudfunctions.invoker)) ile ilgili talimatlar için Cloud Functions'a erişimi yönetme başlıklı makaleyi inceleyin.

Kullanıcı İş Akışı

  1. Oturum açma: OAuth 2.0 süreci kullanılarak kimliği doğrulanmış Google Hesabınızla oturum açarsınız.
  2. Simülasyonları görüntüleme: Ana sayfada, tüm yürütme bilgilerini içeren Firestore veritabanı sorgulanarak geçmiş ve mevcut tüm simülasyonlar listelenir.
  3. Simülasyon oluşturma: Sağ alt köşedeki + işlem düğmesini tıklayarak yeni bir simülasyon planlamak için bir forma gidersiniz. 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. Durumu izleme: Simülasyon listesi, yeni simülasyonun durumunu (PENDING, RUNNING, COMPLETED vb.) gösterecek şekilde güncellenir.
  5. Sonuçları görüntüleme: Simülasyon tamamlandıktan sonra oluşturulan raporları ve çıktıları görüntüleyebilirsiniz. Giriş dosyaları, çıkış raporları, günlükler, Logcat ve hata raporları Cloud Storage'da saklanır.
  6. Simülasyon silme: Planlanmış veya devam eden bir simülasyonu iptal edebilirsiniz.

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 Function'ın temel 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 jetonu ile kimliği doğrulanmalı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ğırma (Yerel ve KSA) API'yi yerel bir makineden veya Google Cloud dışı bir ortamdan çağırırken kullanıcı hesabı için alınmış Google tarafından verilmiş bir kimlik jetonu kullanmanız gerekir.

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

  • 2. Hizmet Hesabı Çağırma (Google Cloud İçinde) API'yi bir Google Cloud kaynağında (ör. Compute Engine sanal makinesi, başka bir Cloud Function veya Kubernetes kümesi) çağırırken kaynağın ekli hizmet hesabının kimliğini kullanmanız gerekir. 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 üstbilgisinde Bearer jetonu olarak ekleyin.

Uç noktalar

Cloud Telemetry Simulation yığınının kullanıcıya yönelik uç noktaları, simülasyon oluşturmanıza ve silmenize ya da 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-request

  • İstek metni:

    {
  "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 aracı Docker görüntüsünün etiketi (ör. "latest"). Önemli: Bu, altyapının izin verilen resim haritasında tanımlanan bir etiketle eşleşmelidir (ör. "latest", "stable"). Sistem, Terraform'da SHA256 haritası tanımlanmışsa bilinmeyen etiketleri reddeder.
    • file_path (dize): metrics_config.zip ve publisher_config.zip öğelerini içeren klasörün GCS paketindeki yolu.
    • instance_type (dize): Compute Engine makine türü. Bu tür, n1, n2 veya t2d serisi gibi iç içe sanallaştırmayı desteklemelidir. Daha fazla bilgi için iç içe 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 çalışacağı maksimum süre (saniye cinsinden).
    • max_report_count (tam sayı): Simülasyonun tamamlanacağı telemetri raporlarının sayısı.

  • Başarı Yanıtı (200 OK):

    { "id": "sim-a1b2c3d4e5f6" }

Simülasyon Silme

Bu uç nokta, bekleyen 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 metni:

    { "id": "sim-a1b2c3d4e5f6" }

  • Başarı Yanıtı (200 OK): Boş bir JSON nesnesi {}.

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.

1. Simülasyonları listeleme

Filtreleme ve sıralama desteğiyle birlikte, sayfalandırılmış bir simülasyon listesini alır.

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

  • Sorgu Parametreleri (tümü isteğe bağlıdır):

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

  • Örnek İstek:

    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ı 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"
}

2. 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ı 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
}

3. 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.

  • Get Running Count: Ç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ı Yanıtı (200 OK):

      {
  "count": 0
}

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

    • Uç nokta:

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

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

      {
  "max_running_vms": 5
}