Praktische Methoden zur Beobachtbarkeit von Anwendungen mit generativer KI in JavaScript

1. Übersicht

Für Anwendungen mit generativer KI ist wie für alle anderen Anwendungen eine Beobachtbarkeitslösung erforderlich. Sind für generative KI spezielle Observability-Techniken erforderlich?

In diesem Lab erstellen Sie eine einfache Gen AI-Anwendung. Stellen Sie sie in Cloud Run bereit. Außerdem müssen Sie sie mit wichtigen Monitoring- und Logging-Funktionen ausstatten, indem Sie die Observability-Dienste und -Produkte von Google Cloud verwenden.

Lerninhalte

Anwendung schreiben, die Vertex AI mit dem Cloud Shell-Editor verwendet
Anwendungscode in GitHub speichern
gcloud CLI verwenden, um den Quellcode Ihrer Anwendung in Cloud Run bereitzustellen

Monitoring- und Logging-Funktionen in Ihre Anwendung mit generativer KI einbinden
Logbasierte Messwerte verwenden
Logging und Monitoring mit dem OpenTelemetry SDK implementieren
Informationen zum verantwortungsbewussten Umgang mit KI-Daten

2. Vorbereitung

Wenn Sie noch kein Google-Konto haben, müssen Sie ein neues Konto erstellen.

3. Projekt einrichten

Melden Sie sich mit Ihrem Google-Konto in der Google Cloud Console an.
Erstellen Sie ein neues Projekt oder verwenden Sie ein vorhandenes Projekt wieder. Notieren Sie sich die Projekt-ID des Projekts, das Sie gerade erstellt oder ausgewählt haben.
Aktivieren Sie die Abrechnung für das Projekt.
- Die Kosten für dieses Lab sollten weniger als 5 $betragen.
- Sie können die Schritte am Ende dieses Labs ausführen, um Ressourcen zu löschen und so weitere Kosten zu vermeiden.
- Neue Nutzer haben Anspruch auf die kostenlose Testversion mit einem Guthaben von 300$.
Prüfen Sie in der Cloud-Abrechnung unter Meine Projekte
- Wenn in Ihrem neuen Projekt in der Spalte Billing account der Wert Billing is disabled angezeigt wird:
  1. Klicken Sie in der Spalte Actions auf das Dreipunkt-Menü.
  2. Klicken Sie auf Abrechnung ändern.
  3. Wählen Sie das gewünschte Rechnungskonto aus.
- Wenn Sie an einer Live-Veranstaltung teilnehmen, heißt das Konto wahrscheinlich Google Cloud Platform-Testrechnungskonto.

4. Cloud Shell-Editor vorbereiten

Rufen Sie den Cloud Shell-Editor auf. Wenn Sie die folgende Meldung erhalten, in der Sie aufgefordert werden, Cloud Shell zu autorisieren, gcloud mit Ihren Anmeldedaten aufzurufen, klicken Sie auf Autorisieren, um fortzufahren.
Terminalfenster öffnen
1. Klicken Sie auf das Dreistrich-Menü .
2. Klicken Sie auf Terminal.
3. Klicken Sie auf Neues Terminal
  .
Konfigurieren Sie im Terminal Ihre Projekt-ID:
```
gcloud config set project [PROJECT_ID]
```
Ersetzen Sie [PROJECT_ID] durch die ID Ihres Projekts. Wenn Ihre Projekt-ID beispielsweise lab-example-project lautet, sieht der Befehl so aus:
```
gcloud config set project lab-project-id-example
```
Wenn Sie die folgende Meldung erhalten, in der Sie aufgefordert werden, Ihre Anmeldedaten für die GCPI API anzugeben, klicken Sie auf Autorisieren, um fortzufahren.

Bei erfolgreicher Ausführung wird die folgende Meldung angezeigt:
```
Updated property [core/project].
```
Wenn Sie WARNING sehen und Do you want to continue (Y/N)? gefragt werden, haben Sie die Projekt-ID wahrscheinlich falsch eingegeben. Drücken Sie N, dann Enter und versuchen Sie, den Befehl gcloud config set project noch einmal auszuführen, nachdem Sie die richtige Projekt-ID gefunden haben.
(Optional) Wenn Sie Probleme haben, die Projekt-ID zu finden, führen Sie den folgenden Befehl aus, um die Projekt-ID aller Ihrer Projekte nach Erstellungszeit in absteigender Reihenfolge zu sehen:
```
gcloud projects list \
     --format='value(projectId,createTime)' \
     --sort-by=~createTime
```

5. Google APIs aktivieren

Aktivieren Sie im Terminal die für dieses Lab erforderlichen Google APIs:

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

Die Ausführung dieses Befehls kann einige Zeit in Anspruch nehmen. Wenn die Aktivierung erfolgreich war, erhalten Sie eine Meldung, die ungefähr so aussieht:

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

Wenn Sie eine Fehlermeldung erhalten, die mit ERROR: (gcloud.services.enable) HttpError accessing beginnt und Fehlerdetails wie unten enthält, wiederholen Sie den Befehl nach einer Verzögerung von 1 bis 2 Minuten.

"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. Gen AI-NodeJS-Anwendung erstellen

In diesem Schritt schreiben Sie den Code für eine einfache anfragebasierte Anwendung, die das Gemini-Modell verwendet, um 10 interessante Fakten über ein Tier Ihrer Wahl anzuzeigen. So erstellen Sie den Anwendungscode:

Erstellen Sie im Terminal das Verzeichnis codelab-o11y:
```
mkdir ~/codelab-o11y
```
Ändern Sie das aktuelle Verzeichnis in codelab-o11y:
```
cd ~/codelab-o11y
```
Initialisieren Sie package.json der NodeJS-Anwendung:
```
npm init -y
```
Installieren Sie das Paket fastify:
```
npm install fastify
```
Installieren Sie Cloud SDK-Pakete für die Authentifizierung und die Arbeit mit Vertex AI:
```
npm install google-auth-library @google-cloud/vertexai
```
Erstellen Sie eine index.js-Datei und öffnen Sie sie im Cloud Shell-Editor:
```
cloudshell edit index.js
```
Im Editorfenster über dem Terminal sollte jetzt eine leere Datei angezeigt werden. Ihr Bildschirm sollte nun in etwa so aussehen:

Kopieren Sie den folgenden Code und fügen Sie ihn in die geöffnete Datei index.js ein:

const { VertexAI } = require('@google-cloud/vertexai');
const { GoogleAuth } = require('google-auth-library');

let generativeModel;
const auth = new GoogleAuth();
auth.getProjectId().then(result => {
  const vertex = new VertexAI({ project: result });
  generativeModel = vertex.getGenerativeModel({
      model: 'gemini-1.5-flash'
  });
});

const fastify = require('fastify')();
const PORT = parseInt(process.env.PORT || '8080');

fastify.get('/', async function (request, reply) {
  const animal = request.query.animal || 'dog';
  const prompt = `Give me 10 fun facts about ${animal}. Return this as html without backticks.`
  const resp = await generativeModel.generateContent(prompt);
  const html = resp.response.candidates[0].content.parts[0].text;
  reply.type('text/html').send(html);
})

fastify.listen({ host: '0.0.0.0', port: PORT }, function (err, address) {
  if (err) {
    console.error(err);
    process.exit(1);
  }
  console.log(`codelab-genai: listening on ${address}`);
})

Nach einigen Sekunden wird Ihr Code automatisch im Cloud Shell Editor gespeichert.

Code der GenAI-Anwendung in Cloud Run bereitstellen

Führen Sie im Terminalfenster den Befehl aus, um den Quellcode der Anwendung in Cloud Run bereitzustellen.

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

Wenn Sie die folgende Aufforderung sehen, die Sie darüber informiert, dass mit dem Befehl ein neues Repository erstellt wird. Klicken Sie auf Enter.

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)?

Die Bereitstellung kann einige Minuten dauern. Nach Abschluss der Bereitstellung wird in etwa folgende Ausgabe angezeigt:

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

Kopieren Sie die angezeigte Cloud Run-Dienst-URL in einen separaten Tab oder ein separates Fenster in Ihrem Browser. Alternativ können Sie den folgenden Befehl im Terminal ausführen, um die Dienst-URL auszugeben, und dann bei gedrückter Ctrl auf die angezeigte URL klicken, um sie zu öffnen:
```
gcloud run services list \
     --format='value(URL)' \
     --filter='SERVICE:"codelab-o11y-service"'
```
Wenn die URL geöffnet wird, erhalten Sie möglicherweise einen 500-Fehler oder die folgende Meldung:
```
Sorry, this is just a placeholder...
```
Das bedeutet, dass die Bereitstellung der Dienste nicht abgeschlossen wurde. Warten Sie einige Sekunden und aktualisieren Sie dann die Seite. Am Ende sehen Sie einen Text, der mit Fun Dog Facts beginnt und 10 Fun Facts über Hunde enthält.

Interagieren Sie mit der Anwendung, um interessante Fakten über verschiedene Tiere zu erhalten. Hängen Sie dazu den Parameter animal an die URL an, z. B. ?animal=[ANIMAL], wobei [ANIMAL] ein Tiername ist. Hängen Sie beispielsweise ?animal=cat an, um 10 Funfacts über Katzen zu erhalten, oder ?animal=sea turtle, um 10 Funfacts über Meeresschildkröten zu erhalten.

7. Vertex API-Aufrufe prüfen

