Per funzionalità simili a Amazon Timestream for, prendi in considerazione Amazon Timestream LiveAnalytics per InfluxDB. Offre un'acquisizione semplificata dei dati e tempi di risposta alle query di una sola cifra di millisecondi per analisi in tempo reale. [Scopri](https://docs.aws.amazon.com//timestream/latest/developerguide/timestream-for-influxdb.html) di più qui. Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà. # 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.](https://docs.influxdata.com/influxdb3/core/reference/line-protocol/) 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. 1. **API di compatibilità v2** (`/api/v2/write`): per la migrazione dei carichi di lavoro InfluxDB v2.x. 1. **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_lp`endpoint è 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\$1partial | Accetta scritture parziali sugli errori | true | | no\$1sync | 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/write`endpoint 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 \$1 | 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'`/write`endpoint 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 \$1 | 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\$1:** `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' }) ``` # Integrazione di Telegraf con Timestream per InfluxDB 3 Telegraf è un agente di raccolta dati basato su plug-in con oltre 300 plug-in di input per la raccolta di metriche da varie fonti e plug-in di output per la scrittura di dati verso diverse destinazioni. La sua architettura "plug-and-play" lo rende ideale per raccogliere e riportare rapidamente le metriche su InfluxDB 3. ## Requisiti + [Telegraf 1.9.2 o versione successiva — Per le istruzioni di installazione, consulta la documentazione di installazione di Telegraf.](https://docs.influxdata.com/telegraf/latest/install/) + Endpoint e credenziali del cluster InfluxDB 3. + Connettività di rete al cluster InfluxDB 3. ## Opzioni di configurazione di Telegraf Telegraf fornisce due plugin di output compatibili con InfluxDB 3: 1. `outputs.influxdb_v2`- Consigliato per nuove implementazioni. 1. `outputs.influxdb`(v1) - Per le configurazioni v1 esistenti. ### Utilizzo del plugin di output v2 Ti consigliamo di utilizzare il `outputs.influxdb_v2` plug-in per connetterti all'API di compatibilità InfluxDB v2: ``` [[outputs.influxdb_v2]] urls = ["https://your-cluster-endpoint:8086"] token = "${INFLUX_TOKEN}" # Use environment variable for security organization = "" # Can be left empty for InfluxDB 3 bucket = "DATABASE_NAME" ## Optional: Enable gzip compression content_encoding = "gzip" ## Optional: Increase timeout for high-latency networks timeout = "10s" ## Optional: Configure batching metric_batch_size = 5000 metric_buffer_limit = 50000 ``` ### Utilizzo del plug-in di output v1 precedente Per le configurazioni Telegraf esistenti che utilizzano il plugin v1: ``` [[outputs.influxdb]] urls = ["https://your-cluster-endpoint:8086"] database = "DATABASE_NAME" skip_database_creation = true username = "ignored" # Required but ignored password = "${INFLUX_TOKEN}" # Use environment variable content_encoding = "gzip" ## Optional: Configure write parameters timeout = "10s" metric_batch_size = 5000 metric_buffer_limit = 50000 ``` ## Esempio di configurazione di base di Telegraf Quello che segue è un esempio completo che raccoglie le metriche di sistema e le scrive su InfluxDB 3: ``` # Global Agent Configuration [agent] interval = "10s" round_interval = true metric_batch_size = 5000 metric_buffer_limit = 50000 collection_jitter = "0s" flush_interval = "10s" flush_jitter = "0s" precision = "s" hostname = "" omit_hostname = false # Input Plugins - Collect system metrics [[inputs.cpu]] percpu = true totalcpu = true collect_cpu_time = false report_active = false [[inputs.disk]] ignore_fs = ["tmpfs", "devtmpfs", "devfs", "iso9660", "overlay", "aufs", "squashfs"] [[inputs.mem]] [[inputs.net]] interfaces = ["eth*", "en*"] [[inputs.system]] # Output Plugin - Write to InfluxDB 3 [[outputs.influxdb_v2]] urls = ["https://your-cluster-endpoint:8086"] token = "${INFLUX_TOKEN}" organization = "" bucket = "telegraf_metrics" content_encoding = "gzip" ``` ## Le migliori pratiche per Telegraf con InfluxDB 3 + **Sicurezza** + Memorizza i token in variabili di ambiente o archivi segreti. + Non codificare mai i token nei file di configurazione. + Usa gli endpoint HTTPS per le implementazioni di produzione. + **Ottimizzazione delle prestazioni** + Abilita la compressione gzip con content\$1encoding = «gzip». + Configura le dimensioni dei batch appropriate (5000-10000 metriche). + Imposta i limiti del buffer in base alla memoria disponibile. + Usa la precisione appropriata al tuo caso d'uso (i secondi spesso sono sufficienti). + **Configurazione della rete** + Per i cluster privati, esegui Telegraf all'interno dello stesso VPC. + Configura i timeout appropriati per la latenza della tua rete. + Usa l' writer/reader endpoint per le operazioni di scrittura. + **Monitoraggio** + Abilita il plug-in per le metriche interne di Telegraf per monitorare le prestazioni degli agenti. + Monitora gli errori di scrittura e i nuovi tentativi. + Imposta avvisi per le condizioni di sovraccarico del buffer. + **Organizzazione dei dati** + Usa una denominazione dei tag coerente tra i plugin di input. + Sfrutta i plugin del processore di Telegraf per normalizzare i dati. + Applica il filtro dei tag per controllare la cardinalità. ## Esecuzione di Telegraf Per avviare Telegraf con la tua configurazione, procedi come segue: ``` # Test configuration telegraf --config telegraf.conf --test # Run Telegraf telegraf --config telegraf.conf # Run as a service (systemd) sudo systemctl start telegraf ``` ### Plugin Telegraf comuni per i dati delle serie temporali **Plugin di input popolari:** + `inputs.cpu`,`inputs.mem`, `inputs.disk` - Metriche di sistema. + `inputs.docker`, `inputs.kubernetes` - Metriche dei container. + `inputs.prometheus`- Raschia i punti finali di Prometheus. + `inputs.snmp`- Monitoraggio dei dispositivi di rete. + `inputs.mqtt_consumer`- Raccolta dati IoT. + `inputs.http_listener_v2`- Ricevitore webhook HTTP. **Utili plugin per processori:** + `processors.regex`- Trasforma i tag/field nomi. + `processors.converter`- Modifica i tipi di dati dei campi. + `processors.aggregator`- Metriche aggregate. + `processors.filter`- Filtra le metriche in base alle condizioni. Sfruttando l'ampio ecosistema di plugin di Telegraf con InfluxDB 3, puoi creare soluzioni di monitoraggio complete che raccolgono dati da diverse fonti e li scrivono in modo efficiente nel tuo database di serie temporali. ## 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\$1partial=true per operazioni batch resilienti. + Monitora gli errori di scrittura tramite metriche. CloudWatch + Ottimizzazione prestazioni + Usa no\$1sync=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.