ID articolo: TECH-HTTP-001
Ultimo aggiornamento: gennaio 2025
Categoria: Supporto tecnico / Integrazione
Tag: Esportazione HTTP, Risoluzione dei problemi, Timeout del gateway, Errori di integrazione

📋 Riepilogo dell'articolo

Questa guida aiuta i clienti a diagnosticare e risolvere i problemi relativi alla ricezione di esportazioni automatizzate di dati di misurazione dell'energia tramite HTTP. Illustra gli errori più comuni, le relative soluzioni e fornisce un approccio sistematico alla risoluzione dei problemi.

🎯 Si applica a

• Clienti che utilizzano la funzionalità di esportazione HTTP/HTTPS
• Amministratori di sistema che gestiscono endpoint HTTP
• Team di supporto tecnico

⚡ Ricerca rapida di soluzioni

📝 Prerequisiti

Prima di procedere alla risoluzione dei problemi, verifica che il tuo server HTTP soddisfi questi requisiti:

✅ Accetta una dimensione minima del payload di 1 MB
✅ Restituisce lo stato HTTP 200 OK in caso di ricezione riuscita
✅ Supporta i metodi POST, PUT o POST MULTIPART
✅ Può gestire più transazioni per grandi esportazioni (>2.000 misurazioni)

🔧 Tipi di errori comuni e soluzioni

1. Errori di timeout del gateway

Dettagli dell'errore:

• Messaggio: Gateway Timeout
• Tipo: CLIENT_ERROR
• Stato HTTP: 504

Cause profonde:

• L'elaborazione del server supera il timeout di 60 secondi
• Timeout del proxy/bilanciatore del carico troppo restrittivo
• Colli di bottiglia delle prestazioni del backend

Soluzione passo dopo passo:

Aumenta le impostazioni di timeout

Per Nginx:

# Add to your server or location block
proxy_read_timeout 300s;
proxy_connect_timeout 75s;
proxy_send_timeout 300s;

Per Apache:

# Add to httpd.conf or .htaccess
Timeout 300
ProxyTimeout 300

Per IIS:

<system.webServer>
  <httpProtocol>
    <customHeaders>
      <add name="Keep-Alive" value="timeout=300" />
    </customHeaders>
  </httpProtocol>
</system.webServer>

Ottimizzare le prestazioni di elaborazione

• Monitorare CPU/memoria durante le esportazioni
• Implementare l'elaborazione asincrona
• Valutare la possibilità di restituire immediatamente 200 e di elaborarlo in background

2. Errori di timeout di lettura

Dettagli dell'errore:

• Messaggio: Read timed out
• Tipo: INTERNAL_ERROR
• Frequenza: Molto comune (codici di stato 261-262)

Cause profonde:

• Interruzione della connettività di rete
• Firewall che blocca le connessioni sostenute
• Problemi di handshake SSL/TLS

Soluzione passo dopo passo:

Diagnostica di rete

# Test connectivity
telnet your-server.com 443

# Check SSL certificate
openssl s_client -connect your-server.com:443

Configurazione del firewall

• Aggiungi alla whitelist gli IP del nostro servizio di esportazione (contatta l'assistenza per l'elenco)
• Assicurarsi che le connessioni persistenti siano consentite
• Controllare le regole di limitazione della velocità

Controllo dello stato del server

# Monitor connections during export window
netstat -an | grep :443 | grep ESTABLISHED

3. Errori di risoluzione DNS

Dettagli dell'errore:

• Messaggio: Name or service not known
• Tipo: CLIENT_ERROR
• Esempio: ops.autodeskbuildingops.com: Name or service not known

Cause profonde:

• Nome host/URL errato
• Problemi di configurazione DNS
• Scadenza o modifiche del dominio

Soluzione passo dopo passo:

Verifica la configurazione del dominio

# Check DNS resolution
nslookup your-domain.com
dig your-domain.com

# Verify from our perspective
curl -I https://your-domain.com/your-endpoint

Soluzioni comuni

• Assicurarsi che il dominio sia risolvibile pubblicamente
• Controlla gli errori di battitura nell'URL configurato
• Verifica che il certificato SSL corrisponda al dominio

4. Errori interni del server

Dettagli dell'errore:

• Messaggio: Internal Server Error
• Tipo: CLIENT_ERROR
• Stato HTTP: 500

