Vidocq Documentation

Humboldt est l’implémentation MicroProfile Telemetry 2.1 de l’écosystème Vidocq. Elle réécrit son propre SDK OpenTelemetry (traces, metrics, logs) directement sur la surface API OTel publique, et s’intègre avec Chappe pour le transport HTTP, Vauban pour le CDI, Ravel pour la configuration et Cassini pour l’instrumentation JAX-RS. Objectif : conformité 100 % au TCK officiel, sans dépendance opentelemetry-sdk / opentelemetry-exporter-*, sans Netty, sans pile gRPC.

Origine du nom

Alexander von Humboldt (1769–1859), polymathe prussien, naturaliste, géographe, explorateur. L’homme qui a posé le geste fondamental de l’observabilité moderne : observer simultanément, mesurer rigoureusement, corréler à travers les couches. Sur le Chimborazo en 1802, il enregistre conjointement la pression barométrique, la température, le magnétisme terrestre, l’humidité, la faune, la flore — puis trace les premières cartes isothermes qui révèlent les invariants cachés de la planète. Il invente le Naturgemälde, première dataviz scientifique, et synthétise tout son savoir dans le Kosmos.

Référence : Humboldt sur Wikipédia.

Humboldt, l’explorateur Humboldt, le runtime

Observation simultanée (pression, température, magnétisme)

Trois piliers : traces, metrics, logs (un seul SDK)

Cartes isothermes

Vues agrégées par dimension (résultats corrélés)

Voyages couvrant la totalité des couches (mer, plaine, sommet)

Instrumentation cross-cutting (web → DB → external)

Kosmos — synthèse globale du savoir naturel

Document OpenTelemetry unifié (W3C TraceContext + OTLP)

Réseau de stations magnétiques

Réseau de processors / exporters / propagators

OpenTelemetry est le Naturgemälde des systèmes distribués. Humboldt l’embarque nativement en Java SE.

En un coup d’œil

Spec implémentée

MicroProfile Telemetry 2.1 (OpenTelemetry API 1.39+, sémantique 1.27+)

Repo

https://codeberg.org/Vidocq/humboldt

Java

25 (LTS)

Modules JPMS

~16 modules — principaux : io.vidocq.humboldt.api, .sdk.trace, .sdk.metric, .sdk.log, .sdk.common, .context, .exporter.otlp.http, .propagator.w3c, .cdi, .rest, .runtime. Liste complète : Référence.

Dépendances runtime

opentelemetry-api, opentelemetry-context, opentelemetry-semconv, opentelemetry-instrumentation-annotations, protobuf-java, microprofile-telemetry-api. SDK et exporters tiers refusés.

Prête pour jlink

✅

TCK MP Telemetry 2.1

🚧 M7c en cours — premier passage OpenTelemetryBeanTest ✅ ; statut détaillé à confirmer (voir tck-runs/)

Trois traits identitaires

  1. 6 jars runtime au lieu d’environ 25 chez SmallRye Telemetry — pas de opentelemetry-sdk, pas de opentelemetry-exporter-otlp, pas de grpc-java, pas de Netty, pas de Guava.

  2. ScopedValue<Context> (JEP 506) au lieu de ThreadLocal direct — zéro pinning de carrier thread sur virtual threads dans la roadmap M8 (humboldt-context MVP en ThreadLocal conforme JDK 21+, ADR de migration tracée).

  3. APT + Class-File API au stade process-classes pour générer interceptors, providers et bridges — AOT-ready GraalVM / Leyden CDS, pas de proxy dynamique, pas de bytecode agent à chaud.

Position dans l’écosystème

flowchart LR
  App[Application utilisateur] -->|@WithSpan, MP Telemetry API| API[humboldt-api]
  HTTP[Requête HTTP entrante] -->|traceparent, tracestate| Prop[humboldt-propagator-w3c]
  Prop --> Ctx[humboldt-context]
  API --> Trace[humboldt-sdk-trace]
  API --> Metric[humboldt-sdk-metric]
  API --> Log[humboldt-sdk-log]
  Trace --> Batch[BatchSpanProcessor VT]
  Metric --> Reader[PeriodicMetricReader]
  Log --> BatchL[BatchLogRecordProcessor VT]
  Batch --> Exp[humboldt-exporter-otlp-http]
  Reader --> Exp
  BatchL --> Exp
  Exp -->|HTTP/JSON ou /protobuf| Coll[OTel Collector]
  Cassini[cassini-core] -->|filter| REST[humboldt-rest]
  REST --> API
  Vauban[vauban-core] -->|@Inject Tracer/Meter/Logger| CDI[humboldt-cdi]
  CDI --> API
  Ravel[ravel-core] -->|otel.*, mp.telemetry.*| Runtime[humboldt-runtime]
  Runtime --> Trace
  Runtime --> Metric
  Runtime --> Log

Humboldt partage son transport avec le reste de l’écosystème Vidocq (Chappe HTTP/1.1 + H2). Aucune dépendance Netty, grpc-java, OkHttp, Guava ou pile HTTP tierce. Le futur exporter gRPC OTLP sera livré via un module natif chappe-grpc (cf. PLAN.md §3.5).

Différenciation vs SmallRye Telemetry

SmallRye Humboldt

Dépendances runtime

~25 jars (otel-sdk, exporter-otlp, grpc-java, netty, guava, protobuf, perfmark, …)

6 jars (opentelemetry-api, -context, -semconv, protobuf-java, humboldt-*, microprofile-telemetry-api)

Réflexion runtime

oui (Weld + OTel reflection)

non — APT + Class-File API à process-classes

Pinning virtual threads

risque (ThreadLocal Context)

non — ScopedValue<Context> (JEP 506, roadmap M8)

AOT-ready (GraalVM, Leyden)

partiel

oui dès le design

Transport OTLP v1

gRPC ou HTTP

HTTP/protobuf et HTTP/JSON (gRPC via futur chappe-grpc natif)

Chapitres

  • Démarrage rapide — ajouter Humboldt à un projet Vidocq en quelques minutes.

  • Concepts — modèle OpenTelemetry (Span, Metric, LogRecord, Context, Resource, Scope) et apport de MP Telemetry 2.1.

  • Cas d’usage — @WithSpan, injection Tracer/Meter/Logger, exporter OTLP, sampling, baggage.

  • Fonctionnement interne — pipeline SDK, BatchSpanProcessor sur virtual threads, JEP 506, codegen APT/Class-File.

  • TCK — statut MicroProfile Telemetry 2.1, commandes, contraintes hors-reactor.

  • Référence — table complète des modules JPMS, clés otel. / mp.telemetry., semantic conventions.

  • Migration — depuis SmallRye Telemetry / Quarkus OpenTelemetry.

Bugs et benchmarks consolidés : lien:https://codeberg.org/Vidocq/humboldt/src/branch/main/BUG.md[BUG.md], lien:https://codeberg.org/Vidocq/humboldt/src/branch/main/BENCH.md[BENCH.md].

Suivant : Démarrage rapide.