> ## Documentation Index
> Fetch the complete documentation index at: https://docs.poihunter.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Observabilité — erreurs swing positions

> Contrat errorCode, logs BetterStack, errorFlags et requêtes d'audit MongoDB

# Observabilité des erreurs (swing positions)

## 1. Contrat `errorCode`

* Chaque activité d’échec exchange pertinente inclut **`context.errorCode`** (voir [error-map.json](/docs/specifications/swing-positions/xstate/error-map.json)).
* Les logs structurés (`logError`) incluent les mêmes champs : **`errorCode`**, **`positionId`**, **`exchangePair`**, **`activityType`**, **`spec`**: `swing-positions/observability-errors`.

## 2. `errorFlags` sur `swingPosition`

En plus des flags d’intégrité existants (`RELATIVE_AMOUNT_INCONSISTENT`, `TP2_BEFORE_TP1`, etc.) :

| Flag                              | Condition                                                                               |
| --------------------------------- | --------------------------------------------------------------------------------------- |
| **REPEATED\_TP\_EXCHANGE\_ERROR** | Au moins **3** activités cumulées de type `TP1_EXCHANGE_ERROR` ou `TP2_EXCHANGE_ERROR`. |
| **TP\_EXCHANGE\_ERROR\_STALLED**  | Au moins **10** de ces mêmes activités (boucle de retry).                               |

Objectif : requêtes Mongo / alertes sans parser tout le tableau `activity`.

## 3. BetterStack (recommandations)

Configurer des vues / alertes sur les champs JSON des logs applicatifs (adapter au format exact de ton shipper) :

* **Critique** : `errorFlags` contient `TP_EXCHANGE_ERROR_STALLED` ou `errorCode` répété > N fois / 15 min pour un même `positionId`.
* **Warning** : `errorCode` = `EXCHANGE_MIN_AMOUNT` ou flag `REPEATED_TP_EXCHANGE_ERROR`.
* **Réduction de bruit** : ne pas alerter sur le **même** `positionId` + **même** `errorCode` plus d’une fois par heure sans variation (déduplication côté BetterStack si disponible).

Le mapping détaillé des requêtes suggérées est dans **error-map.json**.

## 4. Audits MongoDB (exemples)

À exécuter dans Compass, `mongosh` ou via MCP (lecture seule).

**Positions RUNNING avec erreurs TP répétées (aperçu) :**

```javascript theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
db.swingPosition.find(
  {
    status: "RUNNING",
    $or: [
      { errorFlags: "REPEATED_TP_EXCHANGE_ERROR" },
      { errorFlags: "TP_EXCHANGE_ERROR_STALLED" }
    ]
  },
  { _id: 1, status: 1, errorFlags: 1, updatedAt: 1 }
).limit(20);
```

**Dernière activité = erreur TP (pipeline indicatif) :**

```javascript theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
db.swingPosition.aggregate([
  { $match: { status: "RUNNING" } },
  { $project: {
      last: { $arrayElemAt: ["$activity", -1] },
      _id: 1
  }},
  { $match: { "last.type": { $in: ["TP1_EXCHANGE_ERROR", "TP2_EXCHANGE_ERROR"] } } },
  { $limit: 50 }
]);
```

Les requêtes d’audit réutilisables sont dans **[scripts/mongo/README.md](../../../scripts/mongo/README.md)**.

## 5. Fichiers liés

* [error-map.json](/docs/specifications/swing-positions/xstate/error-map.json) — registre machine-lisible.
* [etat-running.md](/docs/specifications/swing-positions/etat-running.md) — diagramme XState et états d’erreur RUNNING.