Dépannage

Ce guide aide à diagnostiquer et résoudre les problèmes courants avec IceGate.

Santé des Services

Vérifier l'État des Services

# Service Query
        curl http://localhost:3100/ready
        
        # Service Ingest
        curl http://localhost:4318/health

Afficher les Logs des Services

# Docker Compose
        docker compose logs -f query
        docker compose logs -f ingest
        docker compose logs -f maintain

Problèmes de Connexion

Impossible de se Connecter au Service Query

Symptômes :

  • Connexion refusée sur le port 3100
  • Erreurs de timeout

Solutions :

  1. Vérifiez que le service est en cours d'exécution :

    docker ps | grep query

  2. Vérifiez la liaison du port :

    netstat -tlnp | grep 3100

  3. Vérifiez les logs du service pour les erreurs :

    docker compose logs query | tail -100

Impossible de se Connecter au Stockage Objet

Symptômes :

  • "Connection refused" vers le stockage objet
  • Erreurs d'authentification S3

Solutions :

  1. Sur un déploiement RustFS local, vérifiez que le stockage objet fonctionne. Le chemin de disponibilité est propre à RustFS - sur AWS S3 ou un autre fournisseur, passez directement à l'étape 3 :

    curl http://localhost:9000/health/ready

  2. Vérifiez les identifiants :

    echo $AWS_ACCESS_KEY_ID
        echo $AWS_SECRET_ACCESS_KEY

  3. Testez la connexion S3. Retirez --endpoint-url si le backend est le vrai AWS S3 :

    aws s3 ls --endpoint-url http://localhost:9000

Impossible de se Connecter au Catalogue

Symptômes :

  • Erreurs "Catalog unavailable"
  • Échecs de création de tables

Solutions :

  1. Avec le catalogue S3 par défaut, vérifiez que l'objet d'état du catalogue est lisible - il n'y a aucun service de catalogue à contrôler :

    aws --endpoint-url http://localhost:9000 s3 ls s3://warehouse/catalog/root.json

    Un root.json absent signifie que la migration n'a jamais été exécutée. Lancez maintain migrate create avant toute autre chose.

  2. Vérifiez la configuration du catalogue :

    catalog:
          backend: !s3
            warehouse: catalog
          warehouse: s3://warehouse/
          properties:
            bucket: warehouse
            region: us-east-1
            endpoint: http://rustfs:9000

  3. Uniquement avec le backend REST, vérifiez que Nessie est en cours d'exécution :

    curl http://localhost:19120/api/v1/trees

Problèmes de Requêtes

La Requête Retourne des Résultats Vides

Causes Possibles :

  • Mauvais identifiant de tenant
  • Intervalle de temps en dehors de la fenêtre de données
  • Données pas encore compactées

Solutions :

  1. Vérifiez l'en-tête du tenant :

    curl -H "X-Scope-OrgID: correct-tenant" ...

  2. Vérifiez l'intervalle de temps :

    # Lister l'intervalle de temps disponible
        curl http://localhost:3100/loki/api/v1/labels \
          -H "X-Scope-OrgID: my-tenant"

  3. Vérifiez le WAL pour les données récentes :

    aws s3 ls s3://warehouse/wal/ --recursive

Timeout de Requête

Symptômes :

  • Les requêtes prennent trop de temps
  • 504 Gateway Timeout

Solutions :

  1. Ajoutez un filtre d'intervalle de temps :

    {service_name="api"} | timestamp > 1h ago

  2. Réduisez la limite de résultats :

    curl ... --data-urlencode 'limit=100'

  3. Vérifiez le plan de requête :

    curl http://localhost:3100/loki/api/v1/explain \
          --data-urlencode 'query={service_name="api"}' \
          -H "X-Scope-OrgID: my-tenant"

Syntaxe de Requête Invalide

Symptômes :

  • Réponses "parse error"
  • 400 Bad Request

Solutions :

  1. Validez la syntaxe LogQL :

    • Les labels doivent être entre accolades : {service_name="api"}
    • Les valeurs de chaîne entre guillemets : "value"
    • Format de durée : [5m], [1h]

  2. Vérifiez les fonctionnalités non supportées :

    • Les parseurs de pipeline (json, logfmt) ne sont pas encore supportés
    • Certaines agrégations ne sont pas implémentées

Problèmes d'Ingestion

Les Données n'Apparaissent Pas

Symptômes :

  • Données envoyées mais la requête retourne vide
  • Pas d'erreurs depuis ingest

Solutions :

  1. Vérifiez que les données ont été acceptées :

    curl -v -X POST http://localhost:4318/v1/logs \
          -H "X-Scope-OrgID: my-tenant" \
          -H "Content-Type: application/json" \
          -d '...'

  2. Vérifiez les fichiers WAL :

    aws s3 ls s3://warehouse/wal/logs/ --recursive

  3. Attendez la compaction (ou interrogez directement le WAL)

Erreurs d'Ingestion

Erreurs Courantes :

  • 400 Bad Request : Format OTLP invalide
  • 503 Service Unavailable : Stockage indisponible
  • 429 Too Many Requests : Limitation de débit

Solutions :

  1. Validez le format de la charge utile OTLP
  2. Vérifiez la connectivité du stockage
  3. Réduisez le taux d'ingestion ou augmentez le nombre de réplicas ingest

Problèmes de Performance

Requêtes Lentes

  1. Ajoutez des filtres de partition :

    {tenant_id="my-tenant", service_name="api"}

  2. Limitez l'intervalle de temps :

    --data-urlencode 'start=1704067200'
        --data-urlencode 'end=1704153600'

  3. Vérifiez les statistiques des tables :

    SHOW STATS FOR icegate.logs;

Utilisation Mémoire Élevée

  1. Réduisez les requêtes concurrentes
  2. Ajoutez des limites de requêtes
  3. Augmentez l'allocation mémoire du service

Obtenir de l'Aide

Si les problèmes persistent :

  1. Collectez les informations de diagnostic :

    # Logs des services
        docker compose logs > logs.txt
        
        # Informations système
        docker stats > stats.txt

  2. Consultez les GitHub Issues

  3. Incluez :

    • Version d'IceGate
    • Configuration (nettoyée)
    • Messages d'erreur
    • Étapes pour reproduire

Étapes Suivantes

Précédent
Maintenance
Suivant
Environnement de Développement