SigNoz

ID fournisseur : signoz · Maturité : preview · Catégories : Observabilité, Outils

SigNoz — observabilité native OTel. Cette intégration interroge votre instance SigNoz via l'API v5 query_range pour identifier ce qui échoue dans vos services.

En lecture seule par construction. Le seul point de terminaison accessible aux outils de cette intégration est POST /api/v5/query_range. Il n'existe délibérément aucune surface d'alerte, de tableau de bord ou de configuration : un workflow capable de modifier votre plan d'observabilité a un rayon d'impact bien plus large qu'un workflow qui peut seulement le lire.

Authentification

Configuration

SigNoz est auto-hébergé : il n'existe donc pas d'origine publique fixe comme pour un fournisseur SaaS. L'adresse accessible est la vôtre, ce qui explique qu'elle relève de la configuration plutôt que d'une constante.

Capacités

Chaque outil accepte une fenêtre bornée (lookbackHours, 24 par défaut, ou start/end explicites) et une limit (500 par défaut, plafond strict à 5 000).

Chaque enregistrement de log porte ses clés de corrélation : traceId, spanId, deploymentName, namespace et clusterName, en plus de body, serviceName et severityText. serviceName reprend exactement ce que dit l'enregistrement. Un log de conteneur écrit sur stdout peut n'avoir aucun service.name : deploymentName indique alors quelle charge de travail l'a écrit. Un identifiant de trace absent ou entièrement nul est renvoyé sous la forme "", jamais comme un identifiant sur lequel faire une jointure.

Retrouver la requête derrière une erreur

1. Query Error Spans désigne le service et le nom du span en échec.
2. Query Spans avec ce serviceName, ce spanName et errorsOnly: true renvoie des spans concrets, chacun avec son traceId.
3. Query Spans avec un traceId montre la requête entière. Query Logs avec le même traceId montre ce qu'elle a journalisé.
4. Le clusterName de ces spans et de ces logs indique quel déploiement a exécuté la requête. Vérifiez sa version avant de lire le code.

Plusieurs clusters, un seul SigNoz

Lorsque plusieurs clusters envoient leurs données au même SigNoz, passez clusterName à chaque requête afin que le balayage d'un environnement ne remonte pas les erreurs d'un autre. Le filtre porte sur l'attribut de ressource k8s.cluster.name, et un enregistrement qui ne le porte pas est exclu, jamais inclus.

Les logs collectés par l'agent k8s-infra de SigNoz portent le nom du cluster. Les spans ne le portent que s'ils transitent eux aussi par cet agent. Une application ou un sidecar Dapr qui exporte en OTLP directement vers le collecteur SigNoz n'envoie que service.name. Faites pointer son endpoint OTLP vers le Service de l'agent (gRPC 4317, HTTP 4318), ou définissez k8s.cluster.name dans son OTEL_RESOURCE_ATTRIBUTES. Le champ clusterName de chaque span indique lequel des deux cas vous avez : vide signifie que le span est arrivé sans.

Les valeurs de filtre sont validées, pas échappées

Une valeur qui changerait le sens de la requête est refusée avant tout envoi, avec signoz_invalid_filter :

• un traceId doit comporter 32 caractères hexadécimaux minuscules ;
• serviceName, deploymentName, namespace et clusterName (sur chaque outil qui l'accepte) n'acceptent que A-Z a-z 0-9 . _ - ;
• spanName, statusMessageContains et bodyContains ne peuvent contenir ni apostrophe droite, ni barre oblique inverse, ni caractère de contrôle, et sont limités à 200 caractères.

C'est important parce que ces valeurs sont écrites par un agent. Le filtre sur le nom du span s'appelle spanName, et non operation : dans un workflow, le champ operation d'un bloc choisit l'outil à exécuter, et sa valeur serait sinon transmise comme filtre.

Deux comportements à connaître

La troncature est signalée, jamais silencieuse. Les outils renvoient un indicateur truncated lorsque le résultat atteint la limite. Un balayage tronqué qui paraît complet est pire qu'un balayage restreint qui l'admet.

Une forme de réponse non reconnue fait échouer l'appel. SigNoz ne publie pas de schéma de réponse pour query_range v5 : une montée de version pourrait donc en modifier la forme. Plutôt que de se rabattre sur un résultat vide — qui se lirait comme « aucune erreur trouvée » — l'intégration lève une erreur. Un angle mort visible vaut mieux qu'un rapport impeccable auquel on ne peut pas se fier.

Regroupement sur status_message

Les spans en erreur sont regroupés sur service.name + nom du span + status_message, et non sur response_status_code. Pour les spans Dapr CallLocal et de binding, le code de statut est vide, et l'échec lisible par un humain — Code(403): Forbidden, ou un refus de contrôle d'accès verbatim — se trouve dans status_message.