Técnicas práticas de observabilidade para aplicativos de IA generativa em JavaScript

1. Visão geral

Os aplicativos de IA generativa exigem capacidade de observação como qualquer outro. Há técnicas especiais de observabilidade necessárias para a IA generativa?

Neste laboratório, você vai criar um aplicativo simples de IA generativa. Implante no Cloud Run. Instrumente-o com recursos essenciais de monitoramento e geração de registros usando os produtos e serviços de observabilidade do Google Cloud.

O que você vai aprender

  • Escrever um aplicativo que usa a Vertex AI com o editor do Cloud Shell
  • Armazenar o código do aplicativo no GitHub
  • Use a CLI gcloud para implantar o código-fonte do aplicativo no Cloud Run.
  • Adicionar recursos de monitoramento e geração de registros ao seu aplicativo de IA generativa
  • Como usar métricas com base em registros
  • Implementar a geração de registros e o monitoramento com o SDK do Open Telemetry
  • Receba insights sobre o tratamento de dados de IA responsável

2. Pré-requisitos

Se você ainda não tiver uma Conta do Google, crie uma.

3. Configurar o projeto

  1. Faça login no Console do Google Cloud com sua Conta do Google.
  2. Crie um projeto ou reutilize um projeto existente. Anote o ID do projeto que você acabou de criar ou selecionar.
  3. Ative o faturamento do projeto.
    • A conclusão deste laboratório custa menos de US $5 em custos de faturamento.
    • Siga as etapas no final deste laboratório para excluir recursos e evitar mais cobranças.
    • Novos usuários podem aproveitar o teste sem custos financeiros de US$300.
  4. Confirme se o faturamento está ativado em Meus projetos no Cloud Billing
      .
    • Se o novo projeto mostrar Billing is disabled na coluna Billing account:
      1. Clique nos três pontos na coluna Actions.
      2. Clique em Mudar faturamento.
      3. Selecione a conta de faturamento que você quer usar.
    • Se você estiver participando de um evento ao vivo, a conta provavelmente será chamada de Conta de faturamento de avaliação do Google Cloud Platform.

4. Preparar o editor do Cloud Shell

  1. Acesse o editor do Cloud Shell. Se você receber a seguinte mensagem, solicitando a autorização do Cloud Shell para chamar o gcloud com suas credenciais, clique em Autorizar para continuar.
    Clique para autorizar o Cloud Shell
  2. Abrir janela do terminal
    1. Clique no menu de navegação Ícone do menu de navegação.
    2. Clique em Terminal.
    3. Clique em Novo terminal
      Abrir um novo terminal no editor do Cloud Shell.
  3. No terminal, configure o ID do projeto:
    gcloud config set project [PROJECT_ID]
    Substitua [PROJECT_ID] pelo ID do projeto. Por exemplo, se o ID do projeto for lab-example-project, o comando será:
    gcloud config set project lab-project-id-example
    Se você receber a seguinte mensagem informando que o gcloud está solicitando suas credenciais para a API GCPI, clique em Autorizar para continuar.
    Clique para autorizar o Cloud Shell
    Se a execução for bem-sucedida, você vai receber a seguinte mensagem:
    Updated property [core/project].
    Se você vir um WARNING e for perguntado Do you want to continue (Y/N)?, provavelmente inseriu o ID do projeto incorretamente. Pressione N, pressione Enter e tente executar o comando gcloud config set project novamente depois de encontrar o ID do projeto correto.
  4. (Opcional) Se você estiver com problemas para encontrar o ID do projeto, execute o comando a seguir para ver o ID de todos os seus projetos classificados por horário de criação em ordem decrescente:
    gcloud projects list \
     --format='value(projectId,createTime)' \
     --sort-by=~createTime

5. ativar as APIs do Google

No terminal, ative as APIs do Google necessárias para este laboratório:

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

Esse comando vai levar algum tempo para ser concluído. Eventualmente, ele vai produzir uma mensagem de sucesso semelhante a esta:

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

Se você receber uma mensagem de erro começando com ERROR: (gcloud.services.enable) HttpError accessing e contendo detalhes como abaixo, tente executar o comando novamente após um atraso de 1 a 2 minutos.

"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. Criar um aplicativo NodeJS de IA generativa

