Vidocq Documentation
Version

Humboldt is the MicroProfile Telemetry 2.1 implementation of the Vidocq ecosystem. It rewrites its own OpenTelemetry SDK (traces, metrics, logs) directly on top of the public OTel API surface, and integrates with Chappe for HTTP transport, Vauban for CDI, and Cassini for JAX-RS instrumentation; configuration comes from the standard OTEL_* environment variables and otel. system properties. Goal: 100 % official TCK conformance, with no opentelemetry-sdk / opentelemetry-exporter- dependency, no Netty, no gRPC stack.

Origin of the name

Alexander von Humboldt (1769–1859), Prussian polymath, naturalist, geographer, explorer. The man who made the founding gesture of modern observability: observe simultaneously, measure rigorously, correlate across layers. On Chimborazo in 1802, he jointly recorded barometric pressure, temperature, terrestrial magnetism, humidity, fauna and flora — then drew the first isothermal maps revealing the planet’s hidden invariants. He invented the Naturgemälde, the first scientific data visualization, and synthesized all his knowledge in Kosmos.

Reference: Humboldt on Wikipedia.

Humboldt the explorer Humboldt the runtime

Simultaneous observation (pressure, temperature, magnetism)

Three pillars: traces, metrics, logs (one SDK)

Isothermal maps

Aggregated views per dimension (correlated results)

Voyages covering every layer (sea, plain, summit)

Cross-cutting instrumentation (web → DB → external)

Kosmos — global synthesis of natural knowledge

Unified OpenTelemetry document (W3C TraceContext + OTLP)

Network of magnetic stations

Network of processors / exporters / propagators

OpenTelemetry is the Naturgemälde of distributed systems. Humboldt embeds it natively in Java SE.

At a glance

Implemented spec

MicroProfile Telemetry 2.1 (OpenTelemetry API 1.39+, semconv 1.27+)

Repo

https://codefloe.com/Vidocq/humboldt

Java

25 (LTS)

Java modules

15 modules — main ones: io.vidocq.humboldt.api, .sdk.trace, .sdk.metric, .sdk.log, .sdk.common, .context, .exporter.otlp.http, .propagator.w3c, .cdi, .rest, .runtime, .otel.interop, plus the repackaged io.opentelemetry.api / .context / .instrumentation_annotations. Full list: Reference.

Runtime dependencies

None external. The public OpenTelemetry API surface (opentelemetry-api 1.39, -context, -instrumentation-annotations) is repackaged as explicit Java modules inside the humboldt-otel-* artifacts; opentelemetry-semconv appears only in the TCK harness; no protobuf-java, no microprofile-telemetry-api jar. Third-party SDK and exporters refused.

jlink-ready

✅

MP Telemetry 2.1 TCK

✅ 85/85 PASS — full official suite (tracing + metrics + logs), re-verified stable 2026-06-01 (see tck-runs/ and TCK.md)

Three identity traits

  1. Self-contained jars, zero external runtime dependency instead of about 25 third-party jars in SmallRye Telemetry — no opentelemetry-sdk, no opentelemetry-exporter-otlp, no grpc-java, no Netty, no Guava, no protobuf.

  2. ScopedValue<Context> (JEP 506) instead of plain ThreadLocal — zero carrier-thread pinning on virtual threads, planned for M8 (humboldt-context MVP uses JDK 21+-compliant ThreadLocal, migration ADR tracked).

  3. No runtime bytecode machinery — no agent, no ASM/Byte Buddy; CDI wiring is generated at compile time by Vauban’s annotation processor. The one deliberate exception: humboldt-cdi creates two java.lang.reflect.Proxy instances so the injected current-Span and current-Baggage beans always track the active Context.

Position in the ecosystem

Diagram

Humboldt shares its transport with the rest of the Vidocq ecosystem (Chappe HTTP/1.1 + H2). No Netty, grpc-java, OkHttp, Guava or any third-party HTTP stack. The future OTLP gRPC exporter will ship through a native chappe-grpc module (cf. PLAN.md §3.5).

Differentiation vs SmallRye Telemetry

SmallRye Humboldt

Runtime dependencies

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

zero external — self-contained humboldt- jars; the OTel API surface is repackaged inside humboldt-otel-

Runtime reflection

yes (Weld + OTel reflection)

almost none — CDI wiring generated at compile time (Vauban processor); the only dynamic proxies are the two injected current-Span / current-Baggage beans

Virtual-thread pinning

risk (ThreadLocal Context)

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

AOT-ready (GraalVM, Leyden)

partial

yes by design

OTLP transport v1

gRPC or HTTP

HTTP/JSON only (protobuf not shipped; gRPC through future native chappe-grpc)

Chapters

  • Getting started — add Humboldt to a Vidocq project in a few minutes.

  • Concepts — OpenTelemetry model (Span, Metric, LogRecord, Context, Resource, Scope) and what MP Telemetry 2.1 adds.

  • Usage — @WithSpan, Tracer/Meter/Logger injection, OTLP exporter, sampling, baggage.

  • Internals — SDK pipeline, BatchSpanProcessor on virtual threads, JEP 506, bootstrap sequence.

  • TCK — MicroProfile Telemetry 2.1 status (85/85 PASS), commands, in-reactor runner behind the tck profile.

  • Reference — full Java module table, OTEL_* / otel.* keys, semantic conventions.

  • Migration — from SmallRye Telemetry / Quarkus OpenTelemetry.

Consolidated bugs and benchmarks: BUG.md, BENCH.md.

Next: Getting started.