Vidocq Documentation

Humboldt implémente OpenTelemetry. Pour utiliser Humboldt correctement, il faut connaître les abstractions OTel : les trois signaux (traces, metrics, logs), le Context qui les corrèle, le Resource qui identifie le producteur, et les TextMapPropagator qui transportent le contexte entre processus. MicroProfile Telemetry 2.1 ajoute une couche fine d’intégration CDI et de configuration.

Trois signaux, un seul SDK

OpenTelemetry sépare l’observabilité en trois signaux indépendants mais corrélables. Humboldt fournit les trois dans un seul SDK Java pur.

Signal API consommée Module Humboldt

Traces

io.opentelemetry.api.trace.Tracer

humboldt-sdk-trace — SdkTracerProvider, Sampler, SpanProcessor, BatchSpanProcessor

Metrics

io.opentelemetry.api.metrics.Meter

humboldt-sdk-metric — SdkMeterProvider, Counter, Histogram, Gauge async, PeriodicMetricReader

Logs

io.opentelemetry.api.logs.Logger

humboldt-sdk-log — SdkLoggerProvider, LogRecordProcessor, batch

Baggage

io.opentelemetry.api.baggage.Baggage

dans humboldt-sdk-trace (BaggageManager)

Context

io.opentelemetry.context.Context

humboldt-context — ContextStorageProvider SPI

Propagators

io.opentelemetry.context.propagation.TextMapPropagator

humboldt-propagator-w3c — TraceContext + Baggage

Span : unité de travail tracée

Un Span représente une opération bornée dans le temps : un appel HTTP, une requête SQL, une méthode métier. Chaque span porte un traceId (commun à tous les spans d’une même requête distribuée) et un spanId (unique). Un span possède un parent (le span englobant) et peut avoir des links (vers des spans d’autres traces).

Champs essentiels d’un span Humboldt (SpanData, record immuable) :

  • traceId (32 hex) et spanId (16 hex) — générés par IdGenerator (Random128 par défaut).

  • name, kind (SERVER, CLIENT, INTERNAL, PRODUCER, CONSUMER).

  • attributes — paires clé/valeur typées (http.request.method, db.system, etc.).

  • events — points horodatés avec attributs (exception, log, custom).

  • links — références vers d’autres spans (batching, fan-in).

  • status — UNSET, OK, ERROR (avec description).

  • startEpochNanos / endEpochNanos — horodatage monotone via Clock.

  • resource — fournisseur sortant (cf. plus bas).

  • instrumentationScope — name + version du producteur de spans.

Resource — qui produit les signaux ?

Un Resource identifie l’entité qui émet : service.name, service.version, deployment.environment, host.name, process.runtime.name, etc. Le Resource est fusionné une fois au démarrage et attaché à tous les spans, métriques et logs émis. Humboldt expose un Resource immutable à fusion sémantique conforme OTel.

Context — colle invisible entre signaux

Le Context OTel est une carte immuable propagée implicitement via une scope (try-with-resources) ou explicitement via Context.wrap(). Le Context courant porte le Span actif, le Baggage, et éventuellement d’autres clés (utilisateur, tenant…).

Humboldt fournit l’implémentation ContextStorageProvider SPI utilisée par Context.current() :

  • MVP M1 — ThreadLocal simple, conforme JDK 21+ : pas de pinning carrier thread sur virtual threads pour le code Java pur (JEP 444).

  • M8 — migration vers ScopedValue (JEP 506) si gain mémoire significatif sur >100 K virtual threads (ADR à statuer).

Scope vs Context

Distinction subtile : un Context est une valeur, un Scope est une activation du contexte sur le thread courant. Le pattern canonique :

Span span = tracer.spanBuilder("op").startSpan();
try (Scope ignored = span.makeCurrent()) {
    // ici, Span.current() == span et Context.current() porte span
} finally {
    span.end();
}

Oublier le close() du Scope = fuite : tout span ouvert sur le thread restera « courant » jusqu’à l’épuisement du thread.

Sampling — décider qui est tracé

Le Sampler OTel décide, à la création d’un span, si celui-ci sera enregistré et exporté. Humboldt fournit quatre samplers conformes spec :

  • AlwaysOn — tout est tracé. Utile en dev/intégration.

  • AlwaysOff — rien n’est tracé. Désactivation rapide.

  • TraceIdRatioBased(ratio) — décision déterministe sur les 64 bits bas du traceId ; ratio 0.1 = 10 % cohérent à travers tous les services.

  • ParentBased(root) — si parent existe et est sampled → sampled, sinon délègue à root. Combinaison standard parentbased_traceidratio + ratio 0.05 = production.

Propagation — passer le contexte entre services

Quand un appel HTTP sort du service, le traceId et le spanId doivent être injectés dans les headers HTTP pour que le service appelé continue la même trace. Le standard W3C définit deux headers :

  • traceparent — version-traceId-spanId-flags (33 octets ASCII).

  • tracestate — extensions vendor.

  • baggage — paires clé/valeur applicatives (W3C Baggage).

humboldt-propagator-w3c compose les deux propagators (W3CTraceContextPropagator + W3CBaggagePropagator) en un seul TextMapPropagator enregistré par défaut dans le runtime auto-configuré.

Semantic conventions — un vocabulaire commun

Les semantic conventions OTel normalisent les noms d’attributs et de métriques : http.request.method, http.response.status_code, db.system, db.statement, messaging.system, network.peer.address, etc. Humboldt importe opentelemetry-semconv (spec uniquement) pour exposer les constantes, et les filters humboldt-rest les appliquent automatiquement sur les requêtes JAX-RS entrantes (conventions HTTP 1.27+).

Référence : OpenTelemetry Semantic Conventions. Humboldt ne réimplémente pas la convention : il la consomme.

MicroProfile Telemetry 2.1 vs OTel API directe

MicroProfile Telemetry 2.1 est une couche fine au-dessus d’OpenTelemetry, ajoutant essentiellement :

  • CDI producers : @Inject Tracer, @Inject Meter, @Inject io.opentelemetry.api.logs.Logger, @Inject Span (current), @Inject Baggage (current).

  • Configuration via MicroProfile Config (mp.telemetry. et otel.) — Humboldt s’appuie sur Ravel pour la résolution.

  • @WithSpan (opentelemetry-instrumentation-annotations) câblé via un interceptor CDI.

Aucun de ces ajouts ne casse l’API OTel : on peut toujours appeler GlobalOpenTelemetry.getTracer(…​) directement.

Suivant : Cas d’usage.