Nesta etapa, você vai escrever um código do aplicativo simples baseado em solicitações que usa o modelo do Gemini para mostrar 10 curiosidades sobre um animal à sua escolha. Faça o seguinte para criar o código do aplicativo.

  1. No terminal, crie o diretório codelab-o11y:
    mkdir ~/codelab-o11y
  2. Mude o diretório atual para codelab-o11y:
    cd ~/codelab-o11y
  3. Inicialize package.json do aplicativo NodeJS:
    npm init -y
  4. Instale o pacote fastify:
    npm install fastify
  5. Instale os pacotes do SDK Cloud para autenticação e trabalhe com a Vertex AI:
    npm install google-auth-library @google-cloud/vertexai
  6. Crie um arquivo index.js e abra no editor do Cloud Shell:
    cloudshell edit index.js
    Um arquivo vazio vai aparecer na janela do editor acima do terminal. A tela vai ficar assim:
    Mostrar o editor do Cloud Shell depois de começar a editar main.go
  7. Copie o código a seguir e cole no arquivo index.js aberto:
    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}`);
})
    Depois de alguns segundos, o Cloud Shell Editor vai salvar seu código automaticamente.

Implantar o código do aplicativo de IA generativa no Cloud Run

  1. Na janela do terminal, execute o comando para implantar o código-fonte do aplicativo no Cloud Run.
    gcloud run deploy codelab-o11y-service \
     --source="${HOME}/codelab-o11y/" \
     --region=us-central1 \
     --allow-unauthenticated
    Se você vir o prompt abaixo, informando que o comando vai criar um novo repositório. Clique em 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)?
    O processo de implantação pode levar alguns minutos. Depois que o processo de implantação for concluído, você verá uma saída como esta:
    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
  2. Copie o URL do serviço do Cloud Run exibido em uma guia ou janela separada do navegador. Como alternativa, execute o comando a seguir no terminal para imprimir o URL do serviço e clique no URL mostrado enquanto mantém pressionada a tecla Ctrl para abrir o URL:
    gcloud run services list \
     --format='value(URL)' \
     --filter='SERVICE:"codelab-o11y-service"'
    Ao abrir o URL, você pode receber um erro 500 ou ver a mensagem:
    Sorry, this is just a placeholder...
    Isso significa que os serviços não concluíram a implantação. Aguarde alguns instantes e atualize a página. No final, você vai encontrar um texto que começa com Curiosidades divertidas sobre cachorros e contém 10 curiosidades sobre cachorros.

Tente interagir com o aplicativo para receber curiosidades sobre diferentes animais. Para isso, adicione o parâmetro animal ao URL, como ?animal=[ANIMAL], em que [ANIMAL] é o nome de um animal. Por exemplo, adicione ?animal=cat para receber 10 curiosidades sobre gatos ou ?animal=sea turtle para receber 10 curiosidades sobre tartarugas marinhas.

7. Auditar suas chamadas da API Vertex

A auditoria de chamadas da API do Google responde a perguntas como "Quem chamou uma API específica, onde e quando?". A auditoria é importante ao solucionar problemas no aplicativo, investigar o consumo de recursos ou realizar análises forenses de software.

Com os registros de auditoria, é possível rastrear atividades administrativas e do sistema, além de registrar chamadas para operações de API de "leitura de dados" e "gravação de dados". Para auditar as solicitações da Vertex AI para gerar conteúdo, ative os registros de auditoria de "Leitura de dados" no console do Cloud.

  1. Clique no botão abaixo para abrir a página "Registros de auditoria" no console do Cloud

  2. Verifique se a página tem o projeto criado para este laboratório selecionado. O projeto selecionado aparece no canto superior esquerdo da página, logo abaixo do menu de hambúrguer:
    Menu suspenso de projetos do Console do Google Cloud
    . Se necessário, selecione o projeto correto na caixa de combinação.
  3. Na tabela Configuração dos registros de auditoria de acesso a dados, na coluna "Serviço", encontre o serviço Vertex AI API e marque a caixa de seleção à esquerda do nome dele.
    Selecionar a API Vertex AI
  4. No painel de informações à direita, selecione o tipo de auditoria "Leitura de dados".
    Verificar os registros de leitura de dados
  5. Clique em Salvar.

Para gerar registros de auditoria, abra o URL do serviço. Atualize a página enquanto muda o valor do parâmetro ?animal= para receber resultados diferentes.

Explorar registros de auditoria

  1. Clique no botão abaixo para abrir a página da Análise de registros no console do Cloud:

  2. Cole o filtro a seguir no painel "Consulta".
    LOG_ID("cloudaudit.googleapis.com%2Fdata_access") AND
protoPayload.serviceName="aiplatform.googleapis.com"
    O painel "Consulta" é um editor localizado perto da parte de cima da página da Análise de registros:
    Consultar registros de auditoria
  3. Clique em Executar consulta.
  4. Selecione uma das entradas de registro de auditoria e expanda os campos para inspecionar as informações capturadas no registro.
    Você pode conferir detalhes sobre a chamada de API Vertex, incluindo o método e o modelo usados. Também é possível conferir a identidade do invocador e quais permissões autorizaram a chamada.

8. Registrar interações com a IA generativa

Não é possível encontrar parâmetros de solicitação de API ou dados de resposta nos registros de auditoria. No entanto, essas informações podem ser importantes para solucionar problemas de aplicativos e análise de fluxo de trabalho. Nesta etapa, vamos preencher essa lacuna adicionando o registro de aplicativos. O registro usa o método padrão do NodeJS console.log para gravar registros estruturados na saída padrão. Esse método apresenta a capacidade do Cloud Run de capturar informações impressas na saída padrão e ingerir automaticamente no Cloud Logging. Para capturar corretamente os registros estruturados, o registro impresso precisa ser formatado de acordo. Siga as instruções abaixo para adicionar recursos de geração de registros estruturada ao aplicativo NodeJS.

  1. Volte para a janela (ou guia) "Cloud Shell" no navegador.
  2. No terminal, reabra index.js:
    cloudshell edit ~/codelab-o11y/index.js
  3. Siga estas etapas para registrar a resposta do modelo:
    1. Encontre a chamada para await generativeModel.generateContent() (na linha 20).
    2. Copie e cole o código abaixo no início da próxima linha.
        console.log(JSON.stringify({
      severity: 'DEBUG',
      message: 'Content is generated',
      animal: animal,
      prompt: prompt,
      response: resp.response,
  }));

A função de gerenciador é modificada para chamar console.log() e imprimir a estrutura JSON, cujo esquema segue as diretrizes de formatação estruturada. O registro captura o parâmetro "animal" da solicitação, o comando e a resposta do modelo.

Depois de alguns segundos, o Cloud Shell Editor salva as mudanças automaticamente.

Implantar o código do aplicativo de IA generativa no Cloud Run

  1. Na janela do terminal, execute o comando para implantar o código-fonte do aplicativo no Cloud Run.
    gcloud run deploy codelab-o11y-service \
     --source="${HOME}/codelab-o11y/" \
     --region=us-central1 \
     --allow-unauthenticated
    Se você vir o prompt abaixo, informando que o comando vai criar um novo repositório. Clique em 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)?
    O processo de implantação pode levar alguns minutos. Depois que o processo de implantação for concluído, você verá uma saída como esta:
    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
  2. Copie o URL do serviço do Cloud Run exibido em uma guia ou janela separada do navegador. Como alternativa, execute o comando a seguir no terminal para imprimir o URL do serviço e clique no URL mostrado enquanto mantém pressionada a tecla Ctrl para abrir o URL:
    gcloud run services list \
     --format='value(URL)' \
     --filter='SERVICE:"codelab-o11y-service"'
    Ao abrir o URL, você pode receber um erro 500 ou ver a mensagem:
    Sorry, this is just a placeholder...
    Isso significa que os serviços não concluíram a implantação. Aguarde alguns instantes e atualize a página. No final, você vai encontrar um texto que começa com Curiosidades divertidas sobre cachorros e contém 10 curiosidades sobre cachorros.

Para gerar registros de aplicativos, abra o URL do serviço. Atualize a página enquanto muda o valor do parâmetro ?animal= para receber resultados diferentes.
Para conferir os registros do aplicativo, faça o seguinte:

  1. Clique no botão abaixo para abrir a página do Explorador de registros no console do Cloud:

  2. Cole o filtro a seguir no painel "Consulta" (nº 2 na interface da Análise de registros):
    LOG_ID("run.googleapis.com%2Fstdout") AND
severity=DEBUG
  3. Clique em Executar consulta.

O resultado da consulta mostra registros com o comando e a resposta da Vertex AI, incluindo classificações de segurança.

9. Contar interações com a IA generativa

O Cloud Run grava métricas gerenciadas que podem ser usadas para monitorar serviços implantados. As métricas de monitoramento gerenciadas pelo usuário oferecem mais controle sobre os dados e a frequência da atualização da métrica. Para implementar essa métrica, é necessário escrever um código que colete dados e os grave no Cloud Monitoring. Consulte a próxima etapa (opcional) para saber como implementar usando o SDK do OpenTelemetry.

Esta etapa mostra uma alternativa para implementar a métrica do usuário no código: as métricas com base em registros. Com as métricas com base em registros, é possível gerar métricas de monitoramento das entradas de registro que seu aplicativo grava no Cloud Logging. Vamos usar os registros de aplicativos que implementamos na etapa anterior para definir uma métrica com base em registros do contador de tipo. A métrica vai contar o número de chamadas bem-sucedidas para a API Vertex.

  1. Confira a janela do Explorador de registros que usamos na etapa anterior. No painel "Consulta", localize e clique no menu suspenso Ações para abrir. Confira a captura de tela abaixo para encontrar o menu:
    Barra de ferramentas de resultados da consulta com menu suspenso "Ações"
  2. No menu aberto, selecione Criar métrica para abrir o painel Criar métrica com base em registros.
  3. Siga estas etapas para configurar uma nova métrica de contador no painel Criar métrica com base em registros:
    1. Defina o Tipo de métrica: selecione Contador.
    2. Defina os seguintes campos na seção Detalhes:
      • Nome da métrica de registro: defina o nome como model_interaction_count. Algumas restrições de nomenclatura se aplicam. Consulte Solução de problemas para mais detalhes.
      • Descrição: insira uma descrição para a métrica. Por exemplo, Number of log entries capturing successful call to model inference.
      • Unidades: deixe em branco ou insira o dígito 1.
    3. Deixe os valores na seção Seleção de filtro. Observe que o campo Filtro de criação tem o mesmo filtro que usamos para ver os registros de aplicativos.
    4. (Opcional) Adicione um rótulo que ajude a contar o número de chamados para cada animal. OBSERVAÇÃO: esse rótulo pode aumentar muito a cardinalidade da métrica e não é recomendado para uso em produção:
      1. Clique em Adicionar rótulo.
      2. Defina os seguintes campos na seção Rótulos:
        • Nome do identificador: defina o nome como animal.
        • Descrição: insira a descrição do rótulo. Por exemplo, Animal parameter.
        • Tipo de marcador: selecione STRING.
        • Nome do campo: digite jsonPayload.animal.
        • Expressão regular: deixe em branco.
      3. Clique em Concluir.
    5. Clique em Criar métrica para criá-la.

Também é possível criar uma métrica com base em registros na página Métricas com base em registros usando o comando da CLI gcloud logging metrics create ou o recurso do Terraform google_logging_metric.

Para gerar dados de métricas, abra o URL do serviço. Atualize a página aberta várias vezes para fazer várias chamadas ao modelo. Como antes, tente usar animais diferentes no parâmetro.

Insira a consulta em PromQL para pesquisar os dados de métricas com base em registros. Para inserir uma consulta em PromQL, faça o seguinte:

  1. Clique no botão abaixo para abrir a página do Metrics Explorer no console do Cloud:

  2. Na barra de ferramentas do painel do criador de consultas, selecione o botão com o nome < > MQL ou < > PromQL. Confira a localização do botão na imagem abaixo.
    Localização do botão MQL no Metrics Explorer
  3. Verifique se PromQL está selecionado na opção de ativar/desativar Idioma. A alternância de idiomas está na mesma barra de ferramentas que permite formatar sua consulta.
  4. Insira sua consulta no editor Consultas:
    sum(rate(logging_googleapis_com:user_model_interaction_count{monitored_resource="cloud_run_revision"}[${__interval}]))
    Para mais informações sobre como usar o PromQL, consulte PromQL no Cloud Monitoring.
  5. Selecione Executar consulta. Você vai ver um gráfico de linhas semelhante a esta captura de tela:
    Mostrar métricas consultadas

    Quando a opção Execução automática está ativada, o botão Executar consulta não aparece.

10. (Opcional) Usar o OpenTelemetry para monitoramento e rastreamento

Como mencionado na etapa anterior, é possível implementar métricas usando o SDK do OpenTelemetry (Otel). Usar o OTel em arquiteturas de microsserviços é uma prática recomendada. Esta etapa descreve o seguinte:

  • Inicialização de componentes do OTel para oferecer suporte ao rastreamento e monitoramento do aplicativo
  • Como preencher a configuração do OTel com metadados de recursos do ambiente do Cloud Run
  • Como instrumentar um aplicativo Flask com recursos de rastreamento automático
  • Implementar uma métrica de contador para monitorar o número de chamadas de modelo bem-sucedidas
  • Correlacionar rastreamento com registros de aplicativos

A arquitetura recomendada para serviços no nível do produto é usar o coletor OTel para coletar e ingerir todos os dados de observabilidade de um ou mais serviços. Para simplificar, o código desta etapa não usa o coletor. Em vez disso, ele usa exportações do OTel que gravam dados diretamente no Google Cloud.

Configurar componentes do OTel para rastreamento e monitoramento de métricas

  1. Volte para a janela (ou guia) "Cloud Shell" no navegador.
  2. Instale os pacotes necessários para usar a instrumentação automática do OpenTelemetry:
    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
  3. No terminal, crie um arquivo setup.js:
    cloudshell edit ~/codelab-o11y/setup.js
  4. Copie e cole o código abaixo no editor para configurar o rastreamento e o monitoramento do OpenTelemetry.
    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);
}
  5. Volte ao terminal e reabra o index.js:
    cloudshell edit ~/codelab-o11y/index.js
  6. Substitua o código pela versão que inicializa o rastreamento e a coleta de métricas do OpenTelemetry e também atualiza o contador de performance em cada execução bem-sucedida. Para atualizar o código, exclua o conteúdo do arquivo e copie e cole o código abaixo:
    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}`);
});

Agora, o aplicativo usa o SDK do OpenTelemetry para instrumentar a execução do código com rastreamento e implementar a contagem de um número de execuções bem-sucedidas como uma métrica. O método main() é modificado para configurar os exportadores do OpenTelemetry para traces e métricas gravarem diretamente no Google Cloud Tracing e Monitoring. Ele também realiza outras configurações para preencher os rastreamentos e as métricas coletadas com metadados relacionados ao ambiente do Cloud Run. A função Handler() é atualizada para incrementar o contador de métricas sempre que a chamada de API Vertex AI retorna resultados válidos.

Depois de alguns segundos, o Cloud Shell Editor salva as mudanças automaticamente.

Implantar o código do aplicativo de IA generativa no Cloud Run

  1. Na janela do terminal, execute o comando para implantar o código-fonte do aplicativo no Cloud Run.
    gcloud run deploy codelab-o11y-service \
     --source="${HOME}/codelab-o11y/" \
     --region=us-central1 \
     --allow-unauthenticated
    Se você vir o prompt abaixo, informando que o comando vai criar um novo repositório. Clique em 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)?
    O processo de implantação pode levar alguns minutos. Depois que o processo de implantação for concluído, você verá uma saída como esta:
    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
  2. Copie o URL do serviço do Cloud Run exibido em uma guia ou janela separada do navegador. Como alternativa, execute o comando a seguir no terminal para imprimir o URL do serviço e clique no URL mostrado enquanto mantém pressionada a tecla Ctrl para abrir o URL:
    gcloud run services list \
     --format='value(URL)' \
     --filter='SERVICE:"codelab-o11y-service"'
    Ao abrir o URL, você pode receber um erro 500 ou ver a mensagem:
    Sorry, this is just a placeholder...
    Isso significa que os serviços não concluíram a implantação. Aguarde alguns instantes e atualize a página. No final, você vai encontrar um texto que começa com Curiosidades divertidas sobre cachorros e contém 10 curiosidades sobre cachorros.

