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:
- SempreOnSampler: faz a amostragem de todos os traces.
- AlwaysOffSampler: não há amostras de traces.
- ParentBased: amostras com base no período pai
- TraceIdRatioBased: gera amostras de uma porcentagem configurável de traces.
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.
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 seus 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 "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:
- Cotas do Cloud Trace
- 128 bytes por chave de atributo
- 256 bytes por valor de atributo
- Cotas do Cloud Logging
- 256 KB por entrada de registro
- 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: