Scrittura di dati nel cluster Timestream for InfluxDB 3

Amazon Timestream for InfluxDB 3 offre solide funzionalità per l'acquisizione efficiente di dati di serie temporali. Comprendere i metodi corretti per scrivere i dati è essenziale per massimizzare le prestazioni e garantire l'integrità dei dati.

Timestream for InfluxDB 3 fornisce più endpoint API HTTP per la scrittura di dati di serie temporali, offrendo flessibilità per diversi metodi di integrazione e compatibilità con i carichi di lavoro InfluxDB esistenti.

Panoramica del protocollo di linea

InfluxDB 3 è progettato per un elevato throughput di scrittura e utilizza una sintassi di scrittura efficiente e leggibile dall'uomo chiamata protocollo di linea. Come schema-on-write database, InfluxDB crea automaticamente il database logico, le tabelle e i relativi schemi quando inizi a scrivere i dati, senza richiedere alcuna configurazione manuale. Una volta creato lo schema, InfluxDB convalida le future richieste di scrittura rispetto ad esso prima di accettare nuovi dati, pur consentendo l'evoluzione dello schema man mano che le esigenze cambiano.

Struttura del protocollo di linea

Il protocollo di linea è costituito dai seguenti elementi essenziali:

• Tabella: un identificatore di stringa per la tabella in cui verranno archiviati i dati.

• (Facoltativo) Set di tag: coppie chiave-valore delimitate da virgole che rappresentano metadati (indicizzati).

• Set di campi: coppie chiave-valore delimitate da virgole che rappresentano le misurazioni effettive.

• (Facoltativo) Timestamp: timestamp Unix associato al punto dati con una precisione massima di nanosecondi.

I valori dei campi possono essere uno dei seguenti tipi di dati:

• Stringhe (devono essere citate)

• Float (ad esempio, 23.4)

• Numeri interi (ad esempio, 10i)

• Numeri interi senza segno (ad esempio, 10u)

• Booleani (vero/falso)

Il protocollo di linea segue questa sintassi generale:

myTable,tag1=val1,tag2=val2 field1="v1",field2=1i 0000000000000000000

Esempio di punto dati che utilizza il protocollo di linea:

home,room=Living\ Room temp=21.1,hum=35.9,co=0i 1735545600

Questo crea un punto nella tabella «home» con:

• Tag: room="Soggiorno»

• Campi: temp=21.1 (float), hum=35.9 (float), co=0 (intero)

• Timestamp: 1735545600 (secondi Unix)

Panoramica degli endpoint API

InfluxDB 3 supporta tre endpoint di scrittura primari:

1. API v3 nativa (/api/v3/write_lp): l'endpoint consigliato per nuove implementazioni.

2. API di compatibilità v2 (/api/v2/write): per la migrazione dei carichi di lavoro InfluxDB v2.x.

3. API di compatibilità v1 (): per la migrazione dei carichi di lavoro InfluxDB v1.x/write.

Utilizzo dell'API di scrittura nativa v3

L'/api/v3/write_lpendpoint è l'API nativa di InfluxDB 3 per la scrittura dei dati del protocollo di linea.

Formato della richiesta:

POST /api/v3/write_lp?db=DATABASE_NAME&precision=PRECISION&accept_partial=BOOLEAN&no_sync=BOOLEAN

Parametri di interrogazione:

Parameter	Descrizione	Impostazione predefinita
db	Nome del database (obbligatorio)	-
precision	Precisione del timestamp (ns, us, ms, s)	Rilevato automaticamente
accept_partial	Accetta scritture parziali sugli errori	true
no_sync	Riconosci prima della persistenza WAL	false

Esempio di richiesta di scrittura:

curl -v "https://your-cluster-endpoint:8086/api/v3/write_lp?db=sensors&precision=s" \
  --header "Authorization: Bearer YOUR_TOKEN" \
  --data-raw "home,room=Living\ Room temp=21.1,hum=35.9,co=0i 1735545600
home,room=Kitchen temp=21.0,hum=35.9,co=0i 1735545600"