Para gerar dados de telemetria, abra o URL do serviço. Atualize a página enquanto muda o valor do parâmetro ?animal= para receber resultados diferentes.

Analisar traces de aplicativos

  1. Clique no botão abaixo para abrir a página do Explorador de traces no console do Cloud:

  2. Selecione um dos rastreamentos mais recentes. Você vai ver cinco ou seis intervalos parecidos com a captura de tela abaixo.
    Visualização do período do app no Explorador de traces
  3. Encontre o período que rastreia a chamada para o manipulador de eventos (o método fun_facts). Ele será o último período com o nome /.
  4. No painel Detalhes do trace, selecione Registros e eventos. Você vai encontrar os registros de aplicativos correlacionados a esse período específico. A correlação é detectada usando os IDs de trace e período no trace e no registro. Você vai ver o registro do aplicativo que escreveu o comando e a resposta da API Vertex.

Analisar a métrica de contador

  1. Clique no botão abaixo para abrir a página do Metrics Explorer no console do Cloud:

  2. Na barra de ferramentas do painel do criador de consultas, selecione o botão com o nome < > MQL ou < > PromQL. Confira a localização do botão na imagem abaixo.
    Localização do botão MQL no Metrics Explorer
  3. Verifique se PromQL está selecionado na opção de ativar/desativar Idioma. A alternância de idiomas está na mesma barra de ferramentas que permite formatar sua consulta.
  4. Insira sua consulta no editor Consultas:
    sum(rate(workload_googleapis_com:model_call_counter{monitored_resource="generic_task"}[${__interval}]))
  5. Clique em Executar consulta.Quando a opção Execução automática está ativada, o botão Executar consulta não aparece.

