Bu sayfa, Cloud Translation API ile çevrilmiştir.

Go'da üretken yapay zeka uygulamaları için pratik gözlemlenebilirlik teknikleri

1. Genel Bakış

Üretken yapay zeka uygulamaları da diğer uygulamalar gibi gözlemlenebilirlik gerektirir. Üretken yapay zeka için özel gözlemlenebilirlik teknikleri gerekli mi?

Bu laboratuvarda basit bir üretken yapay zeka uygulaması oluşturacaksınız. Cloud Run'a dağıtın. Ayrıca, Google Cloud gözlemlenebilirlik hizmetlerini ve ürünlerini kullanarak gerekli izleme ve günlük kaydı özellikleriyle donatın.

Öğrenecekleriniz

Cloud Shell Düzenleyici ile Vertex AI kullanan bir uygulama yazma
Uygulama kodunuzu GitHub'da depolama
Uygulamanızın kaynak kodunu Cloud Run'a dağıtmak için gcloud KSA'yı kullanın

Üretken yapay zeka uygulamanıza izleme ve günlük kaydı özellikleri ekleme
Günlük tabanlı metrikleri kullanma
Open Telemetry SDK'sı ile günlük kaydını ve izlemeyi uygulama
Sorumlu yapay zeka verileriyle ilgili analizler edinme

2. Ön koşullar

Google Hesabınız yoksa yeni bir hesap oluşturmanız gerekir.

3. Proje ayarlama

Google Hesabınızla Google Cloud Console'da oturum açın.
Yeni bir proje oluşturun veya mevcut bir projeyi yeniden kullanmayı seçin. Yeni oluşturduğunuz veya seçtiğiniz projenin proje kimliğini not edin.
Proje için faturalandırmayı etkinleştirin.
- Bu laboratuvarı tamamlamanın faturalandırma maliyeti 5 ABD dolarından az olmalıdır.
- Daha fazla ödeme alınmaması için bu laboratuvarın sonundaki adımları uygulayarak kaynakları silebilirsiniz.
- Yeni kullanıcılar 300 ABD doları tutarındaki ücretsiz deneme sürümünden yararlanabilir.
Cloud Faturalandırma'daki Projelerim bölümünde faturalandırmanın etkinleştirildiğini onaylayın
- Yeni projenizin Billing account sütununda Billing is disabled yazıyorsa:
  1. Actions sütunundaki üç noktayı tıklayın
  2. Faturalandırmayı değiştir'i tıklayın.
  3. Kullanmak istediğiniz faturalandırma hesabını seçin
- Canlı bir etkinliğe katılıyorsanız hesabın adı büyük olasılıkla Google Cloud Platform Deneme Sürümü Faturalandırma Hesabı şeklinde olacaktır.

4. Cloud Shell Düzenleyici'yi hazırlama

Cloud Shell Düzenleyici'ye gidin. Cloud Shell'in kimlik bilgilerinizle gcloud'u çağırması için yetkilendirilmesini isteyen aşağıdaki mesaj gösterilirse devam etmek üzere Yetkilendir'i tıklayın.
Terminal penceresini açma
1. Hamburger menüsünü tıklayın.
2. Terminal'i tıklayın.
3. Yeni Terminal
  'i tıklayın.
Terminalde proje kimliğinizi yapılandırın:
```
gcloud config set project [PROJECT_ID]
```
[PROJECT_ID] yerine projenizin kimliğini yazın. Örneğin, proje kimliğiniz lab-example-project ise komut şu şekilde olur:
```
gcloud config set project lab-project-id-example
```
gcloud'un GCPI API için kimlik bilgilerinizi istediğini belirten aşağıdaki mesajı görürseniz devam etmek üzere Yetkilendir'i tıklayın.

İşlem başarıyla tamamlandığında aşağıdaki mesajı görürsünüz:
```
Updated property [core/project].
```
WARNING görüyorsanız ve Do you want to continue (Y/N)? soruyorsanız proje kimliğini yanlış girdiğiniz muhtemeldir. Doğru proje kimliğini bulduktan sonra N, Enter tuşlarına basın ve gcloud config set project komutunu tekrar çalıştırmayı deneyin.
(İsteğe bağlı) Proje kimliğini bulmakta sorun yaşıyorsanız tüm projelerinizin proje kimliğini, oluşturma zamanına göre azalan düzende görmek için aşağıdaki komutu çalıştırın:
```
gcloud projects list \
     --format='value(projectId,createTime)' \
     --sort-by=~createTime
```

5. Google API'lerini etkinleştirme

Terminalde, bu laboratuvar için gerekli olan Google API'lerini etkinleştirin:

gcloud services enable \
     run.googleapis.com \
     cloudbuild.googleapis.com \
     aiplatform.googleapis.com \
     logging.googleapis.com \
     monitoring.googleapis.com \
     cloudtrace.googleapis.com

Bu komutun tamamlanması biraz zaman alacaktır. Sonunda şuna benzer bir başarılı mesaj gösterilir:

Operation "operations/acf.p2-73d90d00-47ee-447a-b600" finished successfully.

ERROR: (gcloud.services.enable) HttpError accessing ile başlayan ve aşağıdaki gibi hata ayrıntıları içeren bir hata mesajı alırsanız 1-2 dakika bekledikten sonra komutu tekrar deneyin.

"error": {
  "code": 429,
  "message": "Quota exceeded for quota metric 'Mutate requests' and limit 'Mutate requests per minute' of service 'serviceusage.googleapis.com' ...",
  "status": "RESOURCE_EXHAUSTED",
  ...
}

6. Üretken yapay zeka Go uygulaması oluşturma

Bu adımda, seçtiğiniz bir hayvanla ilgili 10 ilginç bilgi göstermek için Gemini modelini kullanan basit bir istek tabanlı uygulamanın kodunu yazacaksınız. Uygulama kodunu oluşturmak için aşağıdakileri yapın.

Terminalde codelab-o11y dizinini oluşturun:
```
mkdir ~/codelab-o11y
```
Mevcut dizini codelab-o11y olarak değiştirin:
```
cd ~/codelab-o11y
```
Go modüllerini başlatın:
```
go mod init codelab
```

Go için Vertex AI SDK'sını yükleyin:

go get cloud.google.com/go/vertexai/genai

Geçerli proje kimliğini almak için Go için Meta Veri Kitaplığı'nı yükleyin:
```
go get cloud.google.com/go/compute/metadata
```
setup.go dosyası oluşturun ve dosyayı Cloud Shell Düzenleyici'de açın:
```
cloudshell edit setup.go
```
Başlatma kodunu barındırmak için kullanılır. Düzenleyici penceresinde setup.go adlı yeni bir boş dosya görünür.

Aşağıdaki kodu kopyalayıp açılan setup.go dosyasına yapıştırın:

package main

import (
    "context"
    "os"

    "cloud.google.com/go/compute/metadata"
)

func projectID(ctx context.Context) (string, error) {
    var projectID = os.Getenv("GOOGLE_CLOUD_PROJECT")
    if projectID == "" {
           return metadata.ProjectIDWithContext(ctx)
    }
    return projectID, nil
}

Terminal penceresine dönün ve Cloud Shell Düzenleyici'de main.go dosyası oluşturmak ve açmak için aşağıdaki komutu çalıştırın:
```
cloudshell edit main.go
```
Terminalin üzerindeki düzenleyicide boş bir dosya görünür. Ekranınız aşağıdaki gibi görünür:

Aşağıdaki kodu kopyalayıp açılan main.go dosyasına yapıştırın:

package main

import (
    "context"
    "fmt"
    "net/http"
    "os"

    "cloud.google.com/go/vertexai/genai"
)

var model *genai.GenerativeModel

func main() {
    ctx := context.Background()
    projectID, err := projectID(ctx)
    if err != nil {
        return
    }

    var client *genai.Client
    client, err = genai.NewClient(ctx, projectID, "us-central1")
    if err != nil {
        return
    }
    defer client.Close()
       model = client.GenerativeModel("gemini-1.5-flash-001")
       http.HandleFunc("/", Handler)
       port := os.Getenv("PORT")
    if port == "" {
        port = "8080"
    }
    if err := http.ListenAndServe(":"+port, nil); err != nil {
        return
    }
}

func Handler(w http.ResponseWriter, r *http.Request) {
    animal := r.URL.Query().Get("animal")
    if animal == "" {
        animal = "dog"
    }

    prompt := fmt.Sprintf("Give me 10 fun facts about %s. Return the results as HTML without markdown backticks.", animal)
    resp, err := model.GenerateContent(r.Context(), genai.Text(prompt))
    if err != nil {
        w.WriteHeader(http.StatusTooManyRequests)
        return
    }

    if len(resp.Candidates) > 0 && len(resp.Candidates[0].Content.Parts) > 0 {
        htmlContent := resp.Candidates[0].Content.Parts[0]
        w.Header().Set("Content-Type", "text/html; charset=utf-8")
        fmt.Fprint(w, htmlContent)
    }
}

Cloud Shell Düzenleyici, birkaç saniye sonra kodunuzu otomatik olarak kaydeder.

Yapay zeka üretme uygulamasının kodunu Cloud Run'a dağıtma

Terminal penceresinde, uygulamanın kaynak kodunu Cloud Run'a dağıtmak için komutu çalıştırın.

gcloud run deploy codelab-o11y-service \
     --source="${HOME}/codelab-o11y/" \
     --region=us-central1 \
     --allow-unauthenticated

Aşağıdaki gibi bir istem görürseniz komutun yeni bir depo oluşturacağını bildiriyordur. Enter simgesini tıklayın.

Deploying from source requires an Artifact Registry Docker repository to store built containers.
A repository named [cloud-run-source-deploy] in region [us-central1] will be created.

Do you want to continue (Y/n)?

Yayınlama işlemi birkaç dakika sürebilir. Dağıtım işlemi tamamlandıktan sonra aşağıdaki gibi bir çıkış görürsünüz:

Service [codelab-o11y-service] revision [codelab-o11y-service-00001-t2q] has been deployed and is serving 100 percent of traffic.
Service URL: https://codelab-o11y-service-12345678901.us-central1.run.app

Görüntülenen Cloud Run hizmet URL'sini tarayıcınızdaki ayrı bir sekmeye veya pencereye kopyalayın. Alternatif olarak, hizmet URL'sini yazdırmak için terminalde aşağıdaki komutu çalıştırın ve Ctrl tuşunu basılı tutarken gösterilen URL'yi tıklayarak URL'yi açın:
```
gcloud run services list \
     --format='value(URL)' \
     --filter='SERVICE:"codelab-o11y-service"'
```
URL açıldığında 500 hatası alabilir veya şu mesajı görebilirsiniz:
```
Sorry, this is just a placeholder...
```
Bu, hizmetlerin dağıtımı tamamlanmadığı anlamına gelir. Birkaç dakika bekleyip sayfayı yenileyin. Sonunda, Köpekler Hakkında İlginç Bilgiler ile başlayan ve köpeklerle ilgili 10 ilginç bilgi içeren bir metin görürsünüz.

Farklı hayvanlar hakkında eğlenceli bilgiler edinmek için uygulamayla etkileşim kurmayı deneyin. Bunu yapmak için URL'ye animal parametresini ekleyin. Örneğin, [ANIMAL] bir hayvan adıysa ?animal=[ANIMAL]. Örneğin, kediler hakkında 10 ilginç bilgi almak için ?animal=cat, deniz kaplumbağaları hakkında 10 ilginç bilgi almak için ?animal=sea turtle ekleyin.

7. Vertex API çağrılarınızı denetleme

Google API çağrılarının denetlenmesi, "Belirli bir API'yi kim, nerede ve ne zaman çağırıyor?" gibi soruların yanıtlarını sağlar. Uygulamanızda sorun giderirken, kaynak tüketimini araştırırken veya yazılım adli analizi yaparken denetim yapmak önemlidir.

Denetleme günlükleri, yönetim ve sistem etkinliklerini izlemenize ve "veri okuma" ve "veri yazma" API işlemlerine yönelik çağrıları kaydetmenize olanak tanır. İçerik oluşturmak için Vertex AI isteklerini denetlemek istiyorsanız Cloud Console'da "Veri Okuma" denetleme günlüklerini etkinleştirmeniz gerekir.

Cloud Console'da Denetleme Günlükleri sayfasını açmak için aşağıdaki düğmeyi tıklayın
Sayfada, bu laboratuvar için oluşturduğunuz projenin seçili olduğundan emin olun. Seçilen proje, sayfanın sol üst köşesinde hamburger menüsünün hemen yanında gösterilir:

Gerekirse, açılır listeden doğru projeyi seçin.
Veri erişimi denetim günlükleri yapılandırması tablosunda, Hizmet sütununda Vertex AI API hizmetini bulun ve hizmet adının solunda bulunan onay kutusunu işaretleyerek hizmeti seçin.
Sağdaki bilgi panelinde "Veri Okuma" denetim türünü seçin.
Kaydet'i tıklayın.

Denetleme günlükleri oluşturmak için hizmet URL'sini açın. Farklı sonuçlar almak için ?animal= parametresinin değerini değiştirirken sayfayı yenileyin.

Denetleme günlüklerini keşfetme

Cloud Console'da Günlük Gezgini sayfasını açmak için aşağıdaki düğmeyi tıklayın:
Aşağıdaki filtreyi Sorgu bölmesine yapıştırın.
```
LOG_ID("cloudaudit.googleapis.com%2Fdata_access") AND
protoPayload.serviceName="aiplatform.googleapis.com"
```
Sorgu bölmesi, Günlük Gezgini sayfasının üst kısmında bulunan bir düzenleyicidir:
Sorguyu çalıştır'ı tıklayın.
Denetleme günlük girişlerinden birini seçin ve günlükte yakalanan bilgileri incelemek için alanları genişletin.
Kullanılan yöntem ve model de dahil olmak üzere Vertex API çağrısıyla ilgili ayrıntıları görebilirsiniz. Ayrıca, çağrıyı başlatanın kimliğini ve hangi izinlerin çağrıyı yetkilendirdiğini de görebilirsiniz.

8. Üretken yapay zeka ile etkileşimleri günlüğe kaydetme

Denetleme günlüklerinde API istek parametreleri veya yanıt verileri bulunmaz. Ancak bu bilgiler, uygulama ve iş akışı analiziyle ilgili sorunları gidermek için önemli olabilir. Bu adımda, uygulama günlüğü ekleyerek bu boşluğu dolduruyoruz. Günlük kaydı, yapılandırılmış günlük yazmak için standart Go log/slog paketini kullanır. log/slog paketi, Google Cloud'a günlük yazmayı bilmiyor. Standart çıkışa yazma işlemini destekler. Ancak Cloud Run, standart çıkışa yazdırılan bilgileri yakalayıp Cloud Logging'e otomatik olarak beslemeyi sunar. Yapılandırılmış günlüklerin doğru şekilde yakalanması için basılı günlük uygun şekilde biçimlendirilmelidir. Go uygulamamıza yapılandırılmış günlük kaydı özellikleri eklemek için aşağıdaki talimatları uygulayın.

Tarayıcınızdaki "Cloud Shell" penceresine (veya sekmesine) dönün.
Terminalde setup.go dosyasını yeniden açın:
```
cloudshell edit ~/codelab-o11y/setup.go
```

Kodu, günlük kaydını ayarlayan sürümle değiştirin. Kodu değiştirmek için dosyanın içeriğini silin, ardından aşağıdaki kodu kopyalayıp düzenleyiciye yapıştırın:

package main

import (
	"context"
	"os"
	"log/slog"
	"cloud.google.com/go/compute/metadata"
)

func projectID(ctx context.Context) (string, error) {
    var projectID = os.Getenv("GOOGLE_CLOUD_PROJECT")
    if projectID == "" {
           return metadata.ProjectIDWithContext(ctx)
    }
    return projectID, nil
}

func setupLogging() {
    opts := &slog.HandlerOptions{
        Level: slog.LevelDebug,
        ReplaceAttr: func(group []string, a slog.Attr) slog.Attr {
            switch a.Key {
            case slog.LevelKey:
                a.Key = "severity"
                if level := a.Value.Any().(slog.Level); level == slog.LevelWarn {
                    a.Value = slog.StringValue("WARNING")
                }
            case slog.MessageKey:
                a.Key = "message"
            case slog.TimeKey:
                a.Key = "timestamp"
            }
            return a
        },
    }
    jsonHandler := slog.NewJSONHandler(os.Stdout, opts)
    slog.SetDefault(slog.New(jsonHandler))
}

Terminale dönüp main.go dosyasını yeniden açın:
```
cloudshell edit ~/codelab-o11y/main.go
```

Uygulama kodunu, modelle etkileşimi günlüğe kaydeden sürümle değiştirin. Kodu değiştirmek için dosyanın içeriğini silin, ardından aşağıdaki kodu kopyalayıp düzenleyiciye yapıştırın:

package main

import (
    "context"
    "fmt"
    "net/http"
    "os"

    "encoding/json"
    "log/slog"

    "cloud.google.com/go/vertexai/genai"
)

var model *genai.GenerativeModel

func main() {
    ctx := context.Background()
    projectID, err := projectID(ctx)
    if err != nil {
        return
    }

    setupLogging()

    var client *genai.Client
    client, err = genai.NewClient(ctx, projectID, "us-central1")
    if err != nil {
        slog.ErrorContext(ctx, "Failed to marshal response to JSON", slog.Any("error", err))
        os.Exit(1)
    }
    defer client.Close()
    model = client.GenerativeModel("gemini-1.5-flash-001")
    http.HandleFunc("/", Handler)
    port := os.Getenv("PORT")
    if port == "" {
        port = "8080"
    }
    if err := http.ListenAndServe(":"+port, nil); err != nil {
        slog.ErrorContext(ctx, "Failed to start the server", slog.Any("error", err))
        os.Exit(1)
    }
}

func Handler(w http.ResponseWriter, r *http.Request) {
    animal := r.URL.Query().Get("animal")
    if animal == "" {
        animal = "dog"
    }

    prompt := fmt.Sprintf("Give me 10 fun facts about %s. Return the results as HTML without markdown backticks.", animal)
    resp, err := model.GenerateContent(r.Context(), genai.Text(prompt))
    if err != nil {
        w.WriteHeader(http.StatusTooManyRequests)
        return
    }

    jsonBytes, err := json.Marshal(resp)
    if err != nil {
        slog.Error("Failed to marshal response to JSON", slog.Any("error", err))
    } else {
        slog.DebugContext(r.Context(), "content is generated", slog.String("animal", animal),
            slog.String("prompt", prompt), slog.String("response", string(jsonBytes)))
    }

    if len(resp.Candidates) > 0 && len(resp.Candidates[0].Content.Parts) > 0 {
        htmlContent := resp.Candidates[0].Content.Parts[0]
        w.Header().Set("Content-Type", "text/html; charset=utf-8")
        fmt.Fprint(w, htmlContent)
    }
}

Günlük kaydı, günlükleri stdout adresine yazdıracak şekilde yapılandırılır. Burada günlükler Cloud Run günlük kaydı aracısı tarafından toplanır ve Cloud Logging'e eşzamansız olarak aktarılır. main() işlevi, Go standart yapılandırılmış günlüğünü yapılandırılmış biçimlendirme kurallarına uyan JSON şemasını kullanacak şekilde ayarlayacak şekilde değiştirildi. Tüm return ifadeleri, çıkmadan önce hata günlükleri yazan kodla değiştirilir. Handler() işlevi, Vertex AI API çağrısından yanıt alırken yapılandırılmış günlük yazacak şekilde donatılmıştır. Günlük, isteğin hayvan parametresini, modelin istem ve yanıtını yakalar.

Cloud Shell Düzenleyici, birkaç saniye sonra değişikliklerinizi otomatik olarak kaydeder.

Yapay zeka üretme uygulamasının kodunu Cloud Run'a dağıtma

Terminal penceresinde, uygulamanın kaynak kodunu Cloud Run'a dağıtmak için komutu çalıştırın.

gcloud run deploy codelab-o11y-service \
     --source="${HOME}/codelab-o11y/" \
     --region=us-central1 \
     --allow-unauthenticated

Aşağıdaki gibi bir istem görürseniz komutun yeni bir depo oluşturacağını bildiriyordur. Enter simgesini tıklayın.

Deploying from source requires an Artifact Registry Docker repository to store built containers.
A repository named [cloud-run-source-deploy] in region [us-central1] will be created.

Do you want to continue (Y/n)?

Yayınlama işlemi birkaç dakika sürebilir. Dağıtım işlemi tamamlandıktan sonra aşağıdaki gibi bir çıkış görürsünüz:

Service [codelab-o11y-service] revision [codelab-o11y-service-00001-t2q] has been deployed and is serving 100 percent of traffic.
Service URL: https://codelab-o11y-service-12345678901.us-central1.run.app

Görüntülenen Cloud Run hizmet URL'sini tarayıcınızdaki ayrı bir sekmeye veya pencereye kopyalayın. Alternatif olarak, hizmet URL'sini yazdırmak için terminalde aşağıdaki komutu çalıştırın ve Ctrl tuşunu basılı tutarken gösterilen URL'yi tıklayarak URL'yi açın:
```
gcloud run services list \
     --format='value(URL)' \
     --filter='SERVICE:"codelab-o11y-service"'
```
URL açıldığında 500 hatası alabilir veya şu mesajı görebilirsiniz:
```
Sorry, this is just a placeholder...
```
Bu, hizmetlerin dağıtımı tamamlanmadığı anlamına gelir. Birkaç dakika bekleyip sayfayı yenileyin. Sonunda, Köpekler Hakkında İlginç Bilgiler ile başlayan ve köpeklerle ilgili 10 ilginç bilgi içeren bir metin görürsünüz.

Uygulama günlükleri oluşturmak için hizmet URL'sini açın. Farklı sonuçlar almak için ?animal= parametresinin değerini değiştirirken sayfayı yenileyin.
Uygulama günlüklerini görmek için şunları yapın:

Cloud Console'da Günlük gezgini sayfasını açmak için aşağıdaki düğmeyi tıklayın:
Aşağıdaki filtreyi sorgu bölmesine (Günlük gezgini arayüzünde 2. öğe) yapıştırın:
```
LOG_ID("run.googleapis.com%2Fstdout") AND
severity=DEBUG
```
Sorguyu çalıştır'ı tıklayın.

Sorgunun sonucu, istemi ve güvenlik derecelendirmelerini içeren Vertex AI yanıtını içeren günlükleri gösterir.

9. Üretken yapay zeka ile etkileşimleri sayma

Cloud Run, dağıtılan hizmetleri izlemek için kullanılabilecek yönetilen metrikler yazar. Kullanıcı tarafından yönetilen izleme metrikleri, veriler ve metrik güncellemesinin sıklığı üzerinde daha fazla kontrol sağlar. Bu tür bir metriği uygulamak için verileri toplayıp Cloud Monitoring'e yazan bir kod yazmanız gerekir. OpenTelemetry SDK'sını kullanarak uygulama yöntemi için sonraki (isteğe bağlı) adıma bakın.

Bu adımda, kullanıcı metriğini koda uygulamanın alternatifi olan günlüğe dayalı metrikler gösterilmektedir. Günlüğe dayalı metrikler, uygulamanızın Cloud Logging'e yazdığı günlük girişlerinden izleme metrikleri oluşturmanıza olanak tanır. Tür sayıcı türüne sahip günlük tabanlı bir metrik tanımlamak için önceki adımda uyguladığımız uygulama günlüklerini kullanacağız. Metrik, Vertex API'ye yapılan başarılı çağrıların sayısını sayar.

Önceki adımda kullandığımız Günlük gezgini penceresine bakın. Sorgu bölmesinin altında İşlemler açılır menüsünü bulun ve açmak için tıklayın. Menüyü bulmak için aşağıdaki ekran görüntüsüne bakın:
Açılan menüde Günlüğe dayalı metrik oluştur panelini açmak için Metrik oluştur'u seçin.
Günlük tabanlı metrik oluştur panelinde yeni bir sayaç metriği yapılandırmak için aşağıdaki adımları uygulayın:
1. Metrik türünü ayarlayın: Sayaç'ı seçin.
2. Ayrıntılar bölümünde aşağıdaki alanları ayarlayın:
  - Günlük kaydı metriği adı: Adı model_interaction_count olarak ayarlayın. Bazı adlandırma kısıtlamaları geçerlidir. Ayrıntılar için adlandırma kısıtlamaları Sorun giderme bölümüne bakın.
  - Açıklama: Metrik için bir açıklama girin. Örneğin, Number of log entries capturing successful call to model inference.
  - Birimler: Bu alanı boş bırakın veya 1 rakamını ekleyin.
3. Filtre seçimi bölümündeki değerleri olduğu gibi bırakın. Derleme filtresi alanının, uygulama günlüklerini görmek için kullandığımız filtreyle aynı olduğunu unutmayın.
4. (İsteğe bağlı) Her hayvan için yapılan arama sayısını saymanıza yardımcı olacak bir etiket ekleyin. NOT: Bu etiket, metriğin kardinalitesini büyük ölçüde artırma potansiyeline sahiptir ve üretimde kullanılması önerilmez:
  1. Etiket ekle'yi tıklayın.
  2. Etiketler bölümünde aşağıdaki alanları ayarlayın:
    - Etiket adı: Adı animal olarak ayarlayın.
    - Açıklama: Etiketin açıklamasını girin. Örneğin, Animal parameter.
    - Etiket türü: STRING öğesini seçin.
    - Alan adı: jsonPayload.animal yazın.
    - Normal ifade: Boş bırakın.
  3. Bitti'yi tıklayın
5. Metriği oluşturmak için Metrik oluştur'u tıklayın.

Günlük tabanlı metrikler sayfasından gcloud logging metrics create CLI komutunu veya google_logging_metric Terraform kaynağını kullanarak da günlük tabanlı metrik oluşturabilirsiniz.

Metrik verileri oluşturmak için hizmet URL'sini açın. Modele birden fazla çağrı yapmak için açılan sayfayı birkaç kez yenileyin. Önceki gibi, parametrede farklı hayvanlar kullanmayı deneyin.

Günlük tabanlı metrik verilerini aramak için PromQL sorgusunu girin. PromQL sorgusu girmek için aşağıdakileri yapın:

Cloud Console'da Metrik Gezgini sayfasını açmak için aşağıdaki düğmeyi tıklayın:
Sorgu oluşturucu bölmesinin araç çubuğunda, adı < > MQL veya < > PromQL olan düğmeyi seçin. Düğmenin konumu için aşağıdaki resme bakın.
Dil açma/kapatma düğmesinde PromQL'nin seçili olduğunu doğrulayın. Dil değiştirme düğmesi, sorgunuzu biçimlendirmenize olanak tanıyan aynı araç çubuğunda bulunur.
Sorgunuzu Sorgular düzenleyicisine girin:
```
sum(rate(logging_googleapis_com:user_model_interaction_count{monitored_resource="cloud_run_revision"}[${__interval}]))
```
PromQL'yi kullanma hakkında daha fazla bilgi için Cloud Monitoring'de PromQL başlıklı makaleyi inceleyin.
Sorgu Çalıştır'ı tıklayın. Bu ekran görüntüsüne benzer bir çizgi grafik görürsünüz:

Otomatik çalıştırma açma/kapatma düğmesi etkinleştirildiğinde Sorguyu çalıştır düğmesinin gösterilmediğini unutmayın.

10. (İsteğe bağlı) İzleme ve izleme için Open Telemetry'yi kullanma

Önceki adımda belirtildiği gibi, OpenTelemetry (Otel) SDK'sını kullanarak metrikleri uygulamak mümkündür. Mikro hizmet mimarilerinde OTel kullanılması önerilir. Bu adımda aşağıdakiler açıklanmaktadır:

Uygulamanın izlenmesini ve izlenmesini desteklemek için OTel bileşenlerini başlatma
OTel yapılandırmasını Cloud Run ortamının kaynak meta verileriyle doldurma
Flask uygulamasına otomatik izleme özellikleri ekleme
Birkaç başarılı model çağrısını izlemek için bir sayaç metriği uygulama
İzlemeyi uygulama günlükleriyle ilişkilendirme

Ürün düzeyindeki hizmetler için önerilen mimari, bir veya daha fazla hizmete ait tüm gözlemlenebilirlik verilerini toplamak ve beslemek için OTel toplayıcı'yı kullanmaktır. Bu adımdaki kod, basitlik açısından toplayıcıyı kullanmaz. Bunun yerine, verileri doğrudan Google Cloud'a yazan OTel dışa aktarma işlemlerini kullanır.

İzleme ve metrik izleme için OTel bileşenlerini ayarlama

Tarayıcınızdaki "Cloud Shell" penceresine (veya sekmesine) dönün.
Terminalde setup.go dosyasını yeniden açın:
```
cloudshell edit ~/codelab-o11y/setup.go
```

Kodu, OpenTelemetry izleme ve metrik toplama işlemini başlatan sürümle değiştirin. Kodu değiştirmek için dosyanın içeriğini silin, ardından aşağıdaki kodu kopyalayıp düzenleyiciye yapıştırın:

package main

import (
    "context"
    "errors"
    "fmt"
    "net/http"
    "os"

    "log/slog"

    "go.opentelemetry.io/contrib/detectors/gcp"
    "go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp"
    "go.opentelemetry.io/contrib/propagators/autoprop"
    "go.opentelemetry.io/otel"
    sdkmetric "go.opentelemetry.io/otel/sdk/metric"
    "go.opentelemetry.io/otel/sdk/resource"
    sdktrace "go.opentelemetry.io/otel/sdk/trace"
    semconv "go.opentelemetry.io/otel/semconv/v1.27.0"
    "go.opentelemetry.io/otel/trace"

    cloudmetric "github.com/GoogleCloudPlatform/opentelemetry-operations-go/exporter/metric"
    cloudtrace "github.com/GoogleCloudPlatform/opentelemetry-operations-go/exporter/trace"

    "cloud.google.com/go/compute/metadata"
)

var (
    projID string
)

func projectID(ctx context.Context) (string, error) {
    var projectID = os.Getenv("GOOGLE_CLOUD_PROJECT")
    if projectID == "" {
        return metadata.ProjectIDWithContext(ctx)
    }
    return projectID, nil
}

func setupLogging() {
    opts := &slog.HandlerOptions{
        Level: slog.LevelDebug,
        ReplaceAttr: func(group []string, a slog.Attr) slog.Attr {
            switch a.Key {
            case slog.LevelKey:
                a.Key = "severity"
                if level := a.Value.Any().(slog.Level); level == slog.LevelWarn {
                    a.Value = slog.StringValue("WARNING")
                }
            case slog.MessageKey:
                a.Key = "message"
            case slog.TimeKey:
                a.Key = "timestamp"
            }
            return a
        },
    }
    jsonHandler := slog.NewJSONHandler(os.Stdout, opts)
    instrumentedHandler := handlerWithSpanContext(jsonHandler)
    slog.SetDefault(slog.New(instrumentedHandler))
}

type spanContextLogHandler struct {
    slog.Handler
}

func handlerWithSpanContext(handler slog.Handler) *spanContextLogHandler {
    return &spanContextLogHandler{Handler: handler}
}

func (t *spanContextLogHandler) Handle(ctx context.Context, record slog.Record) error {
    if s := trace.SpanContextFromContext(ctx); s.IsValid() {
        trace := fmt.Sprintf("projects/%s/traces/%s", projID, s.TraceID())
        record.AddAttrs(
            slog.Any("logging.googleapis.com/trace", trace),
        )
        record.AddAttrs(
            slog.Any("logging.googleapis.com/spanId", s.SpanID()),
        )
        record.AddAttrs(
            slog.Bool("logging.googleapis.com/trace_sampled", s.TraceFlags().IsSampled()),
        )
    }
    return t.Handler.Handle(ctx, record)
}

func setupTelemetry(ctx context.Context) (shutdown func(context.Context) error, err error) {
    var shutdownFuncs []func(context.Context) error
    shutdown = func(ctx context.Context) error {
        var err error
        for _, fn := range shutdownFuncs {
            err = errors.Join(err, fn(ctx))
        }
        shutdownFuncs = nil
        return err
    }

    projID, err = projectID(ctx)
    if err != nil {
        err = errors.Join(err, shutdown(ctx))
        return
    }

    res, err2 := resource.New(
        ctx,
        resource.WithDetectors(gcp.NewDetector()),
        resource.WithTelemetrySDK(),
        resource.WithAttributes(semconv.ServiceNameKey.String(os.Getenv("K_SERVICE"))),
    )
    if err2 != nil {
        err = errors.Join(err2, shutdown(ctx))
        return
    }

    otel.SetTextMapPropagator(autoprop.NewTextMapPropagator())

    texporter, err2 := cloudtrace.New(cloudtrace.WithProjectID(projID))
    if err2 != nil {
        err = errors.Join(err2, shutdown(ctx))
        return
    }
    tp := sdktrace.NewTracerProvider(
        sdktrace.WithSampler(sdktrace.AlwaysSample()),
        sdktrace.WithResource(res),
        sdktrace.WithBatcher(texporter))
    shutdownFuncs = append(shutdownFuncs, tp.Shutdown)
    otel.SetTracerProvider(tp)

    mexporter, err2 := cloudmetric.New(cloudmetric.WithProjectID(projID))
    if err2 != nil {
        err = errors.Join(err2, shutdown(ctx))
        return
    }
    mp := sdkmetric.NewMeterProvider(
        sdkmetric.WithReader(sdkmetric.NewPeriodicReader(mexporter)),
        sdkmetric.WithResource(res),
    )
    shutdownFuncs = append(shutdownFuncs, mp.Shutdown)
    otel.SetMeterProvider(mp)

    return shutdown, nil
}

func registerHttpHandler(route string, handleFn http.HandlerFunc) {
    instrumentedHandler := otelhttp.NewHandler(otelhttp.WithRouteTag(route, handleFn), route)
    http.Handle(route, instrumentedHandler)
}

Terminale dönün ve go.mod dosyasındaki Go modülü tanımlarını güncellemek için aşağıdaki komutu çalıştırın:
```
go mod tidy
```
Terminale dönüp main.go dosyasını yeniden açın:
```
cloudshell edit ~/codelab-o11y/main.go
```

Mevcut kodu, HTTP izlemeyi yapan ve performans metriğini yazan sürümle değiştirin. Kodu değiştirmek için dosyanın içeriğini silin, ardından aşağıdaki kodu kopyalayıp düzenleyiciye yapıştırın:

package main

import (
    "context"
    "errors"
    "fmt"
    "net/http"
    "os"

    "encoding/json"
    "log/slog"

    "cloud.google.com/go/vertexai/genai"

    "go.opentelemetry.io/otel"
    "go.opentelemetry.io/otel/attribute"
    "go.opentelemetry.io/otel/metric"
)

