Contexte et choix d'OpenTelemetry

OpenTelemetry génère trois signaux distincts – logs, métriques et traces – chacun pouvant être adopté indépendamment. Tous les signaux sont encodés au format OTLP (OpenTelemetry Protocol), un standard inter‑opérable qui permet de changer de fournisseur (Datadog, New Relic, Grafana Cloud) sans modifier le code applicatif. Dans le projet Rails étudié, la contrainte était d’ajouter de l’observabilité sans verrouiller le stack sur un seul vendor, ce qui a conduit à choisir OpenTelemetry comme couche d’instrumentation.

Le déploiement classique d’OpenTelemetry implique un Collector séparé qui reçoit les données en local, les regroupe et les transmet au backend. L’équipe a préféré éliminer ce composant supplémentaire parce que le volume de logs était faible et que le SDK Ruby intègre déjà un mécanisme de batch. Cette décision réduit la surface d’infrastructure, mais elle implique que le SDK doit gérer directement l’export vers le point d’accès du vendor.

Mise en place du SDK Ruby

Le processus d’installation repose sur six gemmes : opentelemetry-sdk, opentelemetry-logs-sdk, opentelemetry-exporter-otlp, opentelemetry-exporter-otlp-logs, opentelemetry-instrumentation-all et opentelemetry-instrumentation-logger. Chaque gemme assure une fonction précise : le SDK centralise la configuration, le logs‑sdk ajoute le signal log, les exporteurs OTLP transmettent respectivement traces et logs, le bundle d’instrumentation active les hooks Rails, Rack et Active Record, et l’instrumentation logger intercepte les appels du RubyLogger pour les convertir en enregistrements OpenTelemetry.

gem "opentelemetry-sdk"
gem "opentelemetry-logs-sdk"
gem "opentelemetry-exporter-otlp"
gem "opentelemetry-exporter-otlp-logs"
gem "opentelemetry-instrumentation-all"
gem "opentelemetry-instrumentation-logger"

Les variables d’environnement OTEL_EXPORTER_OTLP_ENDPOINT et OTEL_EXPORTER_OTLP_HEADERS renseignent le point d’accès (https://your-vendor.com/otlp) et le token d’authentification. L’initialiseur config/initializers/opentelemetry.rb active le SDK uniquement si l’endpoint est défini, fixe le nom du service à our-rails-app et invoque c.use_all pour charger toutes les instrumentations déclarées.

OpenTelemetry::SDK.configure do |c|
  c.service_name = "our-rails-app"
  c.use_all
end

Problèmes rencontrés et correctifs apportés

Deux écarts avec la spécification ont été identifiés. Premièrement, l’exporteur opentelemetry-exporter-otlp-logs supprimait le chemin de base /otlp lors de la construction de l’URL finale : l’endpoint attendu était https://your-vendor.com/otlp/v1/logs, mais l’URL générée était https://your-vendor.com/v1/logs. Le problème a été consigné dans l’issue #2157 et corrigé par le PR #2158, publié dans la version 0.5.1 du gem.

Deuxièmement, Grafana Cloud renvoie un statut HTTP 204 No Content après ingestion réussie, alors que l’exporteur ne reconnaissait que le code 200 comme succès. Cette incohérence entraînait des logs d’erreur fictifs. La correction, décrite dans l’issue #2043 et le PR #2044, a été intégrée à la version 0.4.0 du même exporteur.

Perspectives et limites

Le test local s’effectue en définissant OTEL_LOGS_EXPORTER=console, ce qui affiche les enregistrements dans le terminal et valide la configuration avant le déploiement. Bien que le contournement du Collector simplifie l’architecture, il ne fournit pas de mécanismes de mise en tampon ou de filtrage hors processus ; ces fonctions restent indispensables pour des charges de logs élevées ou des exigences de conformité. L’étape suivante envisagée est l’adoption d’un format structuré, par exemple via le gem rails_semantic_logger, afin d’enrichir chaque enregistrement de métadonnées exploitables par les systèmes d’observabilité.