Envoyer des données OpenTelemetry

Les endpoints

Trois routes OTLP acceptent les données, sur l’hôte d’ingestion et non sur l’API du tableau de bord. Elles reçoivent les charges utiles OTLP/HTTP standard : ni un exporteur de collector ni un SDK de langage n’a besoin d’adaptateur.

La séparation compte au quotidien : l’ingestion est le seul service sur le chemin d’écriture, elle peut donc être dimensionnée, limitée et redémarrée sans toucher au tableau de bord.

POST https://ingest.snagspy.com/v1/traces
POST https://ingest.snagspy.com/v1/logs
POST https://ingest.snagspy.com/v1/metrics

L’authentification se fait par DSN, pas par session

Chaque route d’ingestion s’authentifie avec le DSN d’un projet. Ce n’est pas une session utilisateur et il ne porte aucune permission sur le tableau de bord : un DSN divulgué peut écrire de la télémétrie dans un projet et ne rien lire du tout.

C’est délibéré. Une clé d’ingestion se retrouve sur toutes les machines qui exécutent votre application, y compris un poste de développement et un runner de CI ; un identifiant présent à autant d’endroits doit pouvoir faire le moins de choses possible.

L’en-tête doit être l’en-tête standard `Authorization`, schéma `Bearer`. Il peut porter le DSN entier ou seulement la clé publique qu’il contient — la partie avant le `@` — car l’ingestion en déduit le projet dans les deux cas : rien à extraire avant de coller. L’ingestion ne lit que cet en-tête ; un en-tête au nom différent est rejeté exactement comme s’il était absent, sans que la réponse distingue les deux cas.

exporters:
  otlphttp:
    endpoint: https://ingest.snagspy.com
    headers:
      Authorization: Bearer ${SNAGSPY_DSN}

Fonctionner à côté de ce que vous avez déjà

Rien ici ne vous demande de changer de backend. Un pipeline de collector peut nommer plusieurs exporteurs et envoie chaque lot à chacun d’eux : SnagSpy s’ajoute donc sous son propre nom à côté de l’exporteur que vous utilisez déjà. Votre destination actuelle continue de recevoir exactement ce qu’elle recevait avant.

C’est la manière honnête d’évaluer un second backend : les deux voient le même trafic le temps que dure la comparaison, et retirer l’un ou l’autre est la même modification d’une ligne que l’ajouter. Placez la même liste sur les pipelines `logs` et `metrics` pour comparer aussi ces signaux.

exporters:
  otlphttp/existing:
    endpoint: https://otlp.your-current-backend.example
  otlphttp/snagspy:
    endpoint: https://ingest.snagspy.com
    headers:
      Authorization: Bearer ${SNAGSPY_DSN}

service:
  pipelines:
    traces:
      receivers: [otlp]
      exporters: [otlphttp/existing, otlphttp/snagspy]

Un span porteur d’une exception devient un incident

C’est ce qui distingue SnagSpy d’un simple backend OTLP. Les traces sont conservées comme des traces, mais un span porteur d’une exception est aussi regroupé en incident — l’unité sur laquelle travaillent le tableau de bord, les alertes et l’analyse des causes racines.

Vous n’instrumentez donc pas les erreurs séparément des traces. Si vos spans enregistrent déjà les exceptions comme le décrit la spécification OpenTelemetry, les erreurs arrivent avec elles et sont regroupées sans configuration supplémentaire.

Limites de débit, et ce qui se passe au-delà d’un quota

L’ingestion est limitée à la minute, indépendamment du quota de votre offre. Par défaut : 600 requêtes par minute pour un projet et 30 000 événements par minute pour une organisation. Ce sont des garde-fous de stabilité sur le chemin d’écriture, pas un mécanisme de facturation.

Le quota de l’offre se comporte autrement, et la nuance mérite d’être précise : le dépasser n’interrompt pas votre télémétrie. L’usage est mesuré, le dépassement est signalé une fois par période, et l’ingestion continue d’accepter vos données. Rejeter vos erreurs au moment où vous avez le plus de chances d’être en dépassement — pendant un incident — serait la pire chose qu’un outil de surveillance puisse vous faire.

INGEST_REQUESTS_PER_MINUTE = 600      # par projet
INGEST_EVENTS_PER_MINUTE   = 30000    # par organisation

Partir demande autant de travail qu’arriver

Le chemin d’ingestion étant de l’OTLP standard, migrer vers un autre fournisseur consiste à remettre l’endpoint d’origine. Aucun format propriétaire à démêler, aucune instrumentation à réécrire.

C’est dit franchement parce que c’est une raison d’adopter SnagSpy, pas un risque à dissimuler. Un fournisseur dont la fidélisation repose sur la difficulté de partir a une raison de ne pas corriger ce qui vous a fait envisager de partir.