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, que alimenta o painel de monitoramento de IA do Firebase (pré-lançamento privado).
Instalação
npm i --save @genkit-ai/google-cloud
Se você quiser executar localmente fluxos que usam esse plug-in, também 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 do Genkit
Para ativar a exportação para o Google Cloud Tracing, Logging e Monitoring, chame enableGoogleCloudTelemetry()
:
import { enableGoogleCloudTelemetry } from '@genkit-ai/google-cloud';
enableGoogleCloudTelemetry();
Quando executado em produção, a 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 o 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 exige a configuração da variável de ambiente GCLOUD_PROJECT
no seu projeto do Google Cloud e a autenticação usando a ferramenta gcloud
:
gcloud auth application-default login
Para mais informações, consulte a documentação do Application Default Credentials.
Credenciais da conta de serviço
Se você estiver usando uma conta de serviço e executando fora de um ambiente do Google Cloud, poderá definir 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: 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
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 controlar 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
Ativar a 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, mas ainda exporta rastros e registros.
disableTraces
Fornece uma substituição que desativa a exportação de rastros, mas ainda 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. Como alternativa, acesse o painel de monitoramento de IA do Firebase (pré-lançamento particular) para conferir uma visão da telemetria com a linguagem da IA.