Modalità di risposta di scrittura

Modalità standard (no_sync=false)

• Attende che i dati vengano scritti nel WAL (Write-Ahead Log) prima di confermarli.

• Fornisce garanzie di durabilità.

• Latenza più elevata grazie all'attesa di persistenza WAL.

• Consigliato per dati critici in cui la durabilità è essenziale.

Modalità veloce (no_sync=true)

• Riconosce immediatamente senza attendere la persistenza WAL.

• Latenza di scrittura più bassa possibile.

• Rischio di perdita di dati in caso di arresto anomalo del sistema prima del completamento della scrittura WAL.

• Ideale per scenari ad alta produttività in cui la velocità è prioritaria rispetto alla durabilità assoluta.

Gestione parziale della scrittura

Il accept_partial parametro controlla il comportamento quando i batch di scrittura contengono errori:

Quando accept_partial è true (impostazione predefinita):

• Le righe valide vengono scritte correttamente.

• Le righe non valide vengono rifiutate.

• Restituisce lo stato 400 con dettagli sulle righe non riuscite.

• Utile per operazioni in batch di grandi dimensioni in cui alcuni errori sono accettabili.

Quando accept_partial è false:

• L'intero batch viene rifiutato in caso di errore di una riga.

• Non viene scritto alcun dato.

• Restituisce lo stato 400 con i dettagli dell'errore.

• Garantisce la semantica di all-or-nothing scrittura.

Compatibilità APIs

La compatibilità APIs consente la migrazione senza interruzioni dei carichi di lavoro InfluxDB v1 o v2 esistenti su InfluxDB 3. Questi endpoint funzionano con le librerie client InfluxDB esistenti, Telegraf e integrazioni di terze parti.

Differenze importanti:

• I tag in una tabella (misurazione) sono immutabili una volta creati.

• Un tag e un campo non possono avere lo stesso nome all'interno di una tabella.

• La convalida dello schema viene applicata in fase di scrittura.

Compatibilità con InfluxDB v2

L'/api/v2/writeendpoint offre la compatibilità con le versioni precedenti per i client v2:

curl -i "https://your-cluster-endpoint:8086/api/v2/write?bucket=DATABASE_NAME&precision=s" \
  --header "Authorization: Bearer DATABASE_TOKEN" \
  --header "Content-type: text/plain; charset=utf-8" \
  --data-binary 'home,room=kitchen temp=72 1641024000'

Parametri dell'API V2:

Parameter	Location (Ubicazione)	Descrizione
bucket *	Stringa di query	Mappe al nome del database
precision	Stringa di query	Precisione del timestamp (ns, us, ms, s, m, h)
Authorization	Header	Schema Bearer o Token
Content-Encoding	Header	gzip o identity

Compatibilità con InfluxDB v1

L'/writeendpoint offre la compatibilità con le versioni precedenti per i client v1:

curl -i "https://your-cluster-endpoint:8086/write?db=DATABASE_NAME&precision=s" \
  --user "any:DATABASE_TOKEN" \
  --header "Content-type: text/plain; charset=utf-8" \
  --data-binary 'home,room=kitchen temp=72 1641024000'

Opzioni di autenticazione V1:

• Autenticazione di base: token come password (--user "any:TOKEN").

• Parametro di interrogazione: p=TOKEN nell'URL.

• Bearer/Token intestazione: intestazione di autorizzazione standard.

Parametri dell'API V1:

Parameter	Location (Ubicazione)	Descrizione
db *	Stringa di query	Nome del database
precision	Stringa di query	Precisione del timestamp
p	Stringa di query	Token per l'autenticazione delle query
u	Stringa di query	Nome utente (ignorato)
Authorization	Header	Sono supportati più schemi
Content-Encoding	Header	gzip o identity

Librerie e integrazioni client

Librerie client ufficiali di InfluxDB 3

Le librerie client InfluxDB 3 forniscono interfacce in lingua nativa per la costruzione e la scrittura di dati di serie temporali:

