Suggerimenti e trucchi

Questo documento descrive le best practice per la progettazione, l'implementazione, il test e il deployment di Cloud Functions.

Correttezza

Questa sezione descrive le best practice generali per la progettazione e l'implementazione di Cloud Functions.

Scrivere funzioni idempotenti

Le funzioni devono produrre lo stesso risultato anche se vengono chiamate più volte. In questo modo puoi riprovare un'invocazione se la precedente non va a buon fine a metà del codice. Per saperne di più, consulta Riprovare le funzioni basate su eventi.

Non avviare attività in background

L'attività in background è tutto ciò che accade dopo la chiusura della funzione. Una chiamata di funzione termina quando la funzione restituisce o segnala il completamento, ad esempio chiamando l'argomento callback nelle funzioni basate su eventi Node.js. Qualsiasi codice eseguito dopo l'arresto normale non può accedere alla CPU e non farà alcun progresso.

Inoltre, quando una chiamata successiva viene eseguita nello stesso ambiente, l'attività in background riprende, interferendo con la nuova chiamata. Ciò potrebbe comportare errori e comportamenti imprevisti difficili da diagnosticare. L'accesso alla rete dopo la terminazione di una funzione di solito comporta il ripristino delle connessioni (codice di errore ECONNRESET).

L'attività in background può spesso essere rilevata nei log delle singole chiamate, trovando qualsiasi elemento registrato dopo la riga che indica che la chiamata è terminata. L'attività in background a volte può essere nascosta più in profondità nel codice, soprattutto quando sono presenti operazioni asincrone come callback o timer. Controlla il codice per assicurarti che tutte le operazioni asincrone vengano completate prima di terminare la funzione.

Eliminare sempre i file temporanei

Lo spazio di archiviazione del disco locale nella directory temporanea è un file system in memoria. I file che scrivi consumano la memoria disponibile per la tua funzione e a volte persistono tra le chiamate. Se non elimini esplicitamente questi file, alla fine potresti riscontrare un errore di memoria insufficiente e un successivo riavvio a freddo.

Puoi visualizzare la memoria utilizzata da una singola funzione selezionandola nell'elenco delle funzioni nella console Google Cloud e scegliendo il grafico Utilizzo della memoria.

Se hai bisogno di accedere a uno spazio di archiviazione a lungo termine, valuta la possibilità di utilizzare i montaggi dei volumi Cloud Run con Cloud Storage o volumi NFS.

Puoi ridurre i requisiti di memoria durante l'elaborazione di file più grandi utilizzando il pipelining. Ad esempio, puoi elaborare un file su Cloud Storage creando un flusso di lettura, passandolo attraverso un processo basato sul flusso e scrivendo il flusso di output direttamente su Cloud Storage.

Framework di Functions

Per garantire che le stesse dipendenze vengano installate in modo coerente in tutti gli ambienti, ti consigliamo di includere la libreria Functions Framework nel gestore dei pacchetti e di bloccare la dipendenza a una versione specifica di Functions Framework.

A questo scopo, includi la versione che preferisci nel file di blocco pertinente (ad esempio, package-lock.json per Node.js o requirements.txt per Python).

Se Functions Framework non è elencato esplicitamente come dipendenza, verrà aggiunto automaticamente durante il processo di build utilizzando l'ultima versione disponibile.

Strumenti

Questa sezione fornisce linee guida su come utilizzare gli strumenti per implementare, testare e interagire con Cloud Functions.

Sviluppo locale

Il deployment della funzione richiede un po' di tempo, quindi spesso è più veloce testare il codice della funzione localmente.

Evita i timeout di deployment durante l'inizializzazione

Se il deployment della funzione non riesce e viene visualizzato un errore di timeout, è probabile che il codice dell'ambito globale della funzione richieda troppo tempo per essere eseguito durante il processo di deployment.

L'interfaccia a riga di comando Firebase ha un timeout predefinito per il rilevamento delle funzioni durante il deployment. Se la logica di inizializzazione nel codice sorgente delle funzioni (caricamento dei moduli, esecuzione di chiamate di rete e così via) supera questo timeout, il deployment potrebbe non riuscire.

Per evitare il timeout, utilizza una delle seguenti strategie:

(Consigliato) Utilizza onInit() per posticipare l'inizializzazione

Utilizza l'hook onInit() per evitare di eseguire il codice di inizializzazione durante il deployment. Il codice all'interno dell'hook onInit() viene eseguito solo quando la funzione viene implementata in Cloud Run Functions, non durante il processo di deployment stesso.

const { onInit } = require('firebase-functions/v2/core');
const { onRequest } = require('firebase-functions/v2/https');

// Example of a slow initialization task
function slowInitialization() {
  // Simulate a long-running operation (e.g., loading a large model, network request).
  return new Promise(resolve => {
      setTimeout(() => {
          console.log("Slow initialization complete");
          resolve("Initialized Value");
      }, 20000); // Simulate a 20-second delay
  });
}
let initializedValue;

onInit(async () => {
  initializedValue = await slowInitialization();
});

exports.myFunction = onRequest((req, res) => {
  // Access the initialized value. It will be ready after the first invocation.
  res.send(`Value: ${initializedValue}`);
});

from firebase_functions.core import init
from firebase_functions import https_fn
import time

# Example of a slow initialization task
def _slow_initialization():
  time.sleep(20)  # Simulate a 20-second delay
  print("Slow initialization complete")
  return "Initialized Value"

_initialized_value = None

@init
def initialize():
  global _initialized_value
  _initialized_value = _slow_initialization()

@https_fn.on_request()
def my_function(req: https_fn.Request) -> https_fn.Response:
  # Access the initialized value. It will be ready after the first invocation.
  return https_fn.Response(f"Value: {_initialized_value}")

(Alternativa) Aumenta il timeout di rilevamento

Se non riesci a eseguire il refactoring del codice per utilizzare onInit(), puoi aumentare il timeout di deployment della CLI utilizzando la variabile di ambiente FUNCTIONS_DISCOVERY_TIMEOUT:

$ export FUNCTIONS_DISCOVERY_TIMEOUT=30
$ firebase deploy --only functions

Utilizzare SendGrid per inviare email

Cloud Functions non consente connessioni in uscita sulla porta 25, pertanto non puoi stabilire connessioni non sicure a un server SMTP. Il modo consigliato per inviare email è utilizzare un servizio di terze parti come SendGrid. Puoi trovare altre opzioni per l'invio di email nel tutorial Invio di email da un'istanza per Google Compute Engine.

Prestazioni

Questa sezione descrive le best practice per ottimizzare il rendimento.

Evitare una bassa concorrenza

Poiché gli avvii completi sono costosi, la possibilità di riutilizzare istanze avviate di recente durante un picco è un'ottima ottimizzazione per gestire il carico. La limitazione della concorrenza limita il modo in cui è possibile sfruttare le istanze esistenti, causando quindi più avvii a freddo.

Utilizzare le dipendenze in modo strategico

Poiché le funzioni sono stateless, l'ambiente di esecuzione viene spesso inizializzato da zero (durante quello che è noto come avvio a freddo). Quando si verifica un avvio a freddo, viene valutato il contesto globale della funzione.

Se le tue funzioni importano moduli, il tempo di caricamento di questi moduli può aumentare la latenza di chiamata durante un avvio a freddo. Puoi ridurre questa latenza, nonché il tempo necessario per il deployment della funzione, caricando correttamente le dipendenze e non caricando le dipendenze che la funzione non utilizza.

Utilizza le variabili globali per riutilizzare gli oggetti nelle chiamate future

Non è garantito che lo stato di una funzione venga preservato per le invocazioni future. Tuttavia, Cloud Functions spesso ricicla l'ambiente di esecuzione di una chiamata precedente. Se dichiari una variabile nell'ambito globale, il suo valore può essere riutilizzato nelle invocazioni successive senza dover essere ricalcolato.

In questo modo puoi memorizzare nella cache gli oggetti che potrebbero essere costosi da ricreare a ogni invocazione di funzione. Lo spostamento di questi oggetti dal corpo della funzione all'ambito globale può comportare miglioramenti significativi delle prestazioni. Il seguente esempio crea un oggetto pesante una sola volta per istanza di funzione e lo condivide tra tutte le chiamate di funzione che raggiungono l'istanza specificata:

console.log('Global scope');
const perInstance = heavyComputation();
const functions = require('firebase-functions');

exports.function = functions.https.onRequest((req, res) => {
  console.log('Function invocation');
  const perFunction = lightweightComputation();

  res.send(`Per instance: ${perInstance}, per function: ${perFunction}`);
});

import time

from firebase_functions import https_fn

# Placeholder
def heavy_computation():
  return time.time()

# Placeholder
def light_computation():
  return time.time()

# Global (instance-wide) scope
# This computation runs at instance cold-start
instance_var = heavy_computation()

@https_fn.on_request()
def scope_demo(request):

  # Per-function scope
  # This computation runs every time this function is called
  function_var = light_computation()
  return https_fn.Response(f"Instance: {instance_var}; function: {function_var}")
  

È particolarmente importante memorizzare nella cache le connessioni di rete, i riferimenti alle librerie e gli oggetti client API nell'ambito globale. Per esempi, consulta la sezione Ottimizzazione del networking.

Ridurre gli avvii a freddo impostando un numero minimo di istanze

Per impostazione predefinita, Cloud Functions adatta il numero di istanze in base al numero di richieste in entrata. Puoi modificare questo comportamento predefinito impostando un numero minimo di istanze che Cloud Functions deve mantenere pronte per gestire le richieste. L'impostazione di un numero minimo di istanze riduce gli avvii a freddo della tua applicazione. Se la tua applicazione è sensibile alla latenza, ti consigliamo di impostare un numero minimo di istanze e di completare l'inizializzazione al momento del caricamento.

Note sull'avvio completo e sull'inizializzazione

L'inizializzazione globale avviene al momento del caricamento. Senza, la prima richiesta dovrebbe completare l'inizializzazione e caricare i moduli, con conseguente latenza maggiore.

Tuttavia, l'inizializzazione globale ha un impatto anche sugli avvii a freddo. Per ridurre al minimo questo impatto, inizializza solo ciò che è necessario per la prima richiesta, in modo da mantenere la latenza della prima richiesta il più bassa possibile.

Ciò è particolarmente importante se hai configurato le istanze minime come descritto sopra per una funzione sensibile alla latenza. In questo scenario, il completamento dell'inizializzazione al momento del caricamento e la memorizzazione nella cache dei dati utili garantiscono che la prima richiesta non debba farlo e venga gestita con una latenza bassa.

Se inizializzi le variabili nell'ambito globale, a seconda del linguaggio, tempi di inizializzazione lunghi possono comportare due comportamenti: - Per alcune combinazioni di linguaggi e librerie asincrone, il framework della funzione può essere eseguito in modo asincrono e restituire immediatamente un valore, causando l'esecuzione continua del codice in background, il che potrebbe causare problemi come l'impossibilità di accedere alla CPU. Per evitare questo problema, devi bloccare l'inizializzazione del modulo come descritto di seguito. In questo modo, le richieste non vengono pubblicate finché l'inizializzazione non è completata. - D'altra parte, se l'inizializzazione è sincrona, il lungo tempo di inizializzazione causerà avvii a freddo più lunghi, il che potrebbe essere un problema soprattutto con le funzioni a bassa concorrenza durante i picchi di carico.

Esempio di pre-riscaldamento di una libreria Node.js asincrona

Node.js con Firestore è un esempio di libreria Node.js asincrona. Per sfruttare min_instances, il seguente codice completa il caricamento e l'inizializzazione al momento del caricamento, bloccando il caricamento del modulo.

Viene utilizzato TLA, il che significa che è necessario ES6, utilizzando un'estensione .mjs per il codice node.js o aggiungendo type: module al file package.json.

{
  "main": "main.js",
  "type": "module",
  "dependencies": {
    "@google-cloud/firestore": "^7.10.0",
    "@google-cloud/functions-framework": "^3.4.5"
  }
}

import Firestore from '@google-cloud/firestore';
import * as functions from '@google-cloud/functions-framework';

const firestore = new Firestore({preferRest: true});

// Pre-warm firestore connection pool, and preload our global config
// document in cache. In order to ensure no other request comes in,
// block the module loading with a synchronous global request:
const config = await firestore.collection('collection').doc('config').get();

functions.http('fetch', (req, res) => {

// Do something with config and firestore client, which are now preloaded
// and will execute at lower latency.
});

Esempi di inizializzazione globale

const functions = require('firebase-functions');
let myCostlyVariable;

exports.function = functions.https.onRequest((req, res) => {
  doUsualWork();
  if(unlikelyCondition()){
      myCostlyVariable = myCostlyVariable || buildCostlyVariable();
  }
  res.status(200).send('OK');
});

from firebase_functions import https_fn

# Always initialized (at cold-start)
non_lazy_global = file_wide_computation()

# Declared at cold-start, but only initialized if/when the function executes
lazy_global = None

@https_fn.on_request()
def lazy_globals(request):

  global lazy_global, non_lazy_global

  # This value is initialized only if (and when) the function is called
  if not lazy_global:
      lazy_global = function_specific_computation()

  return https_fn.Response(f"Lazy: {lazy_global}, non-lazy: {non_lazy_global}.")
  

Ciò è particolarmente importante se definisci più funzioni in un unico file e funzioni diverse utilizzano variabili diverse. A meno che tu non utilizzi l'inizializzazione differita, potresti sprecare risorse per variabili inizializzate ma mai utilizzate.

Risorse aggiuntive

Scopri di più sull'ottimizzazione delle prestazioni nel video "Google Cloud Performance Atlas" Cloud Functions Cold Boot Time.