var model *genai.GenerativeModel
var counter metric.Int64Counter

const scopeName = "genai-o11y/go/workshop/example"

func main() {
    ctx := context.Background()
    projectID, err := projectID(ctx)
    if err != nil {
        return
    }

    setupLogging()
    shutdown, err := setupTelemetry(ctx)
    if err != nil {
        slog.ErrorContext(ctx, "error setting up OpenTelemetry", slog.Any("error", err))
        os.Exit(1)
    }
    meter := otel.Meter(scopeName)
    counter, err = meter.Int64Counter("model_call_counter")
    if err != nil {
        slog.ErrorContext(ctx, "error setting up OpenTelemetry", slog.Any("error", err))
        os.Exit(1)
    }

    var client *genai.Client
    client, err = genai.NewClient(ctx, projectID, "us-central1")
    if err != nil {
        slog.ErrorContext(ctx, "Failed to marshal response to JSON", slog.Any("error", err))
        os.Exit(1)
    }
    defer client.Close()
    model = client.GenerativeModel("gemini-1.5-flash-001")

    registerHttpHandler("/", Handler)

    port := os.Getenv("PORT")
    if port == "" {
        port = "8080"
    }

    if err = errors.Join(http.ListenAndServe(":"+port, nil), shutdown(ctx)); err != nil {
        slog.ErrorContext(ctx, "Failed to start the server", slog.Any("error", err))
        os.Exit(1)
    }
}

func Handler(w http.ResponseWriter, r *http.Request) {
    animal := r.URL.Query().Get("animal")
    if animal == "" {
        animal = "dog"
    }

    prompt := fmt.Sprintf("Give me 10 fun facts about %s. Return the results as HTML without markdown backticks.", animal)
    resp, err := model.GenerateContent(r.Context(), genai.Text(prompt))
    if err != nil {
        w.WriteHeader(http.StatusTooManyRequests)
        return
    }
    jsonBytes, err := json.Marshal(resp)
    if err != nil {
        slog.ErrorContext(r.Context(), "Failed to marshal response to JSON", slog.Any("error", err))
    } else {
        slog.DebugContext(r.Context(), "content is generated", slog.String("animal", animal),
            slog.String("prompt", prompt), slog.String("response", string(jsonBytes)))
    }
    if len(resp.Candidates) > 0 && len(resp.Candidates[0].Content.Parts) > 0 {
        clabels := []attribute.KeyValue{attribute.Key("animal").String(animal)}
        counter.Add(r.Context(), 1, metric.WithAttributes(clabels...))
        htmlContent := resp.Candidates[0].Content.Parts[0]
        w.Header().Set("Content-Type", "text/html; charset=utf-8")
        fmt.Fprint(w, htmlContent)
    }
}

Uygulama artık kod yürütmeyi izlemeyle donatmak ve başarılı yürütme sayısını metrik olarak saymak için OpenTelemetry SDK'sını kullanıyor. main() yöntemi, OpenTelemetry dışa aktarıcılarını, izleme ve metriklerin doğrudan Google Cloud İzleme ve İzleme'ye yazması için ayarlayacak şekilde değiştirilir. Ayrıca, toplanan izlemeleri ve metrikleri Cloud Run ortamıyla ilgili meta verilerle doldurmak için ek yapılandırmalar gerçekleştirir. Handler() işlevi, Vertex AI API çağrısı geçerli sonuçlar döndürdüğünde metrik sayacını artıracak şekilde güncellenir.

Cloud Shell Düzenleyici, birkaç saniye sonra değişikliklerinizi otomatik olarak kaydeder.

Yapay zeka üretme uygulamasının kodunu Cloud Run'a dağıtma

Terminal penceresinde, uygulamanın kaynak kodunu Cloud Run'a dağıtmak için komutu çalıştırın.

gcloud run deploy codelab-o11y-service \
     --source="${HOME}/codelab-o11y/" \
     --region=us-central1 \
     --allow-unauthenticated

Aşağıdaki gibi bir istem görürseniz komutun yeni bir depo oluşturacağını bildiriyordur. Enter simgesini tıklayın.

Deploying from source requires an Artifact Registry Docker repository to store built containers.
A repository named [cloud-run-source-deploy] in region [us-central1] will be created.

Do you want to continue (Y/n)?

Yayınlama işlemi birkaç dakika sürebilir. Dağıtım işlemi tamamlandıktan sonra aşağıdaki gibi bir çıkış görürsünüz:

Service [codelab-o11y-service] revision [codelab-o11y-service-00001-t2q] has been deployed and is serving 100 percent of traffic.
Service URL: https://codelab-o11y-service-12345678901.us-central1.run.app

Görüntülenen Cloud Run hizmet URL'sini tarayıcınızdaki ayrı bir sekmeye veya pencereye kopyalayın. Alternatif olarak, hizmet URL'sini yazdırmak için terminalde aşağıdaki komutu çalıştırın ve Ctrl tuşunu basılı tutarken gösterilen URL'yi tıklayarak URL'yi açın:
```
gcloud run services list \
     --format='value(URL)' \
     --filter='SERVICE:"codelab-o11y-service"'
```
URL açıldığında 500 hatası alabilir veya şu mesajı görebilirsiniz:
```
Sorry, this is just a placeholder...
```
Bu, hizmetlerin dağıtımı tamamlanmadığı anlamına gelir. Birkaç dakika bekleyip sayfayı yenileyin. Sonunda, Köpekler Hakkında İlginç Bilgiler ile başlayan ve köpeklerle ilgili 10 ilginç bilgi içeren bir metin görürsünüz.

Telemetri verileri oluşturmak için hizmet URL'sini açın. Farklı sonuçlar almak için ?animal= parametresinin değerini değiştirirken sayfayı yenileyin.

Uygulama izlerini keşfetme