11. (Opcional) Informações sensíveis ofuscadas dos registros

Na etapa 10, registramos informações sobre a interação do aplicativo com o modelo do Gemini. Essas informações incluíam o nome do animal, o comando real e a resposta do modelo. Embora o armazenamento dessas informações no registro seja seguro, isso não é necessariamente verdadeiro em muitos outros cenários. O comando pode incluir informações pessoais ou sensíveis que um usuário não quer que sejam armazenadas. Para resolver isso, ofusque os dados sensíveis gravados no Cloud Logging. Para minimizar as modificações no código, recomendamos a seguinte solução.

  1. Criar um tópico do Pub/Sub para armazenar entradas de registro recebidas
  2. Crie um coletor de registros que redirecione os registros ingeridos para o tópico do Pub/Sub.
  3. Crie um pipeline do Dataflow que modifique os registros redirecionados para o tópico do Pub/Sub seguindo estas etapas:
    1. Ler uma entrada de registro do tópico do Pub/Sub
    2. Inspecionar a carga útil da entrada em busca de informações sensíveis usando a API de inspeção da DLP
    3. Edite as informações sensíveis no payload usando um dos métodos de edição da DLP.
    4. Gravar a entrada de registro ofuscada no Cloud Logging
  4. Implante o pipeline.

12. (Opcional) Limpar

Para evitar o risco de cobranças por recursos e APIs usados no codelab, é recomendável fazer uma limpeza depois de concluir o laboratório. O jeito mais fácil de evitar cobranças é excluindo o projeto que você criou para o codelab.

  1. Para excluir o projeto, execute o comando de exclusão no terminal:
    PROJECT_ID=$(gcloud config get-value project)
gcloud projects delete ${PROJECT_ID} --quiet
    A exclusão do projeto na nuvem interrompe o faturamento de todos os recursos e APIs usados nele. Você vai receber esta mensagem, em que PROJECT_ID é o ID do projeto:
    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.
  2. (Opcional) Se você receber um erro, consulte a Etapa 5 para encontrar o ID do projeto usado durante o laboratório. Substitua-o pelo comando na primeira instrução. Por exemplo, se o ID do projeto for lab-example-project, o comando será:
    gcloud projects delete lab-project-id-example --quiet

13. Parabéns

Neste laboratório, você criou um aplicativo de IA generativa que usa o modelo do Gemini para fazer previsões. e instrumentou o aplicativo com recursos essenciais de monitoramento e geração de registros. Você implantou o aplicativo e as mudanças do código-fonte no Cloud Run. Em seguida, use os produtos do Google Cloud Observability para acompanhar a performance do aplicativo e garantir a confiabilidade dele.

Se você quiser participar de um estudo de pesquisa de experiência do usuário (UX) para melhorar os produtos com que trabalhou hoje, inscreva-se aqui.

Confira algumas opções para continuar aprendendo: