Vidocq Documentation

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, Ravel for configuration, and Cassini for JAX-RS instrumentation. 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://codeberg.org/Vidocq/humboldt

Java

25 (LTS)

JPMS modules

~16 modules — main ones: io.vidocq.humboldt.api, .sdk.trace, .sdk.metric, .sdk.log, .sdk.common, .context, .exporter.otlp.http, .propagator.w3c, .cdi, .rest, .runtime. Full list: Reference.

Runtime dependencies

opentelemetry-api, opentelemetry-context, opentelemetry-semconv, opentelemetry-instrumentation-annotations, protobuf-java, microprofile-telemetry-api. Third-party SDK and exporters refused.

jlink-ready

✅

MP Telemetry 2.1 TCK

🚧 M7c in progress — first OpenTelemetryBeanTest PASS ✅ ; detailed status to be confirmed (see tck-runs/)

Three identity traits

  1. 6 runtime jars instead of about 25 in SmallRye Telemetry — no opentelemetry-sdk, no opentelemetry-exporter-otlp, no grpc-java, no Netty, no Guava.

  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. APT + Class-File API at process-classes to generate interceptors, providers and bridges — AOT-ready for GraalVM / Leyden CDS, no dynamic proxy, no hot bytecode agent.

Position in the ecosystem

flowchart LR
  App[User application] -->|@WithSpan, MP Telemetry API| API[humboldt-api]
  HTTP[Inbound HTTP request] -->|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 or /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 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, …)

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

Runtime reflection

yes (Weld + OTel reflection)

no — APT + Class-File API at process-classes

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/protobuf and HTTP/JSON (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, APT/Class-File codegen.

  • TCK — MicroProfile Telemetry 2.1 status, commands, out-of-reactor constraints.

  • Reference — full JPMS module table, otel. / mp.telemetry. keys, semantic conventions.

  • Migration — from SmallRye Telemetry / Quarkus OpenTelemetry.

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

Next: Getting started.