Cause profonde:

• L'applicazione si blocca durante l'elaborazione del payload
• Risorse del server insufficienti
• Bug o configurazioni errate del codice

Soluzione passo dopo passo:

Abilita la registrazione degli errori dell'applicazione

Controlla i limiti delle risorse

# Memory
free -m

# Disk space
df -h

# Process limits
ulimit -a

Test con payload di esempio (vedere Passaggi di debug)

🔍 Passaggi di debug completi

Passaggio 1: abilitare la registrazione dettagliata (CRITICO)

⚠️ Importante: la registrazione dettagliata è essenziale per la risoluzione dei problemi. Senza registri dettagliati, non possiamo aiutare a diagnosticare efficacemente i problemi.

Configurazione Nginx:

# /etc/nginx/nginx.conf
error_log /var/log/nginx/error.log debug;
access_log /var/log/nginx/access.log combined;

# Log request body for debugging
log_format postdata '$remote_addr - $remote_user [$time_local] '
                    '"$request" $status $bytes_sent '
                    '"$http_referer" "$http_user_agent" "$request_body"';

Configurazione Apache:

# Enable debug logging
LogLevel debug
ErrorLog ${APACHE_LOG_DIR}/error.log
CustomLog ${APACHE_LOG_DIR}/access.log combined

# Log POST data (use cautiously)
DumpIOInput On
DumpIOOutput On

Registrazione a livello di applicazione (esempio Node.js):

const fs = require('fs');
const logStream = fs.createWriteStream('./export-debug.log', { flags: 'a' });

app.use((req, res, next) => {
  const timestamp = new Date().toISOString();
  const logEntry = {
    timestamp,
    method: req.method,
    url: req.url,
    headers: req.headers,
    contentLength: req.headers['content-length'],
    ip: req.ip
  };
  
  logStream.write(JSON.stringify(logEntry) + '\n');
  
  // Log response
  const originalSend = res.send;
  res.send = function(data) {
    logStream.write(`Response: ${res.statusCode} at ${new Date().toISOString()}\n`);
    originalSend.call(res, data);
  };
  
  next();
});

Passaggio 2: testare manualmente l'endpoint

Test di base:

curl -X POST https://your-server.com/endpoint \
  -H "Content-Type: application/json" \
  -d '{
    "measurements": [{
      "device_id": 47653,
      "device_name": "Test Device",
      "measurement_time(UTC)": "2021-08-10T08:48:00Z",
      "resolution(minutes)": 1,
      "site_id": 3026,
      "site_name": "Test Site",
      "current(A)": 3.7,
      "voltage(V)": 230,
      "power(W)": 807.4,
      "power_factor": 0.95,
      "energy(Wh)": 13.5
    }]
  }' \
  -w "\n\nHTTP Code: %{http_code}\nTotal Time: %{time_total}s\nConnect Time: %{time_connect}s\nStart Transfer: %{time_starttransfer}s\n" \
  -v

Test di carico utile elevato:

# Create large test file
echo '{"measurements":[' > large-test.json
for i in {1..2000}; do
  echo '{"device_id":'$i',"device_name":"Device'$i'","measurement_time(UTC)":"2021-08-10T08:48:00Z","resolution(minutes)":1,"site_id":3026,"site_name":"Test Site","current(A)":3.7,"voltage(V)":230,"power(W)":807.4,"power_factor":0.95,"energy(Wh)":13.5},' >> large-test.json
done
echo ']}' >> large-test.json

# Test with large payload
curl -X POST https://your-server.com/endpoint \
  -H "Content-Type: application/json" \
  -d @large-test.json \
  -w "\nPayload Size: %{size_upload} bytes\nTime: %{time_total}s\n"

Passaggio 3: Monitorare durante la finestra di esportazione

Identificare la pianificazione dell'esportazione

• Controlla la configurazione dell'esportazione per gli orari programmati
• Nota le differenze di fuso orario (le esportazioni utilizzano UTC)

Script di monitoraggio in tempo reale:

#!/bin/bash
# monitor-exports.sh

LOG_FILE="/var/log/nginx/access.log"
ERROR_FILE="/var/log/nginx/error.log"

echo "Monitoring exports... Press Ctrl+C to stop"
tail -f $LOG_FILE $ERROR_FILE | grep -E "POST|PUT|500|502|504"

Monitoraggio delle risorse:

# Run during export window
top -b -n 1 > resource-snapshot.txt
iostat -x 1 10 >> resource-snapshot.txt

✅ Lista di controllo diagnostica

Utilizzare questa checklist per garantire che tutti i problemi comuni siano stati risolti:

• [ ] Configurazione dell'endpoint
  • [ ] Accetta metodi POST/PUT/POST MULTIPART
  • [ ] Restituisce esattamente HTTP 200 OK (nessun reindirizzamento)
  • [ ] Nessuna autenticazione o configurazione corretta
• [ ] Capacità e prestazioni
  • [ ] Può gestire carichi utili da 1 MB+
  • [ ] Impostazioni timeout >60 secondi a tutti i livelli
  • [ ] CPU/memoria sufficienti durante le ore di punta
• [ ] Rete e sicurezza
  • [ ] Il firewall consente le connessioni in entrata
  • [ ] Certificati SSL/TLS validi e non scaduti
  • [ ] Il DNS si risolve correttamente dalle reti esterne
• [ ] Registrazione e monitoraggio
  • [ ] Registrazione dettagliata abilitata
  • [ ] I registri sono conservati per almeno 7 giorni
  • [ ] Avvisi di monitoraggio configurati

📊 Dati da raccogliere per il supporto

Quando contatti l'assistenza, fornisci:

1. Informazioni sugli errori

Export Configuration ID: [Your ID]
Error Message: [Exact error from logs]
Failure Timestamps: [UTC times]
Frequency: [How often it occurs]

2. Registri del server (OBBLIGATORI)

Includere almeno 3 tentativi falliti che mostrino:

• Intestazioni di richiesta complete
• Codici di risposta
• Durata dell'elaborazione
• Eventuali errori nelle tracce dello stack

3. Dettagli di configurazione

Web Server: [Type and Version]
OS: [Operating System]
Timeout Settings: [All relevant timeouts]
Proxy/LB: [If applicable]
SSL Certificate: [Expiry date]

4. Risultati del test

• Uscita del test di arricciatura manuale
• Risultati dei test di carico utile elevato
• Utilizzo delle risorse durante i guasti

5. Informazioni di rete

Public IP: [Your server IP]
Firewall Rules: [Relevant rules]
Rate Limits: [If configured]

💡 Buone pratiche

Implementare una registrazione robusta

# Python example with rotation
import logging
from logging.handlers import RotatingFileHandler

handler = RotatingFileHandler(
    'export-receiver.log',
    maxBytes=10485760,  # 10MB
    backupCount=10
)
logging.basicConfig(handlers=[handler], level=logging.DEBUG)

Modello di risposta rapida

// Return 200 immediately, process async
app.post('/export', (req, res) => {
  res.status(200).send('OK');
  
  // Process in background
  setImmediate(() => {
    processExportData(req.body);
  });
});

Endpoint di controllo dello stato di salute

@app.route('/health')
def health_check():
    return {'status': 'healthy', 'timestamp': datetime.utcnow()}, 200

Monitorare la disponibilità degli endpoint

• Utilizzare servizi di monitoraggio del tempo di attività
• Imposta avvisi per guasti
• Monitorare le tendenze dei tempi di risposta

🆘 Hai ancora bisogno di aiuto?

Se i problemi persistono dopo aver seguito questa guida:

1. Raccogliere tutte le informazioni diagnostiche elencate sopra
2. Abilita la registrazione dettagliata e cattura più tentativi falliti
3. Esegui i test manuali e salva gli output
4. Contatta l'assistenza con:
   • Questo articolo fa riferimento a (TECH-HTTP-001)
   • Tutti i dati diagnostici raccolti
   • Il tuo ID di configurazione di esportazione

Ricorda: le esportazioni non riuscite vengono automaticamente ritentate per un massimo di 7 giorni, evitando così la perdita di dati durante la risoluzione dei problemi.

📚 Articoli correlati

• [Guida alla configurazione dell'esportazione HTTP]
• [Comprensione del formato dei dati di esportazione]
• [Best practice di sicurezza per endpoint HTTP]
• [Webhook vs. esportazione HTTP: quale scegliere?]

Feedback: Questo articolo ti è stato utile? [Sì] [No] [Segnala un problema]