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, 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:

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.