Vidocq Documentation

Cette page consolide la surface publique de Humboldt : artefacts à déclarer, modules Java exportés, clés de configuration reconnues par HumboldtAutoConfigure, et conventions sémantiques OTel appliquées par les filters automatiques.

Artefacts Maven

groupId artifactId Rôle

io.vidocq.humboldt

humboldt-api

Façade publique et SPI stable (io.vidocq.humboldt.spi.*).

io.vidocq.humboldt

humboldt-sdk-common

Resource, Clock, IdGenerator, Attributes.

io.vidocq.humboldt

humboldt-context

ContextStorageProvider SPI utilisé par Context.current().

io.vidocq.humboldt

humboldt-sdk-trace

SdkTracerProvider, samplers, processors, BatchSpanProcessor.

io.vidocq.humboldt

humboldt-sdk-metric

SdkMeterProvider, instruments synchrones et async, PeriodicMetricReader.

io.vidocq.humboldt

humboldt-sdk-log

SdkLoggerProvider, LogRecordProcessor, batch.

io.vidocq.humboldt

humboldt-propagator-w3c

Façade W3CPropagators.get() composant TraceContext + Baggage.

io.vidocq.humboldt

humboldt-exporter-otlp-http

Exporter OTLP/JSON et OTLP/protobuf via java.net.http.HttpClient.

io.vidocq.humboldt

humboldt-cdi

WithSpanInterceptor, producers Tracer/Meter/Logger.

io.vidocq.humboldt

humboldt-rest

Filters JAX-RS HumboldtServerRequestFilter / ResponseFilter.

io.vidocq.humboldt

humboldt-runtime

Agrégateur, HumboldtAutoConfigure, AutoConfiguredHumboldt, EnvConfig.

io.vidocq.humboldt

humboldt-otel-api

Re-bundle Java Modules de io.opentelemetry:opentelemetry-api (module nommé).

io.vidocq.humboldt

humboldt-otel-context

Re-bundle Java Modules de io.opentelemetry:opentelemetry-context.

io.vidocq.humboldt

humboldt-otel-instrumentation-annotations

Re-bundle Java Modules de opentelemetry-instrumentation-annotations.

io.vidocq.humboldt

humboldt-tck

Runner officiel TCK MicroProfile Telemetry 2.1 — in-reactor, gardé par le profil Maven tck. Ne pas déclarer en dépendance applicative.

Toutes les versions à 0.2.0 au moment de la rédaction (jalon M7c en cours).

Modules Java Modules

Module Contenu

io.vidocq.humboldt.api

io.vidocq.humboldt.spi.* (SPI publique : ExporterProvider, SamplerProvider, ResourceProvider).

io.vidocq.humboldt.sdk.common

Resource, Clock, IdGenerator (Random128).

io.vidocq.humboldt.context

HumboldtContextStorageProvider, HumboldtContextStorage (ThreadLocal MVP, ScopedValue en M8).

io.vidocq.humboldt.sdk.trace

SdkTracerProvider, SdkSpan, Sampler (AlwaysOn/Off, TraceIdRatioBased, ParentBased), SpanProcessor (Simple, Batch).

io.vidocq.humboldt.sdk.metric

SdkMeterProvider, instruments (LongCounter, DoubleHistogram, async Gauge), PeriodicMetricReader, views.

io.vidocq.humboldt.sdk.log

SdkLoggerProvider, SdkLogger, SdkLogRecordBuilder, processors Simple + Batch.

io.vidocq.humboldt.propagator.w3c

W3CPropagators.get() — composite TraceContext + Baggage.

io.vidocq.humboldt.exporter.otlp.http

OtlpHttpSpanExporter, OtlpHttpMetricExporter, OtlpHttpLogExporter, OtlpJsonEncoder, retry exponentiel.

io.vidocq.humboldt.cdi

Annotation @WithSpan (re-export), WithSpanInterceptor, HumboldtBuildCompatibleExtension, producers Tracer/Meter/Logger.

io.vidocq.humboldt.rest

HumboldtServerRequestFilter, HumboldtServerResponseFilter (@Provider JAX-RS).

io.vidocq.humboldt.runtime

HumboldtAutoConfigure, AutoConfiguredHumboldt, EnvConfig.

io.opentelemetry.api, io.opentelemetry.context, io.opentelemetry.instrumentation_annotations

Modules Java Modules des artefacts OTel publics, rebundlés avec un module-info explicite.

Les packages io.vidocq.humboldt.internal.* ne sont jamais exportés. Tout accès direct passe par un crash Java Modules clair.

Clés de configuration

Humboldt lit les variables d’environnement OpenTelemetry standard, avec repli sur les system properties équivalentes (SCREAMING_SNAKE_CASE → lower.dot.case).

Identification du service

Clé Défaut Effet

OTEL_SERVICE_NAME / otel.service.name

unknown_service:java

Attribut service.name du Resource.

OTEL_RESOURCE_ATTRIBUTES / otel.resource.attributes

(vide)

Liste key1=value1,key2=value2 fusionnée dans le Resource.

Exporters par signal

Clé Défaut Valeurs

OTEL_TRACES_EXPORTER

otlp

otlp, none, in-memory, logging

OTEL_METRICS_EXPORTER

otlp

otlp, none, in-memory, logging

OTEL_LOGS_EXPORTER

otlp

otlp, none, in-memory, logging

Endpoint OTLP HTTP

Clé Défaut Effet

OTEL_EXPORTER_OTLP_ENDPOINT

http://localhost:4318

Endpoint commun (suffixe /v1/traces etc. ajouté automatiquement).

OTEL_EXPORTER_OTLP_TRACES_ENDPOINT

(hérité)

Override traces.

OTEL_EXPORTER_OTLP_METRICS_ENDPOINT

(hérité)

Override metrics.

OTEL_EXPORTER_OTLP_LOGS_ENDPOINT

(hérité)

Override logs.

OTEL_EXPORTER_OTLP_HEADERS

(vide)

Headers HTTP comma-separated key1=value1,key2=value2.

OTEL_EXPORTER_OTLP_TIMEOUT

(différé M7)

Timeout requête, ms.

OTEL_EXPORTER_OTLP_PROTOCOL

http/protobuf

http/json ou http/protobuf. M7 différé pour la bascule complète.

Sampling

Clé Défaut Valeurs

OTEL_TRACES_SAMPLER

parentbased_always_on

always_on, always_off, traceidratio, parentbased_always_on, parentbased_always_off, parentbased_traceidratio

OTEL_TRACES_SAMPLER_ARG

1.0

Ratio pour traceidratio (0.0 à 1.0).

Lecture des métriques

Clé Défaut Effet

OTEL_METRIC_EXPORT_INTERVAL

60000 ms (in-memory = 60min)

Période du PeriodicMetricReader.

OTEL_METRIC_EXPORT_TIMEOUT

(différé M7)

Timeout d’une collecte.

MicroProfile Telemetry

Clé Défaut Effet

mp.telemetry.sdk.disabled

false

Désactive complètement le SDK (no-op). Différé M7.

mp.telemetry.propagators

tracecontext,baggage

Liste comma-separated des propagators. Différé M7.

Sémantique conventions appliquées

Les conventions OTel HTTP 1.27+ sont appliquées automatiquement par humboldt-rest côté serveur :

Attribut Source

http.request.method

ContainerRequestContext.getMethod()

url.path

getUriInfo().getPath() normalisé /

url.scheme

getUriInfo().getRequestUri().getScheme()

http.response.status_code

ContainerResponseContext.getStatus() (long)

error.type / status ERROR

Si status_code ≥ 500 (4xx ignoré — convention OTel HTTP)

Pour les attributs côté client (HTTP, DB, messaging…), Humboldt ne génère pas automatiquement : utiliser les constantes de opentelemetry-semconv dans le code applicatif. Référence complète : OpenTelemetry Semantic Conventions.

Propagators enregistrés

AutoConfiguredHumboldt.getPropagators() retourne par défaut un TextMapPropagator composite :

  1. W3CTraceContextPropagator — headers traceparent, tracestate.

  2. W3CBaggagePropagator — header baggage.

Pas de B3 par défaut (opt-in via clé mp.telemetry.propagators=tracecontext,baggage,b3 une fois la clé activée en M7).

Sortie et formats

Exporter Sortie

otlp

POST OTLP/HTTP — JSON ou protobuf selon OTEL_EXPORTER_OTLP_PROTOCOL.

in-memory

Buckets InMemorySpanExporter / InMemoryMetricReader / InMemoryLogRecordExporter — utiles pour les tests.

logging

System.getLogger(…​).log() format human-readable.

none

Aucun processor enregistré — signal désactivé.

Compatibilité

  • Java 25 LTS minimum (compilation et runtime).

  • Maven 3.9.16 ou supérieur (Model 4.0.0 partout ; le runner TCK est in-reactor derrière le profil tck).

  • Compatible CDI 4.1 Lite (Vauban) et JAX-RS 4.0 (Cassini). CDI Full (Weld, OpenWebBeans) non testé.

Suivant : Fonctionnement interne.