alliance-boreale/docs/pile opérateur/pol/POL-OBS-LOG-001 — Contrat de journalisation (Logs) — Référence Loki.md

# POL-OBS-LOG-001 — Contrat de journalisation (Logs) — Référence Loki

**Version :** 1.0  
**Date :** 25 janvier 2026  
**Cycle de Réalignement Boréal :** CRB-3  
**Statut :** Obligatoire (référence vivante)  
**Portée :** C3 (Observabilité fédérée), C5 (Pivot), C6–C8 (Tenants), Membres affiliés

---

## 1. Objet

Définir le **contrat minimal** de collecte, transport, étiquetage, rétention, accès et preuves pour les logs,
avec **Loki** comme backend de référence.

Cette politique vise explicitement la simplicité d’adoption par les petits membres :

- un endpoint standard,
- une configuration “copier-coller” (agent),
- un jeu de labels minimal,
- un modèle d’accès via SSO.

---

## 2. Principes invariants

### 2.1 Adjacent-only (obligatoire)

- Les logs **ne contournent jamais** le pivot.
- Chemin normatif : **C6 → C5 → C3** (tenant vers pivot vers fédération).

### 2.2 Séparation Fédération / Tenants

- Les tenants sont isolés en lecture/écriture.
- La Fédération peut opérer et auditer sans exposer les couches internes.

### 2.3 Simplicité opératoire

- Un petit membre n’a pas à comprendre le multi-tenant.
- L’isolation est assurée **par le Pivot (C5)**.

---

## 3. Référence technique

### 3.1 Backend

- **Loki** = backend de logs de référence.

### 3.2 Visualisation / requêtes

- **Grafana** = interface de consultation de référence.

### 3.3 Agent de collecte

- **Grafana Alloy** = agent recommandé par défaut.
- Autres agents acceptés si : 
  - ils supportent l’ingestion Loki via HTTP(S),
  - ils respectent les labels et les contraintes de cette politique,
  - ils n’introduisent pas de labels à haute cardinalité.

---

## 4. Points d’entrée (endpoints) — standardisation

### 4.1 Ingestion (écriture)

- Endpoint unique via le Pivot (C5) : `https://logs.pivot.<membre>.alliance-boreale.ca/...`
- Interdiction : accès direct tenant → Loki (C3).

### 4.2 Consultation (lecture)

- Accès Grafana via Pivot (C5) (reverse-proxy) + SSO (Keycloak).

> Note : Le chemin exact (`/loki/api/v1/push`, etc.) est défini par l’implémentation du Gateway,
> mais l’invariant est : **une URL unique, TLS obligatoire, auth obligatoire**.

---

## 5. Authentification & autorisation

### 5.1 Lecture (Grafana)

- SSO via **Keycloak** (OIDC/SAML).
- RBAC : permissions par organisation/tenant et par rôle (admin, ops, lecteur).

### 5.2 Écriture (agents)

Mode recommandé (simple) :

- Token d’ingestion (Bearer) par organisation/tenant, délivré/provisionné via le Pivot.
- Le secret est stocké comme **secret** (Vault ou mécanisme équivalent), jamais en clair dans un repo.

Mode alternatif (si requis) :

- mTLS avec certificats gérés par la Fédération.

---

## 6. Isolation (multi-tenant) — masquée pour les petits

### 6.1 Principe

- Le Pivot (C5) est responsable d’assigner l’isolement tenant (ex. injection d’un identifiant d’organisation).
- Les petits membres/tenants ne manipulent pas l’identifiant d’isolation.

### 6.2 Interdictions

- Un agent ne doit pas pouvoir écrire dans un autre tenant.
- Toute tentative d’accès hors périmètre est loggée et alertée.

---

## 7. Labels (schéma Boréal) — minimal et stable

### 7.1 Labels obligatoires (MVP)

Chaque stream de logs DOIT inclure au minimum :

- `org` : organisation ou tenant (valeur stable)
- `env` : `prod | preprod | dev`
- `service` : nom stable du service (ex. `pivot-api`, `forgejo`, `nextcloud`, `tenant-app`)
- `member` : code membre (ex. `czp`, `mtl`, `qc2`)

### 7.2 Labels optionnels (avec prudence)

- `host` : nom machine/VM (stable)
- `layer` : couche (`c3`, `c5`, `c6`, etc.) si utile

### 7.3 Interdictions (cardinalité)

Il est strictement interdit de promouvoir en labels des valeurs à haute cardinalité, incluant (non exhaustif) :

- `trace_id`, `span_id`, `request_id`, `session_id`
- `user_id`, `email`, identifiants personnels
- timestamps, UUIDs, numéros de commande, adresses IP client

Ces valeurs doivent rester dans le **contenu** du log (requêtables), pas dans les labels.

---

## 8. Qualité des logs (hygiène minimale)

### 8.1 Format recommandé

- JSON structuré si possible (clé/valeur), sinon logfmt.
- Les champs sensibles doivent être masqués (redaction) avant expédition.

### 8.2 Données sensibles

- Ne pas expédier de secrets (tokens, clés, mots de passe).
- Ne pas expédier de données personnelles non nécessaires.
- Si un tenant a des contraintes particulières, il doit fournir une règle de redaction.

---

## 9. Rétention & classes de service

### 9.1 Rétention par défaut (standard)

- **14 jours** (sauf exception documentée).

### 9.2 Exceptions

- Toute rétention supérieure (ex. “régulé”) doit être : 
  - justifiée,
  - validée par gouvernance (C3),
  - accompagnée de preuves (stockage, coûts, risques, contrôles).

---

## 10. Quotas & protection

Le Pivot (C5) doit appliquer :

- quotas d’ingestion (taux, volume/jour),
- limites de taille par entrée,
- protections anti-boucle / anti-tempête (burst control),
- blocage ou mise en quarantaine en cas de non-conformité (labels interdits, volumes anormaux).

---

## 11. Preuves minimales (audit)

Pour être “conforme POL-OBS-LOG-001”, les preuves suivantes doivent être disponibles :

1. Configuration du Gateway (C5) : TLS, auth, routage, quotas.
2. Configuration Loki (C3) : rétention, stockage, limites, accès.
3. Exemple de configuration agent (Alloy) “copier-coller” (template).
4. Démonstration : une requête Grafana/Loki qui retourne des logs d’un service donné.
5. Journal des incidents de non-conformité (tentatives cross-tenant, labels interdits).

---

## 12. Non-conformité & remédiation

### 12.1 Détection

- Toute violation (labels interdits, volumétrie anormale, tentative cross-tenant) déclenche : 
  - un événement de sécurité/opérations,
  - une entrée de traçabilité (ΔLog / incident).

### 12.2 Réponse

- Quarantaine du flux (au pivot) si nécessaire.
- Correction du template agent.
- Ajustement des politiques si apprentissage systémique requis.

---

## 13. Annexes

### A) Requête Loki (exemple conceptuel)

- `{org="t001", env="prod", service="pivot-api", member="czp"}`

### B) Convention de nommage (rappel)

- Conformité à la Nomenclature v3 pour VMID, DNS, et segmentation par couche.