Plug-in de telemetria e geração de registros 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.

Pré-requisitos

Se você quiser executar localmente fluxos que usam esse plug-in, precisará da 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

Para ativar a exportação para o Google Cloud Tracing, Logging e Monitoring, importe googlecloud e execute Init(). Depois de chamar Init(), sua telemetria é automaticamente exportada.

import "github.com/firebase/genkit/go/plugins/googlecloud"

if err := googlecloud.Init(
	ctx,
	googlecloud.Config{ProjectID: "your-google-cloud-project"},
); err != nil {
	return err
}

Especifique o projeto do Google Cloud para onde você quer exportar os dados da telemetria. Há também alguns parâmetros opcionais:

  • ForceExport: exporta dados de telemetria mesmo quando executados em um ambiente de desenvolvimento (como ao usar genkit start ou genkit flow:run). Essa é uma maneira rápida de testar a integração e enviar os primeiros eventos para monitoramento no Google Cloud.

    Se você usar essa opção, também vai precisar disponibilizar suas credenciais do Cloud localmente:

    gcloud auth application-default login

  • MetricInterval: o intervalo, em nanossegundos, em que as informações de telemetria serão exportadas. Por padrão, isso equivale a 60 segundos (60e9 nanossegundos).

  • LogLevel: o nível mínimo de gravidade das entradas de registro a serem exportadas. slog.LevelInfo, por padrão.

O plug-in requer as credenciais do projeto do Google Cloud. Se você está executando fluxos de um ambiente do Google Cloud (Cloud Run etc.), as credenciais são definidas automaticamente. A execução em outros ambientes exige a configuração do Application Default Credentials.

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: