Il plug-in Google Cloud esporta i dati di logging e telemetria di Firebase Genkit nella suite Cloud Observability, che alimenta la dashboard Firebase AI Monitoring.
Installazione
npm i --save @genkit-ai/google-cloudQuando esegui in locale il codice Genkit che include questo plug-in, devi anche installare lo strumento Google Cloud CLI.
Configurare un account Google Cloud
Questo plug-in richiede un account/progetto Google Cloud. Tutti i progetti Firebase ne includono uno per impostazione predefinita (console Google Cloud) oppure puoi registrarti all'indirizzo https://cloud.google.com.
Prima di aggiungere il plug-in, assicurati che le seguenti API siano abilitate per il tuo progetto Google Cloud:
Queste API dovrebbero essere elencate nella dashboard delle API per il tuo progetto.
Fai clic qui per scoprire di più sull'attivazione e la disattivazione delle API.
Configurazione di Genkit
Per attivare Cloud Tracing, Logging e Monitoring (metriche), chiama semplicemente enableGoogleCloudTelemetry():
import { enableGoogleCloudTelemetry } from '@genkit-ai/google-cloud';
enableGoogleCloudTelemetry();
Quando viene eseguita in produzione, la telemetria viene esportata automaticamente.
Autenticazione e autorizzazione
Il plug-in richiede un ID progetto Google Cloud e le credenziali dell'applicazione.
Google Cloud
Se esegui il deployment del codice in un ambiente Google Cloud (Cloud Functions, Cloud Run e così via), l'ID progetto e le credenziali verranno rilevati automaticamente tramite le credenziali predefinite dell'applicazione.
Dovrai applicare i seguenti ruoli all'account di servizio che esegue il codice (ovvero "account di servizio collegato") tramite la console IAM:
roles/monitoring.metricWriterroles/cloudtrace.agentroles/logging.logWriter
Sviluppo locale
Quando esegui lo sviluppo locale, affinché le credenziali utente siano disponibili per il plug-in, sono necessari passaggi aggiuntivi.
Imposta la variabile di ambiente
GCLOUD_PROJECTsul tuo progetto Google Cloud.Esegui l'autenticazione utilizzando l'interfaccia a riga di comando
gcloud:gcloud auth application-default login
Ambienti di produzione esterni a Google Cloud
Se possibile, ti consigliamo comunque di utilizzare la procedura per le credenziali predefinite dell'applicazione per rendere disponibili le credenziali per il plug-in.
In genere, questo comporta la generazione di una coppia/una chiave dell'account di servizio e il deployment di queste credenziali nell'ambiente di produzione.
Segui le istruzioni per configurare una chiave dell'account di servizio.
Assicurati che l'account di servizio abbia i seguenti ruoli:
roles/monitoring.metricWriterroles/cloudtrace.agentroles/logging.logWriter
Esegui il deployment del file delle credenziali in produzione (non eseguire il check-in nel codice sorgente)
Imposta la variabile di ambiente
GOOGLE_APPLICATION_CREDENTIALScome percorso del file delle credenziali.GOOGLE_APPLICATION_CREDENTIALS = "path/to/your/key/file"
In alcuni ambienti serverless, potresti non essere in grado di eseguire il deployment di un file di credenziali. In questo caso, in alternativa ai passaggi 3 e 4 precedenti, puoi impostare la variabile di ambiente GCLOUD_SERVICE_ACCOUNT_CREDS con i contenuti del file delle credenziali come segue:
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"
}'
Configurazione plug-in
La funzione enableGoogleCloudTelemetry() accetta un oggetto di configurazione facoltativo che configura l'istanza di 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,
});
Gli oggetti di configurazione consentono un controllo granulare su vari aspetti dell'esportazione della telemetria descritti di seguito.
le credenziali
Consente di specificare le credenziali direttamente utilizzando JWTInput dalla libreria google-auth.
campionatore
Nei casi in cui l'esportazione di tutte le tracce non sia praticabile, OpenTelemetry consente il campionamento delle tracce.
Esistono quattro sampler preconfigurati:
- AlwaysOnSampler: acquisisce campioni di tutte le tracce
- AlwaysOffSampler: non acquisisce tracce
- ParentBased: campioni basati sull'intervallo principale
- TraceIdRatioBased: campiona una percentuale configurabile di tracce
autoInstrumentation e autoInstrumentationConfig
L'attivazione della strumentazione automatica consente a OpenTelemetry di acquisire i dati di telemetria da librerie di terze parti senza dover modificare il codice.
metricExportIntervalMillis
Questo campo specifica l'intervallo di esportazione delle metriche in millisecondi.
metricExportTimeoutMillis
Questo campo specifica il timeout per l'esportazione delle metriche in millisecondi.
disableMetrics
Fornisce un'override che disattiva l'esportazione delle metriche, continuando a esportare tracce e log.
disattivaTraces
Fornisce un'override che disattiva l'esportazione delle tracce, continuando a esportare le metriche e i log.
disableLoggingIO
Fornisce un'override che disattiva la raccolta dei log di input e output.
forceDevExport
Questa opzione forza Genkit a esportare i dati di telemetria e log quando viene eseguito nell'ambiente dev (ad es. localmente).
Testa l'integrazione
Quando configuri il plug-in, utilizza forceDevExport: true per attivare l'esportazione della telemetria per le esecuzioni locali. Vai a Logs, Metrics o Trace Explorer di Google Cloud per visualizzare la telemetria.
Suite Google Cloud Observability
Una volta eseguito il deployment del codice (ad es. il flusso), vai alla dashboard Cloud Monitoring e seleziona il tuo progetto. Da qui, puoi spostarti facilmente tra le esplorazioni Log, Metriche e Tracce per il monitoraggio della produzione.
Log e tracce
Nel menu a sinistra, fai clic su "Esploratore dei log" sotto l'intestazione "Esplora".
Qui vedrai tutti i log associati al codice Genkit di cui è stato eseguito il deployment, incluso console.log(). Qualsiasi log con il prefisso [genkit] è un log interno di Genkit che contiene informazioni che potrebbero essere interessanti ai fini del debugging. Ad esempio, i log di Genkit nel formato Config[...] contengono
metadati come la temperatura e i valori topK per deduzioni LLM specifiche.
I log nel formato Output[...] contengono le risposte dell'LLM, mentre i log Input[...] contengono i prompt. Cloud Logging dispone di ACL efficaci che consentono un controllo granulare sull'accesso ai log sensibili.
Viene visualizzato un riquadro di anteprima della traccia che fornisce una rapida panoramica dei dettagli della traccia. Per visualizzare i dettagli completi, fai clic sul link "Visualizza nel tracciamento" in alto a destra nel riquadro.
L'elemento di navigazione più importante in Cloud Trace è il grafico a dispersione delle tracce. Contiene tutte le tracce raccolte in un determinato intervallo di tempo.
Se fai clic su ciascun punto dati, i relativi dettagli vengono visualizzati sotto il grafico a dispersione.
La visualizzazione dettagliata contiene la forma del flusso, inclusi tutti i passaggi, e informazioni importanti sui tempi. Cloud Trace ha la possibilità di intercalare tutti i log associati a una determinata traccia all'interno di questa visualizzazione. Seleziona l'opzione"Mostra espanso " nel menu a discesa "Log ed eventi".
La visualizzazione risultante consente di esaminare in dettaglio i log nel contesto della traccia, inclusi i prompt e le risposte dell'LLM.
Metriche
Per visualizzare tutte le metriche esportate da Genkit, fai clic su 'Gestione delle metriche' sotto l'intestazione "Configura" nel menu a sinistra.
La console di gestione delle metriche contiene una visualizzazione tabulare di tutte le metriche raccolte, incluse quelle relative a Cloud Run e al relativo ambiente.
Se fai clic sull'opzione "Workload", viene visualizzato un elenco che include le metriche raccolte da Genkit. Qualsiasi metrica con il prefisso genkit costituisce una metrica interna di Genkit.
Genkit raccoglie diverse categorie di metriche, tra cui funzionalità, azioni e generazione. Ogni metrica ha diverse dimensioni utili che facilitano il filtraggio e il raggruppamento.
Le dimensioni comuni includono:
flow_name: il nome di primo livello del flusso.flow_path: lo span e il relativo span principale si concatenano fino allo span principale.error_code: in caso di errore, il codice di errore corrispondente.error_message: in caso di errore, il messaggio di errore corrispondente.model: il nome del modello.
Metriche delle funzionalità
Le funzionalità sono il punto di contatto di primo livello per il codice Genkit. Nella maggior parte dei casi, si tratta di un flusso. In caso contrario, sarà l'intervallo più alto in una traccia.
| Nome | Tipo | Descrizione |
|---|---|---|
| genkit/feature/requests | Contatore | Numero di richieste |
| genkit/feature/latency | Istogramma | Latenza di esecuzione in ms |
Ogni metrica delle funzionalità contiene le seguenti dimensioni:
| Nome | Descrizione |
|---|---|
| nome | Il nome della funzionalità. Nella maggior parte dei casi, si tratta del flusso Genkit di primo livello |
| stato | "success" o "failure" a seconda che la richiesta di funzionalità sia andata a buon fine o meno |
| errore | Impostato solo quando status=failure. Contiene il tipo di errore che ha causato l'errore |
| origine | La lingua di origine di Genkit. Ad es. 'ts' |
| sourceVersion | La versione del framework Genkit |
Metriche relative alle azioni
Le azioni rappresentano un passaggio generico di esecuzione all'interno di Genkit. Per ognuno di questi passaggi vengono monitorate le seguenti metriche:
| Nome | Tipo | Descrizione |
|---|---|---|
| genkit/action/requests | Contatore | Numero di volte in cui questa azione è stata eseguita |
| genkit/action/latency | Istogramma | Latenza di esecuzione in ms |
Ogni metrica di azione contiene le seguenti dimensioni:
| Nome | Descrizione |
|---|---|
| nome | Il nome dell'azione |
| featureName | Il nome della funzionalità principale in esecuzione |
| percorso | Il percorso di esecuzione dalla radice della funzionalità a questa azione. Ad es. '/myFeature/parentAction/thisAction' |
| stato | "success" o "failure" a seconda che l'azione sia riuscita o meno |
| errore | Impostato solo quando status=failure. Contiene il tipo di errore che ha causato l'errore |
| origine | La lingua di origine di Genkit. Ad es. 'ts' |
| sourceVersion | La versione del framework Genkit |
Generare metriche
Si tratta di metriche di azioni speciali relative alle azioni che interagiscono con un modello. Oltre alle richieste e alla latenza, vengono monitorati anche input e output, con dimensioni specifiche del modello che semplificano il debug e la regolazione della configurazione.
| Nome | Tipo | Descrizione |
|---|---|---|
| genkit/ai/generate/requests | Contatore | Numero di volte in cui questo modello è stato chiamato |
| genkit/ai/generate/latency | Istogramma | Latenza di esecuzione in ms |
| genkit/ai/generate/input/tokens | Contatore | Token di input |
| genkit/ai/generate/output/tokens | Contatore | Token di output |
| genkit/ai/generate/input/characters | Contatore | Caratteri dell'input |
| genkit/ai/generate/output/characters | Contatore | Caratteri di output |
| genkit/ai/generate/input/images | Contatore | Immagini di input |
| genkit/ai/generate/output/images | Contatore | Immagini di output |
| genkit/ai/generate/input/audio | Contatore | Inserire file audio |
| genkit/ai/generate/output/audio | Contatore | File audio di output |
Ogni metrica generata contiene le seguenti dimensioni:
| Nome | Descrizione |
|---|---|
| modelName | Il nome del modello |
| featureName | Il nome della funzionalità principale in esecuzione |
| percorso | Il percorso di esecuzione dalla radice della funzionalità a questa azione. Ad es. '/myFeature/parentAction/thisAction' |
| latencyMs | Il tempo di risposta del modello |
| stato | "success" o "failure" a seconda che la richiesta di funzionalità sia andata a buon fine o meno |
| errore | Impostato solo quando status=failure. Contiene il tipo di errore che ha causato l'errore |
| origine | La lingua di origine di Genkit. Ad es. 'ts' |
| sourceVersion | La versione del framework Genkit |
La visualizzazione delle metriche può essere eseguita tramite Metrics Explorer. Nel menu a sinistra, fai clic su "Esplora metriche" sotto l'intestazione "Esplora".
Seleziona una metrica facendo clic sul menu a discesa "Seleziona una metrica", selezionando "Nodo generico", "Genkit" e una metrica.
La visualizzazione della metrica dipende dal suo tipo (contatore, istogramma e così via). Metrics Explorer fornisce solide funzionalità di aggregazione e query per aiutare a visualizzare le metriche in base alle varie dimensioni.
Ritardo della telemetria
Potrebbe verificarsi un leggero ritardo prima che la telemetria per una determinata esecuzione di un flusso venga visualizzata nella suite di operazioni di Cloud. Nella maggior parte dei casi, questo ritardo è inferiore a 1 minuto.
Quote e limiti
Esistono diverse quote da tenere presenti:
Costo
Cloud Logging, Cloud Trace e Cloud Monitoring offrono livelli senza costi generosi. I prezzi specifici sono disponibili ai seguenti link: