NuCache et configuration BTreeBlockSize

Introduction

Umbraco utilise NuCache pour stocker une représentation optimisée du contenu publié.
L'objectif est d'éviter de lire la base SQL à chaque requête.

Flux simplifié :

Base SQL
   ↓
NuCache (B+Tree persistant)
   ↓
Published Snapshot (mémoire)
   ↓
Rendu du site

NuCache améliore fortement les performances, car la majorité des lectures se font depuis la mémoire et non directement depuis SQL.

---

Emplacement du cache

Le cache NuCache est stocké sur disque dans :

/umbraco/Data/TEMP/NuCache

Fichiers typiques :

• NuCache.Content.db
• NuCache.Media.db
• NuCache.Content.xml
• NuCache.Media.xml

Fichier	Description
NuCache.Content.db	Cache binaire principal du contenu
NuCache.Media.db	Cache binaire des médias
NuCache.Content.xml	Snapshot XML utilisé pour reconstruire le cache
NuCache.Media.xml	Snapshot XML des médias

---

Structure interne

NuCache utilise une structure B+Tree persistante.

Un B+Tree permet :

• un accès très rapide
• un stockage optimisé sur disque
• une fragmentation limitée
• une lecture efficace

Les données sont stockées dans des blocs de taille fixe.

Cette taille est définie par le paramètre :

BTreeBlockSize

---

Configuration BTreeBlockSize

Dans appsettings.json :

{
  "Umbraco": {
    "CMS": {
      "NuCache": {
        "BTreeBlockSize": 4096
      }
    }
  }
}

Règles officielles

Selon la documentation Umbraco :

• la valeur doit être une puissance de 2
• minimum : 512
• maximum : 65536
• valeur par défaut : 4096

Valeurs possibles

Valeur	Valide	Remarque
512	Oui	Minimum
1024	Oui	Petite taille de bloc
2048	Oui	Taille intermédiaire
4096	Oui	Valeur par défaut
8192	Oui	Premier niveau d'augmentation raisonnable
16384	Oui	Adapté aux contenus lourds
32768	Oui	Pour contenus très lourds
65536	Oui	Maximum

Exemples de valeurs non valides :

• 3000
• 5000
• 10000

car elles ne sont pas des puissances de 2.

---

Évolution depuis Umbraco 9+

Dans les versions modernes d'Umbraco, la colonne data de cmsContentNu est souvent inutilisée ou NULL.

Les données réellement stockées par NuCache se trouvent dans :

dataRaw

Exemple de requête utile :

SELECT TOP 10 nodeId, LEN(dataRaw) AS SizeBytes
FROM cmsContentNu
ORDER BY SizeBytes DESC;

dataRaw contient le contenu sérialisé en binaire.

---

Taille typique des contenus NuCache

Ordres de grandeur souvent observés :

Type de page	Taille dataRaw
Page simple	2-10 KB
Page avec quelques blocs	10-50 KB
Page lourde	50-150 KB
Page très lourde	150-300 KB
Page extrême (BlockGrid imbriqué)	300 KB et plus

---

Pourquoi les BlockGrid imbriqués peuvent poser problème

Les BlockGrid imbriqués génèrent des payloads volumineux.

Chaque bloc peut contenir :

• content
• settings
• layout
• areas
• des métadonnées

Quand une page contient beaucoup de blocs imbriqués, NuCache doit sérialiser un volume important de données. Cela peut provoquer des erreurs du type :

Specified argument was out of the range of valid values. (Parameter 'length')

ou :

Specified argument was out of the range of valid values. (Parameter 'handle')

Ces erreurs proviennent généralement du moteur B+Tree utilisé par NuCache.

---

Quand augmenter BTreeBlockSize

Il n'existe pas de règle officielle Umbraco disant :

"à partir de X KB, il faut mettre Y".

En revanche, une règle empirique souvent utilisée sur les projets réels est la suivante :

Taille du plus gros node (LEN(dataRaw))	BTreeBlockSize conseillé
< 100 KB	4096
100-200 KB	8192
200-350 KB	16384
350-600 KB	32768
> 600 KB	65536 (à évaluer avec prudence)

Cette règle n'est pas officielle, mais elle est cohérente avec le fonctionnement d'un B+Tree :

taille du payload / taille du bloc = nombre de blocs nécessaires

Exemple :

328 KB / 4096 ≈ 80 blocs
328 KB / 16384 ≈ 20 blocs

Plus la taille du bloc est grande, plus on réduit :

• la fragmentation
• la profondeur de l'arbre
• le nombre de splits internes

---

Comment augmenter BTreeBlockSize

1. Modifier la configuration

Dans appsettings.json :

{
  "Umbraco": {
    "CMS": {
      "NuCache": {
        "BTreeBlockSize": 16384
      }
    }
  }
}

2. Arrêter complètement l'application

Par exemple :

• arrêt du site IIS
• arrêt de l'App Pool
• ou arrêt du processus selon l'hébergement

3. Supprimer le cache NuCache

Supprimer le dossier :

/umbraco/Data/TEMP/NuCache

4. Redémarrer l'application

Au redémarrage, Umbraco reconstruit NuCache depuis la base SQL avec la nouvelle taille de bloc.

---

Recommandation pratique d'augmentation

Approche raisonnable :

1. commencer par 8192 si les pages deviennent lourdes
2. passer à 16384 pour des BlockGrid vraiment volumineux
3. tester 32768 seulement si le problème persiste
4. éviter de sauter directement au maximum sans raison

En pratique :

• 4096 : convient à la majorité des sites
• 8192 : bon premier ajustement
• 16384 : bon compromis pour les pages lourdes
• 32768 : réservé aux cas plus extrêmes
• 65536 : à utiliser avec prudence

---

Diagnostic des pages les plus lourdes

Pour identifier rapidement les pages les plus grosses dans NuCache :

SELECT TOP 20 nodeId, LEN(dataRaw) AS SizeBytes
FROM cmsContentNu
ORDER BY SizeBytes DESC;

Cela permet de trouver :

• les pages avec des BlockGrid très lourds
• les pages les plus susceptibles de poser problème

---

Quand supprimer NuCache

Supprimer NuCache peut être utile si :

• le cache est corrompu
• des erreurs length ou handle apparaissent
• une modification du BTreeBlockSize vient d'être faite

Important :

• NuCache est un cache dérivé
• la source de vérité reste la base SQL
• supprimer NuCache ne supprime aucun contenu

---

Points clés à retenir

• NuCache stocke le contenu publié dans un B+Tree persistant
• BTreeBlockSize définit la taille des blocs internes
• les pages avec BlockGrid imbriqués peuvent générer des payloads très lourds
• dans Umbraco 13, il faut surveiller dataRaw, pas seulement data
• augmenter BTreeBlockSize peut améliorer la stabilité sur des pages très volumineuses
• il faut toujours supprimer puis reconstruire NuCache après modification de ce paramètre

---

Sources

Documentation officielle

• Documentation NuCache settings :
  https://docs.umbraco.com/umbraco-cms/13.latest/reference/configuration/nucachesettings

Discussions et retours communautaires

• GitHub issue Umbraco liée à des erreurs NuCache / B+Tree :
  https://github.com/umbraco/Umbraco-CMS/issues/8447

• Forum / discussions Umbraco :
  https://our.umbraco.com/forum/

• Archives de discussions Discord Umbraco :
  https://discord-chats.umbraco.com/

Contributors

Clément Favre

Changelog

Last edited about 2 months ago

View full history

b07d2bb-docs: add Crans-Montana headless and police intranets to parc inventory