Telemetrie

Un exemple

[telemetry]
enabled = true
otlp_endpoint = "http://otel-collector:4318"
protocol = "http"
service_name = "craft-file-gate"
metrics = true

`[telemetry]`

Toutes les cles : Reference [telemetry].

Le point d’acces

`protocol`	`otlp_endpoint`	Spans envoyes a
`http`	`http://collector:4318`	`http://collector:4318/v1/traces` (et `/v1/metrics`)
`http`	`http://gw/otel/v1/traces`	tel quel
`grpc`	`http://collector:4317`	tel quel

https:// est chiffre dans les deux protocoles ; le certificat du collecteur est verifie contre les racines du systeme (voir Racines de confiance TLS).
protocol fait autorite : OTEL_EXPORTER_OTLP_PROTOCOL et OTEL_EXPORTER_OTLP_TRACES_PROTOCOL, qu’injectent certains operateurs, ne le changent pas.
L’exporteur lit OTEL_EXPORTER_OTLP_HEADERS (en-tetes d’authentification) et OTEL_EXPORTER_OTLP_TIMEOUT (10 s par defaut).

Ce qui est exporte

L’export recoit les spans et les evenements de CraftFileGate et de la piste d’audit a partir de info, quel que soit le niveau du journal : un serveur regle en warn exporte toujours ses spans.

Span	Attributs	Parent
`ssh_connection`	`peer`, `username`	-
`auth_password`, `auth_publickey`	`username`	`ssh_connection`
`sftp_session`	`session_id`, `username`	la connexion
`sftp_operation`	`operation`, `session_id`, `username`, `path`, `bytes`	`sftp_session`
`api_request`	`method`, `path` (tel que recu, encode en pourcent), `username`	-
`api_operation`	`operation`, `path` (decode), `username`	`api_request`
`authz_service_call`	`http.method`, `http.url`, `http.status_code`	l’appelant

La ligne d’audit d’une operation est un evenement de son span ; un echec passe le span en status=error.

Pour un panneau Tempo ou Jaeger :

un transfert qui va jusqu’a close a deux spans sftp_operation du meme operation (upload, download) : l’ouverture, puis la validation, qui seule porte bytes. Comptez les spans qui portent bytes ;
un rmdir d’un repertoire non vide a un span rmdir puis un span rmdir_recursive, pour une seule ligne d’audit rmdir_recursive ;
les lectures et ecritures n’ont pas de span par paquet.

Un path ou un username qui contient un caractere de controle ou un separateur Unicode (U+2028, controles bidirectionnels) arrive echappe, sous une forme visible (\u{2028}). La valeur exacte est dans la ligne d’audit.

Les metriques en OTLP

Avec metrics = true, le serveur pousse ses metriques toutes les metrics_interval_secs, en plus de GET /metrics, qui reste servi ; la correspondance des noms : Metriques.

Envois, relances et arret

Moment	Comportement
refus transitoire (`http` : `429`, `502`, `503`, `504`, pas de reponse ; `grpc` : `UNAVAILABLE`, `DEADLINE_EXCEEDED`, …)	jusqu’a 4 tentatives dans le delai de 10 s ; `Retry-After` respecte
autre refus	une seule tentative
collecteur injoignable	le lot est perdu et compte, rien ne s’arrete ; une ligne a la panne, une au retour
arret	dernier envoi des metriques et des spans, 5 s au plus

Les spans perdus se comptent sur /metrics :

Metrique	Compte
`craftfilegate_otel_spans_ended_total`	spans remis a l’export
`craftfilegate_otel_spans_exported_total`	spans acceptes par le collecteur
`craftfilegate_otel_spans_export_failed_total`	spans d’un lot perdu apres sa derniere tentative

ended - exported - export_failed est ce qui est encore en route (jusqu’a 2560 spans : la file et le lot en cours), plus ce qu’une file pleine a rejete. Un ecart qui croit au-dela, ce sont des spans perdus.

increase(craftfilegate_otel_spans_ended_total[5m])
  - increase(craftfilegate_otel_spans_exported_total[5m])

Ce que vous verrez

Quand	Ligne
demarrage, export coupe	`INFO` `OpenTelemetry tracing disabled ([telemetry] absent or enabled = false); no spans are exported`
demarrage, export actif	`INFO` `OpenTelemetry tracing enabled`, champs `endpoint` (complete en `http`), `protocol`, `service_name`
demarrage, metriques	`INFO` `OpenTelemetry metrics export enabled`, champs `endpoint`, `interval_secs`
collecteur revenu apres une panne	`INFO` `OTLP collector recovered — telemetry export resumed`
arret	`INFO` `flushing OpenTelemetry spans`, puis `OpenTelemetry shutdown complete`

Keyboard shortcuts

CraftFileGate