Gateway di ingest

Le tue applicazioni mandano errori, log e metriche a CloseYourIt. Quei dati possono arrivare in due modi: diretto, che è quello che hai dopo l'installazione, e attraverso il gateway, che accendi con un comando.

Le due strade

Diretto (predefinito)

la tua applicazione  →  Caddy  →  app  →  worker  →  database

1. La tua applicazione manda una richiesta a https://<tuo-dominio>/api/….
2. Caddy, il web server, la passa all'app.
3. L'app controlla il token e risponde 202.
4. Il worker salva i dati un attimo dopo.

Se al passo 2 l'app sta ripartendo o è troppo occupata, la richiesta fallisce. I dati si perdono, a meno che chi li manda non riprovi.

Attraverso il gateway

la tua applicazione  →  Caddy  →  gateway  →  app  →  worker  →  database
                                     ↓ l'app non risponde
                                   coda  →  app, più tardi

1. La tua applicazione manda la stessa richiesta allo stesso indirizzo.
2. Caddy passa i dati in arrivo al gateway. Tutto il resto sotto /api/ — la lettura dei dati, l'Automator — continua ad andare dritto all'app.
3. Il gateway inoltra la richiesta all'app e aspetta qualche secondo.
4. Se l'app risponde, anche con un errore come 401 o 422, la tua applicazione riceve quella risposta. Non si mette niente in coda.
5. Se l'app non risponde, è sovraccarica (429) o va in errore (5xx), il gateway salva la richiesta, cifrata, in una coda (NATS JetStream) e risponde subito 202.
6. Il gateway continua a provare a consegnare quello che c'è in coda finché l'app non lo prende.

A confronto

Quando ti serve

• Molte applicazioni mandano dati, o una ne manda tanti.
• Aggiorni spesso e non vuoi perdere dati durante i riavvii.

Per un piccolo team con pochi progetti puoi farne a meno.

Passare dal diretto al gateway

Nelle tue applicazioni non cambia niente: stesso indirizzo, stessi token. Non si sposta nessun dato, e puoi tornare indietro quando vuoi.

1. Controlla che ci sia spazio: df -h /opt/closeyourit deve mostrare almeno 6 GB liberi.
2. Accendilo:

   closeyourit enable ingest
   

   Copia
3. Controlla che gateway e nats siano accesi accanto ad app, worker, postgres e caddy:

   closeyourit status
   

   Copia
4. Manda una richiesta a mano (vedi l'API HTTP) e controlla che compaia in CloseYourIt.

Il passaggio dura qualche secondo. Una richiesta che arriva in quel momento può fallire. Caddy passa al gateway solo quando il gateway è rimasto acceso: se non succede, il comando lo dice, lo rispegne e i dati continuano ad andare dritti all'app.

Come capire se una richiesta è finita in coda

Quando il gateway tiene una richiesta invece di consegnarla subito, risponde 202 con l'intestazione X-CloseYourIt-Queued: true (gli indirizzi compatibili con Sentry rispondono 200, come si aspettano quegli SDK). Quella risposta vuol dire "al sicuro in coda", non "già salvata in CloseYourIt".

Cosa accetta il gateway

Solo gli indirizzi che ricevono dati: eventi, metriche, log, visite, registrazioni, rilasci, segnali dei cron, campioni dei server e i due indirizzi compatibili con Sentry. Vedi l'API HTTP.

Tutto il resto sotto /api/ — la lettura dei dati, l'Automator che prende lavoro — continua ad andare dritto all'app, con il gateway acceso o spento.

Quando la coda è piena, le richieste nuove vengono rifiutate invece di buttare quelle già in attesa.

Una richiesta che continua a fallire si riprova con pause sempre più lunghe. Dopo 20 tentativi passa nell'archivio "non consegnate" e non si riprova più.

La lettura dei dati o l'Automator hanno smesso di funzionare

Le prime installazioni mandavano al gateway tutto /api/, che rifiuta quello che non conosce: la lettura dei dati risponde 405 e l'Automator riceve 404. Lancia closeyourit update: porta anche il file del web server della versione nuova.

La chiave di cifratura

Le richieste in coda sono cifrate con la chiave in /opt/closeyourit/ingest/envelope_key. La password della coda è in /opt/closeyourit/ingest/nats_password. Si generano entrambe all'installazione. Se sostituisci la chiave mentre ci sono richieste in attesa, quelle richieste non si possono più leggere.

Tornare al diretto

closeyourit disable ingest

Le richieste tornano subito alla strada diretta. Il gateway ha poi 30 secondi per consegnare quello che è ancora in attesa, e si ferma. Quello che non è stato consegnato resta nella coda su disco e si consegna la prossima volta che accendi il gateway.

Fallo quando l'app sta bene, così la coda è già vuota.

OpenTelemetry si configura a parte

Il ricevitore OTLP, facoltativo, ha ascoltatori, autenticazione e limiti delle richieste suoi. Accendere questo gateway di ingest nativo non espone e non attiva quegli ascoltatori da solo.