Durch die Überprüfung von Google API-Aufrufen erhalten Sie Antworten auf Fragen wie „Wer hat eine bestimmte API wann und wo aufgerufen?“. Die Überwachung ist wichtig, wenn Sie Fehler in Ihrer Anwendung beheben, den Ressourcenverbrauch untersuchen oder eine Software-Forensik durchführen.

Mit Audit-Logs können Sie Administrator- und Systemaktivitäten nachverfolgen sowie Aufrufe von API-Vorgängen zum Lesen und Schreiben von Daten protokollieren. Wenn Sie Vertex AI-Anfragen zum Generieren von Inhalten prüfen möchten, müssen Sie Audit-Logs vom Typ „Daten lesen“ in der Cloud Console aktivieren.

Klicken Sie auf die Schaltfläche unten, um die Seite „Audit-Logs“ in der Cloud Console zu öffnen.
Achten Sie darauf, dass auf der Seite das Projekt ausgewählt ist, das Sie für dieses Lab erstellt haben. Das ausgewählte Projekt wird oben links auf der Seite direkt neben dem Dreistrich-Menü angezeigt:

Wählen Sie bei Bedarf das richtige Projekt aus der Kombinationsbox aus.
Suchen Sie in der Tabelle Konfiguration für Audit-Logs zum Datenzugriff in der Spalte „Dienst“ nach dem Dienst Vertex AI API und wählen Sie den Dienst aus, indem Sie das Kästchen links neben dem Dienstnamen aktivieren.
Wählen Sie im Infobereich rechts den Audittyp „Daten lesen“ aus.
Klicken Sie auf Speichern.

Öffnen Sie die Dienst-URL, um Audit-Logs zu generieren. Aktualisieren Sie die Seite, während Sie den Wert des Parameters ?animal= ändern, um unterschiedliche Ergebnisse zu erhalten.

Audit-Logs ansehen

Klicken Sie auf die Schaltfläche unten, um die Seite „Log-Explorer“ in der Cloud Console zu öffnen:
Fügen Sie den folgenden Filter in den Bereich „Abfrage“ ein.
```
LOG_ID("cloudaudit.googleapis.com%2Fdata_access") AND
protoPayload.serviceName="aiplatform.googleapis.com"
```
Der Bereich „Abfrage“ ist ein Editor oben auf der Seite „Log-Explorer“:
Klicken Sie auf Abfrage ausführen.
Wählen Sie einen der Audit-Log-Einträge aus. Die Felder werden maximiert, damit Sie die im Log erfassten Informationen sehen können.
Sie können Details zum Vertex API-Aufruf sehen, einschließlich der verwendeten Methode und des verwendeten Modells. Außerdem können Sie die Identität des Aufrufers und die Berechtigungen sehen, die den Aufruf autorisiert haben.

8. Interaktionen mit generativer KI protokollieren

Sie finden keine API-Anfrageparameter oder Antwortdaten in Audit-Logs. Diese Informationen können jedoch für die Fehlerbehebung bei der Analyse von Anwendungen und Workflows wichtig sein. In diesem Schritt schließen wir diese Lücke, indem wir die Anwendungs-Logging-Funktion hinzufügen. Für das Logging wird die Standard-Logging-Methode von NodeJS console.log verwendet, um strukturierte Logs in die Standardausgabe zu schreiben. Bei dieser Methode wird die Funktion von Cloud Run genutzt, Informationen, die in die Standardausgabe geschrieben werden, automatisch zu erfassen und in Cloud Logging aufzunehmen. Damit die strukturierten Logs richtig erfasst werden, muss das gedruckte Log entsprechend formatiert sein. Folgen Sie der Anleitung unten, um unserer NodeJS-Anwendung Funktionen für strukturiertes Logging hinzuzufügen.

Kehren Sie in Ihrem Browser zum Fenster (oder Tab) „Cloud Shell“ zurück.
Öffnen Sie index.js im Terminal noch einmal:
```
cloudshell edit ~/codelab-o11y/index.js
```

So protokollieren Sie die Antwort des Modells:

Suchen Sie den Aufruf von await generativeModel.generateContent() (in Zeile 20).

Kopieren Sie den folgenden Code und fügen Sie ihn am Anfang der nächsten Zeile ein.

  console.log(JSON.stringify({
      severity: 'DEBUG',
      message: 'Content is generated',
      animal: animal,
      prompt: prompt,
      response: resp.response,
  }));

Die Handler-Funktion wird so geändert, dass console.log() aufgerufen wird, um die JSON-Struktur auszugeben, die den Richtlinien für die strukturierte Formatierung entspricht. Das Log erfasst den Tierparameter der Anfrage sowie den Prompt und die Antwort des Modells.

Nach einigen Sekunden werden Ihre Änderungen automatisch in Cloud Shell Editor gespeichert.

Code der GenAI-Anwendung in Cloud Run bereitstellen

Führen Sie im Terminalfenster den Befehl aus, um den Quellcode der Anwendung in Cloud Run bereitzustellen.

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

Wenn Sie die folgende Aufforderung sehen, die Sie darüber informiert, dass mit dem Befehl ein neues Repository erstellt wird. Klicken Sie auf Enter.

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)?

Die Bereitstellung kann einige Minuten dauern. Nach Abschluss der Bereitstellung wird in etwa folgende Ausgabe angezeigt:

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

Kopieren Sie die angezeigte Cloud Run-Dienst-URL in einen separaten Tab oder ein separates Fenster in Ihrem Browser. Alternativ können Sie den folgenden Befehl im Terminal ausführen, um die Dienst-URL auszugeben, und dann bei gedrückter Ctrl auf die angezeigte URL klicken, um sie zu öffnen:
```
gcloud run services list \
     --format='value(URL)' \
     --filter='SERVICE:"codelab-o11y-service"'
```
Wenn die URL geöffnet wird, erhalten Sie möglicherweise einen 500-Fehler oder die folgende Meldung:
```
Sorry, this is just a placeholder...
```
Das bedeutet, dass die Bereitstellung der Dienste nicht abgeschlossen wurde. Warten Sie einige Sekunden und aktualisieren Sie dann die Seite. Am Ende sehen Sie einen Text, der mit Fun Dog Facts beginnt und 10 Fun Facts über Hunde enthält.

Öffnen Sie die Dienst-URL, um Anwendungslogs zu generieren. Aktualisieren Sie die Seite, während Sie den Wert des Parameters ?animal= ändern, um unterschiedliche Ergebnisse zu erhalten.
So rufen Sie die Anwendungslogs auf:

Klicken Sie auf die Schaltfläche unten, um die Seite „Log-Explorer“ in der Cloud Console zu öffnen:
Fügen Sie den folgenden Filter in den Bereich „Abfrage“ (#2 in der Log-Explorer-Benutzeroberfläche) ein:
```
LOG_ID("run.googleapis.com%2Fstdout") AND
severity=DEBUG
```
Klicken Sie auf Abfrage ausführen.

Das Ergebnis der Abfrage enthält Protokolle mit dem Prompt und der Vertex AI-Antwort, einschließlich Sicherheitsbewertungen.

9. Interaktionen mit generativer KI zählen

Cloud Run schreibt verwaltete Messwerte, mit denen bereitgestellte Dienste überwacht werden können. Mit nutzerverwalteten Überwachungsstatistiken haben Sie mehr Kontrolle über Daten und Häufigkeit der Statistikaktualisierung. Um einen solchen Messwert zu implementieren, müssen Sie Code schreiben, der Daten erfasst und in Cloud Monitoring schreibt. Im nächsten (optionalen) Schritt erfahren Sie, wie Sie dies mit dem OpenTelemetry SDK implementieren.

In diesem Schritt wird eine Alternative zur Implementierung von Nutzermesswerten im Code gezeigt: logbasierte Messwerte. Mit logbasierten Messwerten können Sie Monitoring-Messwerte aus den Logeinträgen generieren, die Ihre Anwendung in Cloud Logging schreibt. Wir verwenden die Anwendungslogs, die wir im vorherigen Schritt implementiert haben, um einen logbasierten Messwert vom Typ „Zähler“ zu definieren. Mit diesem Messwert wird die Anzahl der erfolgreichen Aufrufe an die Vertex API gezählt.

Sehen Sie sich das Fenster des Log-Explorers an, das wir im vorherigen Schritt verwendet haben. Suchen Sie im Bereich „Abfrage“ nach dem Drop-down-Menü Aktionen und klicken Sie darauf, um es zu öffnen. Im Screenshot unten sehen Sie, wo sich das Menü befindet:
Wählen Sie im geöffneten Menü Messwert erstellen aus, um den Bereich Logbasierten Messwert erstellen zu öffnen.
So konfigurieren Sie einen neuen Zählermesswert im Bereich Logbasierten Messwert erstellen:
1. Legen Sie den Messwerttyp fest: Wählen Sie Zähler aus.
2. Legen Sie im Abschnitt Details die folgenden Felder fest:
  - Name des Logmesswerts: Legen Sie den Namen auf model_interaction_count fest. Für die Benennung gelten einige Einschränkungen. Weitere Informationen dazu finden Sie unter Fehlerbehebung.
  - Beschreibung: Geben Sie eine Beschreibung für den Messwert ein. z. B. Number of log entries capturing successful call to model inference..
  - Einheiten: Lassen Sie dieses Feld leer oder geben Sie die Zahl 1 ein.
3. Übernehmen Sie die Werte im Abschnitt Filterauswahl. Das Feld Build-Filter enthält denselben Filter, den wir zum Aufrufen von Anwendungslogs verwendet haben.
4. Optional: Fügen Sie ein Label hinzu, mit dem Sie die Anzahl der Anrufe für jedes Tier zählen können. HINWEIS: Dieses Label kann die Kardinalität von Messwerten erheblich erhöhen und wird nicht für den Einsatz in der Produktion empfohlen:
  1. Klicken Sie auf Label hinzufügen.
  2. Legen Sie im Abschnitt Labels die folgenden Felder fest:
    - Labelname: Legen Sie als Namen animal fest.
    - Beschreibung: Geben Sie die Beschreibung des Labels ein. Beispiel: Animal parameter.
    - Labeltyp: Wählen Sie STRING aus.
    - Feldname: Geben Sie jsonPayload.animal ein.
    - Regulärer Ausdruck: Lassen Sie das Feld leer.
  3. Klicken Sie auf Fertig.
5. Klicken Sie auf Messwert erstellen, um den Messwert zu erstellen.

Sie können auch einen logbasierten Messwert auf der Seite Logbasierte Messwerte mit dem gcloud logging metrics create CLI-Befehl oder mit der google_logging_metric Terraform-Ressource erstellen.

Öffnen Sie die Dienst-URL, um Messwertdaten zu generieren. Aktualisieren Sie die geöffnete Seite mehrmals, um mehrere Aufrufe des Modells zu generieren. Verwenden Sie wie zuvor verschiedene Tiere im Parameter.

Geben Sie die PromQL-Abfrage ein, mit der nach den logbasierten Messwertdaten gesucht werden soll. So geben Sie eine PromQL-Abfrage ein:

Klicken Sie auf die Schaltfläche unten, um die Seite „Metrics Explorer“ in der Cloud Console zu öffnen:
Klicken Sie in der Symbolleiste des Bereichs „Query Builder“ auf die Schaltfläche, deren Name entweder < > MQL oder < > PromQL ist. Die Position der Schaltfläche sehen Sie auf dem Bild unten.
Prüfen Sie, ob im Ein-/Aus-Button Sprache PromQL ausgewählt ist. Die Sprachschaltfläche befindet sich in derselben Symbolleiste, mit der Sie Ihre Abfrage formatieren können.
Geben Sie Ihre Abfrage in den Editor Abfragen ein:
```
sum(rate(logging_googleapis_com:user_model_interaction_count{monitored_resource="cloud_run_revision"}[${__interval}]))
```
Weitere Informationen zur Verwendung von PromQL finden Sie unter PromQL in Cloud Monitoring.
Klicken Sie auf Abfrage ausführen. Es wird ein Liniendiagramm wie in diesem Screenshot angezeigt:

Hinweis: Wenn der Ein/Aus-Schalter Automatisch ausführen aktiviert ist, wird der Button Abfrage ausführen nicht angezeigt.

10. Optional: OpenTelemetry für Monitoring und Tracing verwenden

Wie im vorherigen Schritt erwähnt, können Sie Messwerte mit dem OpenTelemetry (Otel) SDK implementieren. Die Verwendung von OTel in Mikrodienstarchitekturen wird empfohlen. In diesem Schritt wird Folgendes beschrieben:

OTel-Komponenten initialisieren, um Tracing und Monitoring der Anwendung zu unterstützen
OTel-Konfiguration mit Ressourcenmetadaten der Cloud Run-Umgebung füllen
Flask-Anwendung mit automatischen Tracing-Funktionen instrumentieren
Zählermesswert implementieren, um die Anzahl der erfolgreichen Modellaufrufe zu erfassen
Tracing mit Anwendungslogs korrelieren

Die empfohlene Architektur für Dienste auf Produktebene ist die Verwendung des OTel-Collectors zum Erfassen und Aufnehmen aller Observability-Daten für einen oder mehrere Dienste. Der Einfachheit halber wird im Code in diesem Schritt kein Collector verwendet. Stattdessen werden OTel-Exporte verwendet, mit denen Daten direkt in Google Cloud geschrieben werden.

OTel-Komponenten für Tracing und Messwert-Monitoring einrichten

Kehren Sie in Ihrem Browser zum Fenster (oder Tab) „Cloud Shell“ zurück.

Installieren Sie die für die automatische OpenTelemetry-Instrumentierung erforderlichen Pakete:

npm install @opentelemetry/sdk-node \
  @opentelemetry/api \
  @opentelemetry/auto-instrumentations-node \
  @opentelemetry/instrumentation-express \
  @opentelemetry/instrumentation-http \
  @opentelemetry/sdk-metrics \
  @opentelemetry/sdk-trace-node \
  @google-cloud/opentelemetry-cloud-trace-exporter \
  @google-cloud/opentelemetry-cloud-monitoring-exporter \
  @google-cloud/opentelemetry-resource-util

Erstellen Sie im Terminal eine neue Datei setup.js:
```
cloudshell edit ~/codelab-o11y/setup.js
```

Kopieren Sie den folgenden Code und fügen Sie ihn in den Editor ein, um OpenTelemetry-Tracing und ‑Monitoring einzurichten.

const opentelemetry = require("@opentelemetry/api");
const { registerInstrumentations } = require('@opentelemetry/instrumentation');
const { NodeTracerProvider } = require('@opentelemetry/sdk-trace-node');
const { MeterProvider, PeriodicExportingMetricReader } = require("@opentelemetry/sdk-metrics");
const { AlwaysOnSampler, SimpleSpanProcessor } = require('@opentelemetry/sdk-trace-base');
const { Resource } = require('@opentelemetry/resources');
const { ATTR_SERVICE_NAME } = require('@opentelemetry/semantic-conventions');
const { FastifyInstrumentation } = require('@opentelemetry/instrumentation-fastify');
const { HttpInstrumentation } = require('@opentelemetry/instrumentation-http');
const { TraceExporter } = require("@google-cloud/opentelemetry-cloud-trace-exporter");
const { MetricExporter } = require("@google-cloud/opentelemetry-cloud-monitoring-exporter");
const { GcpDetectorSync } = require("@google-cloud/opentelemetry-resource-util");

module.exports = { setupTelemetry };

function setupTelemetry() {
  const gcpResource = new Resource({
    [ATTR_SERVICE_NAME]: process.env.K_SERVICE,
  }).merge(new GcpDetectorSync().detect())

  const tracerProvider = new NodeTracerProvider({
    resource: gcpResource,
    sampler: new AlwaysOnSampler(),
    spanProcessors: [new SimpleSpanProcessor(new TraceExporter({
      // will export all resource attributes that start with "service."
      resourceFilter: /^service\./
    }))],
  });
  registerInstrumentations({
    tracerProvider: tracerProvider,
    instrumentations: [
      // Express instrumentation expects HTTP layer to be instrumented
      new HttpInstrumentation(),
      new FastifyInstrumentation(),
    ],
  });
  // Initialize the OpenTelemetry APIs to use the NodeTracerProvider bindings
  tracerProvider.register();

  const meterProvider = new MeterProvider({
    resource: gcpResource,
    readers: [new PeriodicExportingMetricReader({
      // Export metrics every second (default quota is 30,000 time series ingestion requests per minute)
      exportIntervalMillis: 1_000,
      exporter: new MetricExporter(),
    })],
  });
  opentelemetry.metrics.setGlobalMeterProvider(meterProvider);
}

Kehren Sie zum Terminal zurück und öffnen Sie index.js noch einmal:
```
cloudshell edit ~/codelab-o11y/index.js
```

Ersetzen Sie den Code durch die Version, die OpenTelemetry-Tracing und ‑Messwerterfassung initialisiert und den Leistungszähler bei jeder erfolgreichen Ausführung aktualisiert. Wenn Sie den Code aktualisieren möchten, löschen Sie den Inhalt der Datei und kopieren Sie dann den folgenden Code und fügen Sie ihn ein:

const { VertexAI } = require('@google-cloud/vertexai');
const { GoogleAuth } = require('google-auth-library');

let generativeModel, traceIdPrefix;
const auth = new GoogleAuth();
auth.getProjectId().then(result => {
  const vertex = new VertexAI({ project: result });
  generativeModel = vertex.getGenerativeModel({
        model: 'gemini-1.5-flash'
  });
  traceIdPrefix = `projects/${result}/traces/`;
});

// setup tracing and monitoring OTel providers
const { setupTelemetry }= require('./setup');
setupTelemetry();

const { trace, context } = require('@opentelemetry/api');
function getCurrentSpan() {
  const current_span = trace.getSpan(context.active());
  return {
      trace_id: current_span.spanContext().traceId,
      span_id: current_span.spanContext().spanId,
      flags: current_span.spanContext().traceFlags
  };
};

const opentelemetry = require("@opentelemetry/api");
const meter = opentelemetry.metrics.getMeter("genai-o11y/nodejs/workshop/example");
const counter = meter.createCounter("model_call_counter");

const fastify = require('fastify')();
const PORT = parseInt(process.env.PORT || '8080');

fastify.get('/', async function (request, reply) {
  const animal = request.query.animal || 'dog';
  const prompt = `Give me 10 fun facts about ${animal}. Return this as html without backticks.`
  const resp = await generativeModel.generateContent(prompt)
  const span = getCurrentSpan();
  console.log(JSON.stringify({
      severity: 'DEBUG',
      message: 'Content is generated',
      animal: animal,
      prompt: prompt,
      response: resp.response,
      "logging.googleapis.com/trace": traceIdPrefix + span.trace_id,
      "logging.googleapis.com/spanId": span.span_id,
  }));
  counter.add(1, { animal: animal });
  const html = resp.response.candidates[0].content.parts[0].text;
  reply.type('text/html').send(html);
});

fastify.listen({ host: '0.0.0.0', port: PORT }, function (err, address) {
  if (err) {
    console.error(err);
    process.exit(1);
  }
  console.log(`codelab-genai: listening on ${address}`);
});

Die Anwendung verwendet jetzt das OpenTelemetry SDK, um die Codeausführung mit Tracing zu instrumentieren und die Anzahl der erfolgreichen Ausführungen als Messwert zu erfassen. Die main()-Methode wird geändert, um die OpenTelemetry-Exporteure für Traces und Messwerte so einzurichten, dass sie direkt in Google Cloud Tracing und Monitoring geschrieben werden. Außerdem werden zusätzliche Konfigurationen vorgenommen, um die erfassten Traces und Messwerte mit Metadaten zur Cloud Run-Umgebung zu füllen. Die Funktion Handler() wird aktualisiert, um den Zähler für Messwerte jedes Mal zu erhöhen, wenn der Vertex AI API-Aufruf gültige Ergebnisse zurückgibt.

Nach einigen Sekunden werden Ihre Änderungen automatisch in Cloud Shell Editor gespeichert.

Code der GenAI-Anwendung in Cloud Run bereitstellen

Führen Sie im Terminalfenster den Befehl aus, um den Quellcode der Anwendung in Cloud Run bereitzustellen.

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

Wenn Sie die folgende Aufforderung sehen, die Sie darüber informiert, dass mit dem Befehl ein neues Repository erstellt wird. Klicken Sie auf Enter.

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)?

Die Bereitstellung kann einige Minuten dauern. Nach Abschluss der Bereitstellung wird in etwa folgende Ausgabe angezeigt:

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

Kopieren Sie die angezeigte Cloud Run-Dienst-URL in einen separaten Tab oder ein separates Fenster in Ihrem Browser. Alternativ können Sie den folgenden Befehl im Terminal ausführen, um die Dienst-URL auszugeben, und dann bei gedrückter Ctrl auf die angezeigte URL klicken, um sie zu öffnen:
```
gcloud run services list \
     --format='value(URL)' \
     --filter='SERVICE:"codelab-o11y-service"'
```
Wenn die URL geöffnet wird, erhalten Sie möglicherweise einen 500-Fehler oder die folgende Meldung:
```
Sorry, this is just a placeholder...
```
Das bedeutet, dass die Bereitstellung der Dienste nicht abgeschlossen wurde. Warten Sie einige Sekunden und aktualisieren Sie dann die Seite. Am Ende sehen Sie einen Text, der mit Fun Dog Facts beginnt und 10 Fun Facts über Hunde enthält.

Öffnen Sie die Dienst-URL, um Telemetriedaten zu generieren. Aktualisieren Sie die Seite, während Sie den Wert des Parameters ?animal= ändern, um unterschiedliche Ergebnisse zu erhalten.

Anwendungs-Traces ansehen

Klicken Sie auf die Schaltfläche unten, um die Seite „Trace Explorer“ in der Cloud Console zu öffnen:
Wählen Sie einen der letzten Traces aus. Sie sollten 5 oder 6 Spannen sehen, die wie im Screenshot unten aussehen.
Suchen Sie nach dem Span, der den Aufruf des Event-Handlers (die Methode fun_facts) nachverfolgt. Das ist der letzte Bereich mit dem Namen /.
Wählen Sie im Bereich Trace-Details die Option Logs und Ereignisse aus. Sie sehen Anwendungslogs, die mit diesem bestimmten Span korrelieren. Die Korrelation wird anhand der Trace- und Span-IDs im Trace und im Log erkannt. Sie sollten das Anwendungsprotokoll sehen, in dem der Prompt und die Antwort der Vertex API aufgezeichnet wurden.

Zählermesswert ansehen

Klicken Sie auf die Schaltfläche unten, um die Seite „Metrics Explorer“ in der Cloud Console zu öffnen:
Klicken Sie in der Symbolleiste des Bereichs „Query Builder“ auf die Schaltfläche, deren Name entweder < > MQL oder < > PromQL ist. Die Position der Schaltfläche sehen Sie auf dem Bild unten.
Prüfen Sie, ob im Ein-/Aus-Button Sprache PromQL ausgewählt ist. Die Sprachschaltfläche befindet sich in derselben Symbolleiste, mit der Sie Ihre Abfrage formatieren können.

Geben Sie Ihre Abfrage in den Editor Abfragen ein:

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

Klicken Sie auf Abfrage ausführen.Wenn der Ein/Aus-Button Automatisch ausführen aktiviert ist, wird der Button Abfrage ausführen nicht angezeigt.

11. (Optional) Vertrauliche Informationen aus Logs verschleiern

In Schritt 10 haben wir Informationen zur Interaktion der Anwendung mit dem Gemini-Modell protokolliert. Diese Informationen umfassten den Namen des Tieres, den eigentlichen Prompt und die Antwort des Modells. Das Speichern dieser Informationen im Log sollte sicher sein, das gilt jedoch nicht für viele andere Szenarien. Der Prompt kann personenbezogene oder anderweitig vertrauliche Informationen enthalten, die ein Nutzer nicht speichern möchte. Um dieses Problem zu beheben, können Sie die sensiblen Daten, die in Cloud Logging geschrieben werden, verschleiern. Um Codeänderungen zu minimieren, empfehlen wir die folgende Lösung.

Pub/Sub-Thema zum Speichern eingehender Logeinträge erstellen
Erstellen Sie eine Logs-Senke, die aufgenommene Logs an ein Pub/Sub-Thema weiterleitet.
Erstellen Sie eine Dataflow-Pipeline, die Logs ändert, die an ein Pub/Sub-Thema weitergeleitet werden. Gehen Sie dazu so vor:
1. Logeintrag aus dem Pub/Sub-Thema lesen
2. Die Nutzlast des Eintrags mit der DLP Inspection API auf vertrauliche Informationen prüfen
3. Entfernen Sie die vertraulichen Informationen in der Nutzlast mit einer der DLP-Methoden zum Entfernen.
4. Den verschleierten Logeintrag in Cloud Logging schreiben
Stellen Sie die Pipeline bereit.

12. Optional: Bereinigen

Um das Risiko zu vermeiden, dass für die im Codelab verwendeten Ressourcen und APIs Gebühren anfallen, empfiehlt es sich, nach Abschluss des Codelabs die Ressourcen zu bereinigen. Am einfachsten vermeiden Sie weitere Kosten, wenn Sie das für das Codelab erstellte Projekt löschen.

Achtung: Das Löschen eines Projekts hat folgende Auswirkungen:

– Alle Elemente im Projekt werden gelöscht. Wenn Sie für die Aufgaben in diesem Dokument ein bereits bestehendes Projekt verwendet haben und dieses löschen, werden auch alle anderen im Rahmen des Projekts erstellten Daten gelöscht.
– Benutzerdefinierte Projekt-IDs gehen verloren. Beim Erstellen dieses Projekts haben Sie möglicherweise eine benutzerdefinierte Projekt-ID erstellt, die Sie weiterhin verwenden möchten. Damit die URLs, die die Projekt-ID nutzen, zum Beispiel eine appspot.com-URL, erhalten bleiben, sollten Sie ausgewählte Ressourcen innerhalb des Projekts löschen, anstatt das gesamte Projekt.

Wenn Sie die von Ihnen erstellte Anwendung ausprobieren möchten, können Sie Zeit sparen und die Überschreitung von Projektkontingenten vermeiden, indem Sie das Projekt wiederverwenden.

Führen Sie den Befehl zum Löschen des Projekts im Terminal aus, um das Projekt zu löschen:

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

Wenn Sie Ihr Cloud-Projekt löschen, wird die Abrechnung für alle in diesem Projekt verwendeten Ressourcen und APIs beendet. Es sollte folgende Meldung angezeigt werden, wobei PROJECT_ID Ihre Projekt-ID ist:

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.

(Optional) Wenn Sie eine Fehlermeldung erhalten, sehen Sie in Schritt 5 nach, welche Projekt-ID Sie während des Labs verwendet haben. Ersetzen Sie den Befehl in der ersten Anleitung damit. Wenn Ihre Projekt-ID beispielsweise lab-example-project lautet, sieht der Befehl so aus:
```
gcloud projects delete lab-project-id-example --quiet
```

13. Glückwunsch

In diesem Lab haben Sie eine Anwendung mit generativer KI erstellt, die mit dem Gemini-Modell Vorhersagen trifft. Außerdem wurde die Anwendung mit wichtigen Monitoring- und Logging-Funktionen ausgestattet. Sie haben die Anwendung und Änderungen aus dem Quellcode in Cloud Run bereitgestellt. Anschließend können Sie die Leistung der Anwendung mit Google Cloud Observability-Produkten verfolgen, um die Zuverlässigkeit der Anwendung zu gewährleisten.

Wenn Sie an einer Studie zur Nutzerfreundlichkeit teilnehmen möchten, um die Produkte zu verbessern, mit denen Sie heute gearbeitet haben, registrieren Sie sich hier.

Hier sind einige Optionen, um weiterzulernen:

Codelab Gemini-basierte Chatanwendung in Cloud Run bereitstellen
Codelab Gemini-Funktionsaufrufe mit Cloud Run verwenden
Cloud Run Jobs Video Intelligence API zum Verarbeiten einer Videoszene nach der anderen verwenden
On-Demand-Workshop Google Kubernetes Engine Onboard
Zählermesswerte und Verteilungsmesswerte mit Anwendungsprotokollen konfigurieren
OTLP-Messwerte mit einem OpenTelemetry-Sidecar schreiben
Referenz zur Verwendung von OpenTelemetry in Google Cloud