otel-instrument

Instrumentation OpenTelemetry minimale et idiomatique pour Crystal, posée sur wyhaines/opentelemetry-sdk.cr.

Deux briques, branchées sur des points d'extension prévus (pas de monkey-patching de la stdlib) :

• OTel::HTTPHandler — un HTTP::Handler qui ouvre un span racine par requête. À placer en tête de la chaîne de handlers.
• un hook DB (require "otel-instrument/db") — un span par requête SQL via le hook public DB::Statement#def_around_query_or_exec.

Grâce au contexte fiber-local du SDK, tout span ouvert pendant le traitement d'une requête (dont les spans SQL) s'imbrique automatiquement sous le span racine du handler. On obtient un arbre requête HTTP → … → SQL sans rien câbler manuellement.

Pourquoi cette lib plutôt que l'auto-instrumentation existante ?

opentelemetry-instrumentation.cr instrumente surtout par monkey-patching de la stdlib (fragile entre versions de Crystal). De plus, à ce jour, son instrumentation CrystalDB est verrouillée à crystal-db < 0.12.0 et son instrumentation HTTP::Server ne suit pas correctement les frameworks à chaîne de handlers. Ici on cible les bons seams (un HTTP::Handler, un hook DB public) : plus simple, plus robuste, sans patch.

Installation

# shard.yml
dependencies:
  otel-instrument:
    github: <votre-compte>/otel-instrument

Utilisation

Handler HTTP (générique HTTP::Server)

require "otel-instrument"

server = HTTP::Server.new([
  OTel::HTTPHandler.new,
  # ... vos autres handlers
])

Avec spider-gazelle / action-controller

require "otel-instrument"

# En tête de chaîne : devient le span racine de chaque requête.
ActionController::Server.before(OTel::HTTPHandler.new)

Le handler nomme le span "<MÉTHODE> <chemin>" par défaut. Pour une faible cardinalité (recommandé pour l'agrégation RED), affinez le nom une fois la route connue, p. ex. dans un before_action :

before_action do
  OpenTelemetry.current_span.try &.name = "#{self.class.name}##{action_name}"
end

Hook DB

require "otel-instrument/db"   # effet global : chaque requête SQL est tracée

Configuration OpenTelemetry

Cette lib ne configure pas le SDK (c'est le rôle de l'application) :

OpenTelemetry.configure do |c|
  c.service_name = "mon-app"
  c.exporter = OpenTelemetry::Exporter.new(variant: :http) # lit OTEL_EXPORTER_OTLP_ENDPOINT
end

Tests

shards install
# Le spec DB nécessite un PostgreSQL (DATABASE_URL, défaut otapi_test) :
crystal spec

Limite connue

Le contexte de span est fiber-local. Si vous spawn du travail pendant une requête, le span courant ne suit pas automatiquement — il faut propager le contexte explicitement.