Cloud Console'da Trace Explorer sayfasını açmak için aşağıdaki düğmeyi tıklayın:
En son izlemelerden birini seçin. Aşağıdaki ekran görüntüsüne benzeyen 5 veya 6 span görmeniz gerekir.
Etkinlik işleyiciye yapılan çağrıyı izleyen aralığı (fun_facts yöntemi) bulun. / adlı son span olacaktır.
İzleme ayrıntıları bölmesinde Günlükler ve etkinlikler'i seçin. Bu belirli aralıkla ilişkili uygulama günlüklerini görürsünüz. İlişkilendirme, iz ve günlükteki iz ve aralık kimlikleri kullanılarak algılanır. İstemi yazan uygulama günlüğünü ve Vertex API'nin yanıtını görmeniz gerekir.

Sayaç metriğini keşfetme

Cloud Console'da Metrik Gezgini sayfasını açmak için aşağıdaki düğmeyi tıklayın:
Sorgu oluşturucu bölmesinin araç çubuğunda < > MQL veya < > PromQL adını taşıyan düğmeyi seçin. Düğmenin konumu için aşağıdaki resme bakın.
Dil açma/kapatma düğmesinde PromQL'nin seçili olduğunu doğrulayın. Dil değiştirme düğmesi, sorgunuzu biçimlendirmenize olanak tanıyan aynı araç çubuğunda bulunur.

Sorgunuzu Sorgular düzenleyicisine girin:

sum(rate(workload_googleapis_com:model_call_counter{monitored_resource="generic_task"}[${__interval}]))

Sorgu Çalıştır'ı tıklayın.Otomatik çalıştırma açma/kapatma düğmesi etkinleştirildiğinde Sorgu Çalıştır düğmesi gösterilmez.

11. (İsteğe bağlı) Günlüklerdeki karartılmış hassas bilgiler

10. adımda, uygulamanın Gemini modeliyle etkileşimi hakkındaki bilgileri günlüğe kaydettik. Bu bilgiler arasında hayvanın adı, gerçek istem ve modelin yanıtı yer alıyordu. Bu bilgilerin günlükte saklanması güvenli olsa da diğer birçok senaryo için bu durum geçerli olmayabilir. İstem, kullanıcının depolanmasını istemediği bazı kişisel veya hassas bilgileri içerebilir. Bu sorunu gidermek için Cloud Logging'a yazılan hassas verileri karartabilirsiniz. Kod değişikliklerini en aza indirmek için aşağıdaki çözüm önerilir.

Gelen günlük girişlerini depolamak için Pub/Sub konusu oluşturma
Alınan günlükleri PubSub konusuna yönlendiren bir günlük havuzu oluşturun.
Aşağıdaki adımları uygulayarak Pub/Sub konusuna yönlendirilen günlükleri değiştiren bir Dataflow ardışık düzeni oluşturun:
1. PubSub konusundaki bir günlük girişini okuma
2. DLP inceleme API'sini kullanarak girişin hassas bilgiler içeren yükü olup olmadığını kontrol edin.
3. VKÖ azaltma yöntemlerinden birini kullanarak yükündeki hassas bilgileri çıkartın.
4. Kodu karartılmış günlük girişini Cloud Logging'e yazma
Ardışık düzeni dağıtma

12. (İsteğe bağlı) Temizleme

Codelab'de kullanılan kaynaklar ve API'ler için ücret ödeme riskini önlemek amacıyla, lab'i tamamladıktan sonra temizlik yapmanız önerilir. Faturalandırılmanın önüne geçmenin en kolay yolu, kod laboratuvarının oluşturduğunuz projeyi silmektir.

Projeyi silmek için terminalde delete project komutunu çalıştırın:

PROJECT_ID=$(gcloud config get-value project)
gcloud projects delete ${PROJECT_ID} --quiet

Cloud projeniz silindiğinde, söz konusu projede kullanılan tüm kaynaklar ve API'ler için faturalandırma durdurulur. PROJECT_ID yerine proje kimliğinizin yazdığı şu mesajı görürsünüz:

Deleted [https://cloudresourcemanager.googleapis.com/v1/projects/PROJECT_ID].

You can undo this operation for a limited period by running the command below.
    $ gcloud projects undelete PROJECT_ID

See https://cloud.google.com/resource-manager/docs/creating-managing-projects for information on shutting down projects.

(İsteğe bağlı) Hata alırsanız laboratuvar sırasında kullandığınız proje kimliğini bulmak için 5. adıma bakın. Bu değeri, ilk talimattaki komutla değiştirin. Örneğin, proje kimliğiniz lab-example-project ise komut şu şekilde olur:
```
gcloud projects delete lab-project-id-example --quiet
```

13. Tebrikler

Bu laboratuvarda, tahmin yapmak için Gemini modelini kullanan bir üretken yapay zeka uygulaması oluşturdunuz. Ayrıca uygulamayı temel izleme ve günlük kaydı özellikleriyle donattı. Uygulamayı ve kaynak koddaki değişiklikleri Cloud Run'a dağıttınız. Ardından, uygulamanın güvenilirliğinden emin olmak için Google Cloud Observability ürünlerini kullanarak uygulamanın performansını izleyebilirsiniz.

Şu anda kullandığınız ürünleri iyileştirmek için bir kullanıcı deneyimi (UX) araştırmasına katılmak istiyorsanız buradan kaydolun.

Öğrenmeye devam etmek için kullanabileceğiniz bazı seçenekler:

Codelab Gemini destekli sohbet uygulamasını Cloud Run'a dağıtma
Codelab Cloud Run ile Gemini işlev çağrısını kullanma
Videoyu sahne sahne işlemek için Cloud Run Jobs Video Intelligence API'yi kullanma
İsteğe bağlı atölye Google Kubernetes Engine'e ilk katılım
Uygulama günlüklerini kullanarak karşı ve dağıtım metriklerini yapılandırma hakkında daha fazla bilgi edinin
OpenTelemetry yardımcı aracı kullanarak OTLP metrikleri yazma
Google Cloud'da Open Telemetry'nin kullanımıyla ilgili Referans

Go ile Open Telemetry izlemeleri ve metrikleri oluşturma