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á instalar a ferramenta Google Cloud CLI.

Configurar uma conta do Google Cloud

Este 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.

O plug-in exige o ID do projeto 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. 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.

Configuração do plug-in

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

{
    projectId?: string,
    telemetryConfig?: TelemetryConfig
}

projectId

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

telemetryConfig

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

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

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

amostra

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

Há quatro amostras pré-configuradas:

autoInstrumentation e autoInstrumentationConfig

Com a ativação da instrumentação automática, o OpenTelemetry pode capturar dados de telemetria de bibliotecas de terceiros sem precisar modificar o código.

MetricsExportInterval

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

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 "Logging" 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 "View in trace details".

Isso abrirá um painel de visualização de rastros, fornecendo uma visão rápida dos detalhes do rastro. Para conferir todos os detalhes, clique no link "View in 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 tem a capacidade de intercalar todos os registros associados a um determinado trace nessa visualização. Selecione a opção "Mostrar expandido" no menu suspenso "Registros e eventos".

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

Métricas

Para visualizar todas as métricas exportadas pelo Genkit, 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. Ao clicar na opção "Carga de trabalho", é exibida uma lista que inclui 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 de 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/solicitações nome_fluxo, código_do_erro, mensagem_de_erro
genkit/fluxo/latência nome_do_fluxo

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

Nome Dimensões
genkit/ação/solicitações nome_fluxo, código_do_erro, mensagem_de_erro
genkit/ação/latência nome_do_fluxo

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

Nome Dimensões
genkit/ai/generate caminho_do_fluxo, modelo, temperatura, topK, topP, código_do_erro, mensagem_de_erro
genkit/ai/generate/input_tokens caminho_de_fluxo, modelo, temperatura, topK, topP
genkit/ai/generate/output_tokens caminho_de_fluxo, modelo, temperatura, topK, topP
genkit/ai/generate/input_characters caminho_de_fluxo, modelo, temperatura, topK, topP
genkit/ai/generate/output_characters caminho_de_fluxo, modelo, temperatura, topK, topP
genkit/ai/generate/input_images caminho_de_fluxo, modelo, temperatura, topK, topP
genkit/ai/generate/output_images caminho_de_fluxo, modelo, temperatura, topK, topP
genkit/ai/generate/latência caminho_do_fluxo, modelo, temperatura, topK, topP, código_do_erro, mensagem_de_erro

É possível visualizar métricas no Metrics Explorer. No menu lateral, selecione "Geração de registros" e clique em "Metrics Explorer".

Para escolher uma métrica, clique no menu suspenso "Selecionar uma métrica", escolha "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: