Vidocq Documentation

This page consolidates Humboldt’s public surface: artifacts to declare, exported Java modules, configuration keys recognized by HumboldtAutoConfigure, and OTel semantic conventions applied by the automatic filters.

Maven artifacts

groupId artifactId Role

io.vidocq.humboldt

humboldt-api

Public façade and stable SPI (io.vidocq.humboldt.spi.*).

io.vidocq.humboldt

humboldt-sdk-common

Resource, Clock, IdGenerator, Attributes.

io.vidocq.humboldt

humboldt-context

ContextStorageProvider SPI used by Context.current().

io.vidocq.humboldt

humboldt-sdk-trace

SdkTracerProvider, samplers, processors, BatchSpanProcessor.

io.vidocq.humboldt

humboldt-sdk-metric

SdkMeterProvider, sync and async instruments, PeriodicMetricReader.

io.vidocq.humboldt

humboldt-sdk-log

SdkLoggerProvider, LogRecordProcessor, batch.

io.vidocq.humboldt

humboldt-propagator-w3c

W3CPropagators.get() facade composing TraceContext + Baggage.

io.vidocq.humboldt

humboldt-exporter-otlp-http

OTLP/JSON and OTLP/protobuf exporter via java.net.http.HttpClient.

io.vidocq.humboldt

humboldt-cdi

WithSpanInterceptor, Tracer/Meter/Logger producers.

io.vidocq.humboldt

humboldt-rest

JAX-RS filters HumboldtServerRequestFilter / ResponseFilter.

io.vidocq.humboldt

humboldt-runtime

Aggregator, HumboldtAutoConfigure, AutoConfiguredHumboldt, EnvConfig.

io.vidocq.humboldt

humboldt-otel-api

Java Modules re-bundle of io.opentelemetry:opentelemetry-api (named module).

io.vidocq.humboldt

humboldt-otel-context

Java Modules re-bundle of io.opentelemetry:opentelemetry-context.

io.vidocq.humboldt

humboldt-otel-instrumentation-annotations

Java Modules re-bundle of opentelemetry-instrumentation-annotations.

io.vidocq.humboldt

humboldt-tck

Official MicroProfile Telemetry 2.1 TCK runner — in-reactor, gated by the tck Maven profile. Do not declare as an application dependency.

All versions are 0.2.0 at the time of writing (M7c in progress).

Java modules

Module Contents

io.vidocq.humboldt.api

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

io.vidocq.humboldt.sdk.common

Resource, Clock, IdGenerator (Random128).

io.vidocq.humboldt.context

HumboldtContextStorageProvider, HumboldtContextStorage (MVP ThreadLocal, ScopedValue planned in 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, Simple + Batch processors.

io.vidocq.humboldt.propagator.w3c

W3CPropagators.get() — composite TraceContext + Baggage.

io.vidocq.humboldt.exporter.otlp.http

OtlpHttpSpanExporter, OtlpHttpMetricExporter, OtlpHttpLogExporter, OtlpJsonEncoder, exponential retry.

io.vidocq.humboldt.cdi

@WithSpan annotation (re-exported), WithSpanInterceptor, HumboldtBuildCompatibleExtension, Tracer/Meter/Logger producers.

io.vidocq.humboldt.rest

HumboldtServerRequestFilter, HumboldtServerResponseFilter (JAX-RS @Provider).

io.vidocq.humboldt.runtime

HumboldtAutoConfigure, AutoConfiguredHumboldt, EnvConfig.

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

Java modules of the public OTel artifacts, rebundled with explicit module-info.

io.vidocq.humboldt.internal.* packages are never exported. Any direct access fails with a clear Java Modules crash.

Configuration keys

Humboldt reads standard OpenTelemetry env vars, with fallback to equivalent system properties (SCREAMING_SNAKE_CASE → lower.dot.case).

Service identification

Key Default Effect

OTEL_SERVICE_NAME / otel.service.name

unknown_service:java

service.name attribute of the Resource.

OTEL_RESOURCE_ATTRIBUTES / otel.resource.attributes

(empty)

key1=value1,key2=value2 list merged into the Resource.

Exporter per signal

Key Default Values

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

OTLP HTTP endpoint

Key Default Effect

OTEL_EXPORTER_OTLP_ENDPOINT

http://localhost:4318

Common endpoint (suffix /v1/traces etc. added automatically).

OTEL_EXPORTER_OTLP_TRACES_ENDPOINT

(inherited)

Traces override.

OTEL_EXPORTER_OTLP_METRICS_ENDPOINT

(inherited)

Metrics override.

OTEL_EXPORTER_OTLP_LOGS_ENDPOINT

(inherited)

Logs override.

OTEL_EXPORTER_OTLP_HEADERS

(empty)

Comma-separated HTTP headers key1=value1,key2=value2.

OTEL_EXPORTER_OTLP_TIMEOUT

(deferred M7)

Request timeout, ms.

OTEL_EXPORTER_OTLP_PROTOCOL

http/protobuf

http/json or http/protobuf. Full switch deferred to M7.

Sampling

Key Default Values

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 for traceidratio (0.0 to 1.0).

Metric reading

Key Default Effect

OTEL_METRIC_EXPORT_INTERVAL

60000 ms (in-memory = 60min)

Period of PeriodicMetricReader.

OTEL_METRIC_EXPORT_TIMEOUT

(deferred M7)

Collection timeout.

MicroProfile Telemetry

Key Default Effect

mp.telemetry.sdk.disabled

false

Completely disable the SDK (no-op). Deferred M7.

mp.telemetry.propagators

tracecontext,baggage

Comma-separated propagator list. Deferred M7.

Applied semantic conventions

OTel HTTP conventions 1.27+ are applied automatically by humboldt-rest on the server side:

Attribute Source

http.request.method

ContainerRequestContext.getMethod()

url.path

getUriInfo().getPath() normalized to /

url.scheme

getUriInfo().getRequestUri().getScheme()

http.response.status_code

ContainerResponseContext.getStatus() (long)

error.type / status ERROR

If status_code ≥ 500 (4xx ignored — OTel HTTP convention)

For client-side attributes (HTTP, DB, messaging…), Humboldt does not generate them automatically: use the constants from opentelemetry-semconv in application code. Full reference: OpenTelemetry Semantic Conventions.

Registered propagators

AutoConfiguredHumboldt.getPropagators() returns by default a composite TextMapPropagator:

  1. W3CTraceContextPropagator — headers traceparent, tracestate.

  2. W3CBaggagePropagator — header baggage.

No B3 by default (opt-in via mp.telemetry.propagators=tracecontext,baggage,b3 once the key is enabled in M7).

Outputs and formats

Exporter Output

otlp

OTLP/HTTP POST — JSON or protobuf depending on OTEL_EXPORTER_OTLP_PROTOCOL.

in-memory

InMemorySpanExporter / InMemoryMetricReader / InMemoryLogRecordExporter buffers — used by tests.

logging

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

none

No processor registered — signal disabled.

Compatibility

  • Java 25 LTS minimum (compile and runtime).

  • Maven 3.9.16 or later (Model 4.0.0 everywhere; the TCK runner is in-reactor behind the tck profile).

  • Compatible with CDI 4.1 Lite (Vauban) and JAX-RS 4.0 (Cassini). CDI Full (Weld, OpenWebBeans) not tested.

Next: Internals.