• Python: influxdb3-python

• Vai: influxdb3-go

• JavaScript/Node.js: influxdb3-js

• Giava: influxdb3-java

• C#: InfluxDB3.Client

Esempio: client Python

from influxdb3 import InfluxDBClient3

client = InfluxDBClient3(
    host="your-cluster-endpoint:8086",
    token="YOUR_TOKEN",
    database="DATABASE_NAME"
)

# Write using line protocol
client.write("home,room=Living\\ Room temp=21.1,hum=35.9,co=0i")

# Write using Point objects
from influxdb3 import Point
point = Point("home") \
    .tag("room", "Living Room") \
    .field("temp", 21.1) \
    .field("hum", 35.9) \
    .field("co", 0)
    
client.write(point)

Esempio: client Go

import "github.com/InfluxCommunity/influxdb3-go/v2/influxdb3"

client, err := influxdb3.New(influxdb3.ClientConfig{
    Host: "your-cluster-endpoint:8086",
    Token: "YOUR_TOKEN",
    Database: "DATABASE_NAME",
})

point := influxdb3.NewPoint("home",
    map[string]string{"room": "Living Room"},
    map[string]any{
        "temp": 24.5,
        "hum":  40.5,
        "co":   15,
    },
    time.Now(),
)

err = client.WritePoints(context.Background(), []*influxdb3.Point{point})

Librerie client precedenti

Per i carichi di lavoro v1 e v2 esistenti, puoi continuare a utilizzare le librerie client legacy con gli endpoint di compatibilità:

Esempio: client Node.js v1:

const Influx = require('influx')

const client = new Influx.InfluxDB({
  host: 'your-cluster-endpoint',
  port: 8086,
  protocol: 'https',
  database: 'DATABASE_NAME',
  username: 'ignored',
  password: 'DATABASE_TOKEN'
})

Le migliori pratiche per la scrittura dei dati

Durante la scrittura di dati, consigliamo quanto segue:

• Ottimizzazione dei batch

  • Dimensione ottimale del batch: 5.000-10.000 righe o 10 MB per richiesta.

  • Usa la compressione (gzip) per carichi utili di grandi dimensioni.

  • Ordina i tag per chiave in ordine lessicografico per prestazioni migliori.

• Precisione del timestamp

  • Usa la massima precisione che soddisfa le tue esigenze.

  • Specificate esplicitamente la precisione per evitare ambiguità.

  • Mantieni una precisione costante in tutta l'applicazione.

• Gestione degli errori

  • Implementa la logica di ripetizione dei tentativi per guasti transitori.

  • Usa accept_partial=true per operazioni batch resilienti.

  • Monitora gli errori di scrittura tramite metriche. CloudWatch

• Ottimizzazione prestazioni

  • Usa no_sync=true per scenari ad alto rendimento.

  • Distribuisci le scritture su più connessioni.

  • Usa l' writer/reader endpoint per tutte le operazioni di scrittura.

• Considerazioni sullo schema

  • I tag sono immutabili una volta creati.

  • I campi e i tag non possono avere lo stesso nome.

  • Progetta schemi tenendo conto dei modelli di interrogazione.

  • Tieni sotto controllo la cardinalità dei tag.

Differenze importanti rispetto alle versioni precedenti:

• Tag immutabili: una volta creato un tag in una tabella, il suo tipo non può essere modificato

• Nessun conflitto di tag/field nomi: un tag e un campo non possono avere lo stesso nome all'interno di una tabella

• Schema-on-write: InfluxDB 3 convalida i tipi di dati in fase di scrittura

• Creazione automatica di tabelle: le tabelle vengono create automaticamente alla prima scrittura

• Controllo rigoroso dei tipi: i tipi di campo devono rimanere coerenti in tutte le scritture

Sfruttando l'API di scrittura appropriata e seguendo queste best practice, puoi importare in modo efficiente i dati di serie temporali nella tua istanza Timestream for InfluxDB 3, mantenendo al contempo alte prestazioni e integrità dei dati.