O plug-in do Google Cloud exporta os dados de telemetria e de registros do Firebase Genkit para o pacote Cloud Observability, que alimenta o painel Monitoramento de IA do Firebase.

Instalação

npm i --save @genkit-ai/google-cloud

Ao executar localmente o código do Genkit que inclui esse plug-in, você também precisa ter a ferramenta CLI do Google Cloud instalada.

Configurar uma conta do Google Cloud

Esse plug-in requer uma conta/projeto do Google Cloud. Todos os projetos do Firebase incluem um por padrão (console do GCP), ou você pode se inscrever em https://cloud.google.com.

Antes de adicionar o plug-in, verifique se as seguintes APIs estão ativadas no seu projeto do GCP:

• API Cloud Logging
• API Cloud Trace
• API Cloud Monitoring

Essas APIs devem ser listadas no painel de APIs do seu projeto.

Clique aqui para saber como ativar e desativar APIs.

Configuração do Genkit

Para ativar o Cloud Tracing, o Logging e o Monitoring (métricas), chame enableGoogleCloudTelemetry():

import { enableGoogleCloudTelemetry } from '@genkit-ai/google-cloud';

enableGoogleCloudTelemetry();

Quando executado na produção, a telemetria é exportada automaticamente.

Autenticação e autorização

O plug-in requer um ID de projeto do Google Cloud e credenciais do aplicativo.

Google Cloud

Se você implantar o código em um ambiente do Google Cloud (Cloud Functions, Cloud Run etc.), o ID do projeto e as credenciais serão descobertos automaticamente pelas Application Default Credentials.

É necessário aplicar os seguintes papéis à conta de serviço que está executando seu código (ou seja, a "conta de serviço anexada") pelo console do IAM:

• roles/monitoring.metricWriter
• roles/cloudtrace.agent
• roles/logging.logWriter

Desenvolvimento local

Ao fazer o desenvolvimento local, para que suas credenciais de usuário estejam disponíveis para o plug-in, outras etapas são necessárias.

1. Defina a variável de ambiente GCLOUD_PROJECT para seu projeto do Google Cloud.

2. Faça a autenticação usando a CLI gcloud:

   gcloud auth application-default login

Ambientes de produção fora do Google Cloud

Se possível, ainda é recomendável aproveitar o processo de credenciais padrão do aplicativo para disponibilizar credenciais ao plug-in.

Isso geralmente envolve gerar uma chave/um par de conta de serviço e implantar essas credenciais no ambiente de produção.

1. Siga as instruções para configurar uma chave de conta de serviço.

2. Verifique se a conta de serviço tem os seguintes papéis:

   • roles/monitoring.metricWriter
   • roles/cloudtrace.agent
   • roles/logging.logWriter

3. Implante o arquivo de credencial na produção (não verifique no código-fonte)

4. Defina a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS como o caminho para o arquivo de credenciais.

   GOOGLE_APPLICATION_CREDENTIALS = "path/to/your/key/file"
   

Em alguns ambientes sem servidor, talvez não seja possível implantar um arquivo de credencial. Nesse caso, como alternativa às etapas 3 e 4 acima, é possível definir a variável de ambiente GCLOUD_SERVICE_ACCOUNT_CREDS com o conteúdo do arquivo de credenciais da seguinte maneira:

GCLOUD_SERVICE_ACCOUNT_CREDS='{
  "type": "service_account",
  "project_id": "your-project-id",
  "private_key_id": "your-private-key-id",
  "private_key": "your-private-key",
  "client_email": "your-client-email",
  "client_id": "your-client-id",
  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
  "token_uri": "https://accounts.google.com/o/oauth2/token",
  "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
  "client_x509_cert_url": "your-cert-url"
}'

Configuração do plug-in

A função enableGoogleCloudTelemetry() usa um objeto de configuração opcional que configura a instância do OpenTelemetry NodeSDK.

import { AlwaysOnSampler } from '@opentelemetry/sdk-trace-base';

enableGoogleCloudTelemetry({
  forceDevExport: false, // Set this to true to export telemetry for local runs
  sampler: new AlwaysOnSampler(),
  autoInstrumentation: true,
  autoInstrumentationConfig: {
    '@opentelemetry/instrumentation-fs': { enabled: false },
    '@opentelemetry/instrumentation-dns': { enabled: false },
    '@opentelemetry/instrumentation-net': { enabled: false },
  },
  metricExportIntervalMillis: 5_000,
});

Os objetos de configuração permitem o controle detalhado sobre vários aspectos da exportação de telemetria descritos abaixo.

credenciais

Permite especificar credenciais diretamente usando JWTInput da biblioteca google-auth.

amostrador

Para casos em que a exportação de todos os rastros não é prática, o OpenTelemetry permite a amostragem de rastros.

Há quatro samplers pré-configurados:

• AlwaysOnSampler: amostra todos os rastros.
• AlwaysOffSampler: não coleta rastros.
• ParentBased: amostras com base no período pai
• TraceIdRatioBased: amostra uma porcentagem configurável de rastros.

autoInstrumentation e autoInstrumentationConfig

A ativação da instrumentação automática permite que o OpenTelemetry capture dados de telemetria de bibliotecas de terceiros sem precisar modificar o código.

metricExportIntervalMillis

Esse campo especifica o intervalo de exportação de métricas em milissegundos.

metricExportTimeoutMillis

Esse campo especifica o tempo limite para a exportação de métricas em milissegundos.

disableMetrics

Fornece uma substituição que desativa a exportação de métricas enquanto exporta rastros e registros.

disableTraces

Fornece uma substituição que desativa a exportação de rastros enquanto exporta métricas e registros.

disableLoggingIO

Fornece uma substituição que desativa a coleta de registros de entrada e saída.

forceDevExport

Essa opção força o Genkit a exportar dados de telemetria e de registro quando executado no ambiente dev (por exemplo, localmente).

Testar sua integração

Ao configurar o plug-in, use forceDevExport: true para ativar a exportação de telemetria para execuções locais. Acesse o Google Cloud Logs, Metrics ou Trace Explorer para conferir a telemetria.

Pacote de Observabilidade do Google Cloud

Depois que o código (por exemplo, o fluxo) for implantado, acesse o painel Cloud Monitoring e selecione seu projeto. A partir daí, é possível navegar facilmente entre os exploradores de registros, métricas e rastros para monitoramento de produção.

Registros e traces

No menu à esquerda, clique em "Análise de registros", na seção "Explorar".

Aqui, você vai encontrar todos os registros associados ao código do Genkit implantado, incluindo console.log(). Qualquer registro com o prefixo [genkit] é um registro interno do Genkit que contém informações que podem ser interessantes para fins de depuração. Por exemplo, os registros do Genkit no formato Config[...] contêm metadados, como os valores de temperatura e topK, para inferências específicas do LLM. Os registros no formato Output[...] contêm respostas LLM, enquanto os registros Input[...] contêm os comandos. O Cloud Logging tem ACLs robustas que permitem um controle detalhado de acesso a registros confidenciais.

Isso vai abrir um painel de visualização de trace, com uma visão rápida dos detalhes do trace. Para conferir todos os detalhes, clique no link "Ver no Trace" no canto superior direito do painel.

O elemento de navegação de maior destaque no Cloud Trace é o gráfico de dispersão de traces. Ele contém todos os traces coletados em um determinado período.

Clique em cada ponto de dados para visualizar os detalhes abaixo do gráfico de dispersão.

A visualização detalhada contém o formato do fluxo, incluindo todas as etapas e informações importantes de tempo. O Cloud Trace consegue intercalar todos os registros associados a um determinado trace nessa visualização. Selecione a opção "Mostrar expandidas" no menu suspenso "Logs e eventos".

A visualização resultante permite uma análise detalhada dos registros no contexto do trace, incluindo comandos e respostas do LLM.

Métricas

Para conferir todas as métricas exportadas pelo Genkit, clique em "Gerenciamento de métricas" no título "Configurar" no menu à esquerda.

O console de gerenciamento de métricas contém uma visualização tabular de todas as métricas coletadas, incluindo aquelas que pertencem ao Cloud Run e ao ambiente dele. Clicar na opção "Carga de trabalho" vai revelar uma lista com métricas coletadas pelo Genkit. Qualquer métrica com o prefixo genkit constitui uma métrica interna do Genkit.

O Genkit coleta várias categorias de métricas, incluindo: recurso, ação e geração. Cada métrica tem várias dimensões úteis, o que facilita a filtragem e o agrupamento eficientes.

As dimensões comuns incluem:

• flow_name: o nome de nível superior do fluxo.
• flow_path: o período e a cadeia dele até o período raiz.
• error_code: no caso de um erro, o código do erro correspondente.
• error_message: a mensagem de erro correspondente, no caso de ocorrer um erro.
• model: o nome do modelo.

Métricas de recursos

Os recursos são o ponto de entrada de nível superior do código do Genkit. Na maioria dos casos, esse será um fluxo. Caso contrário, esse será o período mais alto em um rastro.

Cada métrica de recurso contém as seguintes dimensões:

Métricas de ação

As ações representam uma etapa genérica de execução no Genkit. Cada uma dessas etapas terá as seguintes métricas rastreadas:

Cada métrica de ação contém as seguintes dimensões:

Gerar métricas

Essas são métricas de ação especiais relacionadas a ações que interagem com um modelo. Além das solicitações e da latência, a entrada e a saída também são rastreadas, com dimensões específicas do modelo que facilitam a depuração e o ajuste da configuração.

Cada métrica gerada contém as seguintes dimensões:

É possível visualizar métricas no Metrics Explorer. No menu à esquerda, clique em "Metrics Explorer", sob o título "Explorar".

Selecione uma métrica clicando no menu suspenso "Selecionar uma métrica", selecionando "Nó genérico", "Genkit" e uma métrica.

A visualização da métrica vai depender do tipo dela (contador, histograma etc.). O Metrics Explorer fornece recursos robustos de agregação e consulta para ajudar a criar gráficos com as métricas de acordo com as várias dimensões.

Atraso de telemetria

Pode haver um pequeno atraso antes que a telemetria de uma execução específica de um fluxo seja exibida no pacote de operações do Cloud. Na maioria dos casos, esse atraso é inferior a um minuto.

Cotas e limites

É importante ter várias cotas em mente:

• Cotas do Cloud Trace
• Cotas do Cloud Logging
• Cotas do Cloud Monitoring

Custo

O Cloud Logging, o Cloud Trace e o Cloud Monitoring têm níveis sem custo financeiro generosos. Os preços específicos podem ser encontrados nos seguintes links:

• Preços do Cloud Logging
• Preços do Cloud Trace
• Preços do Cloud Monitoring