Plug-in do Google Cloud

O plug-in do Google Cloud exporta os dados de telemetria e de registros do Firebase Genkit para o pacote de operações do Google Cloud.

Instalação

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

Se você quiser executar localmente fluxos que usam esse plug-in, também precisará do ferramenta CLI do Google Cloud instalada.

Configurar uma conta do Google Cloud

Esse plug-in requer uma conta do Google Cloud (inscreva-se, se ainda não tiver uma) e um projeto do Google Cloud.

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

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 a exportação para o Google Cloud Tracing, Logging e Monitoring, adicione o plug-in googleCloud à configuração do Genkit:

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

export default configureGenkit({
  plugins: [googleCloud()],
  enableTracingAndMetrics: true,
  telemetry: {
    instrumentation: 'googleCloud',
    logger: 'googleCloud',
  },
});

Quando executada na produção, sua telemetria é exportada automaticamente.

Authentication

O plug-in requer o ID do projeto do Google Cloud e as credenciais do projeto do Google Cloud. Se você estiver executando seu fluxo em um ambiente do Google Cloud (Cloud Functions, Cloud Run etc.), o ID do projeto e as credenciais serão definidos automaticamente.

Application Default Credentials

A execução em outros ambientes requer a configuração da variável de ambiente GCLOUD_PROJECT como seu projeto do Google Cloud e a autenticação usando a ferramenta gcloud:

gcloud auth application-default login

Para mais informações, consulte o documento Application Default Credentials.

Credenciais da conta de serviço

Se você estiver usando uma conta de serviço e estiver em execução fora de um ambiente do Google Cloud, defina suas credenciais como uma variável de ambiente. Siga as instruções aqui para configurar a chave da conta de serviço do Google Cloud.

Depois de fazer o download do arquivo de chave, é possível especificar as credenciais de duas maneiras em um local de arquivo usando a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS ou copiar diretamente o conteúdo do arquivo json para a variável de ambiente GCLOUD_SERVICE_ACCOUNT_CREDS.

Caminho do arquivo:

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

Cópia direta:

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

O plug-in googleCloud() usa um objeto de configuração opcional:

{
    projectId?: string,
    telemetryConfig?: TelemetryConfig
}

projectId

Essa opção permite especificar o ID do projeto do Google Cloud explicitamente. Na maioria dos casos, isso é desnecessário.

telemetryConfig

Essa opção configura a instância do OpenTelemetry NodeSDK.

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

googleCloud({
  telemetryConfig: {
    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,
  },
});

forceDevExport

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

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 amostras pré-configuradas:

autoInstrumentation e autoInstrumentationConfig

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

metricsExportInterval

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

Testar sua integração

Ao configurar o plug-in, use forceDevExport: true para ativar a exportação de telemetria para execuções locais. Essa é uma maneira rápida de enviar os primeiros eventos para monitoramento no Google Cloud.

Monitoramento da produção com o pacote de operações do Google Cloud

Depois que um fluxo for implantado, acesse o pacote de operações do Google Cloud e selecione o projeto.

Registros e traces

No menu lateral, encontre "Geração de registros". e clique em "Análise de registros".

Serão exibidos todos os registros associados ao fluxo 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 registros Input[...] contêm os comandos. O Cloud Logging tem ACLs robustas que permitem um controle detalhado de registros confidenciais.

Para linhas de registro específicas, é possível navegar para os respectivos traces clicando no ícone do menu estendido e selecionando "Mostrar detalhes do trace".

Isso abrirá um painel de visualização de traces, com uma visão rápida dos detalhes do trace. Para conferir todos os detalhes, clique no botão "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" no menu suspenso.

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

Métricas

Para visualizar todas as métricas que o Genkit exporta, selecione "Logging" no menu lateral e clique em "Gerenciamento de métricas".

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 "Carga de trabalho" 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 métricas de fluxo, 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.
  • temperature: o valor da temperatura de inferência.
  • topK: o valor de inferência topK.
  • topP: o valor topP de inferência.

Métricas de nível de fluxo

Nome Dimensões
genkit/flow/requests flow_name, error_code, error_message
genkit/flow/latency flow_name

Métricas no nível da ação

Nome Dimensões
genkit/action/requests flow_name, error_code, error_message
genkit/action/latency flow_name

Métricas no nível da geração

Nome Dimensões
genkit/ai/generate flow_path, model, temperature, topK, topP, error_code, error_message
genkit/ai/generate/input_tokens flow_path, model, temperature, topK, topP
genkit/ai/generate/output_tokens flow_path, model, temperature, topK, topP
genkit/ai/generate/input_characters flow_path, model, temperature, topK, topP
genkit/ai/generate/output_characters flow_path, model, temperature, topK, topP
genkit/ai/generate/input_images flow_path, model, temperature, topK, topP
genkit/ai/generate/output_images flow_path, model, temperature, topK, topP
genkit/ai/generate/latency flow_path, model, temperature, topK, topP, error_code, error_message

É possível visualizar métricas no Metrics Explorer. No menu lateral, selecione "Logging" e clique em "Metrics Explorer"

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 dependerá do seu tipo (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:

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: