Environment variables, JVM properties, defaults, and precedence for server trace export.

OpenTelemetry configuration

GoodMem reads OTel configuration at startup, with JVM system properties first, environment variables second, and defaults last. Use those properties or variables rather than GoodMem server or Go CLI flags.

For JVM properties, use lowercase names with dots instead of underscores:

Environment variable	JVM property
`OTEL_SERVICE_NAME`	`otel.service.name`
`GOODMEM_OTEL_EXPORT_PROFILE`	`goodmem.otel.export.profile`
`GOODMEM_OTEL_REMOTE_PARENT`	`goodmem.otel.remote.parent`

Place JVM properties before -jar:

java -Dotel.service.name=memory-api -jar goodmem-server.jar

Retain the usual database and server configuration alongside these properties. Restart the server after a telemetry configuration change.

Export and identity

Environment variable	Default	Meaning
`OTEL_TRACES_EXPORTER`	`none`	`otlp` enables network export; `logging` writes spans to local output
`OTEL_METRICS_EXPORTER`	`none`	SDK metric exporter; separate from GoodMem Micrometer metrics
`OTEL_LOGS_EXPORTER`	`none`	SDK log exporter; separate from GoodMem application logs
`OTEL_SDK_DISABLED`	`false`	`true` disables SDK signal processing and export; context propagation remains available
`OTEL_SERVICE_NAME`	`goodmem-server`	Service identity in the backend
`OTEL_RESOURCE_ATTRIBUTES`	Server build supplies `service.version`	Comma-separated resource attributes; explicit values can override the build version
`GOODMEM_OTEL_EXPORT_PROFILE`	`neutral`	`neutral`, `langfuse`, or `langsmith`
`GOODMEM_OTEL_REMOTE_PARENT`	`parent`	`parent` continues an external trace; `link` starts a separate trace

Vendor profiles affect exported metadata only; endpoint selection and request execution remain separate.

For OTEL_RESOURCE_ATTRIBUTES, use plain values such as deployment.environment.name=production, without OTLP header encoding.

OTLP transport

Environment variable	Default	Meaning
`OTEL_EXPORTER_OTLP_PROTOCOL`	`grpc`	`grpc` or `http/protobuf`
`OTEL_EXPORTER_OTLP_ENDPOINT`	SDK local receiver default	Generic endpoint; select an explicit destination for deployed servers
`OTEL_EXPORTER_OTLP_HEADERS`	No headers	Comma-separated `name=value` pairs
`OTEL_EXPORTER_OTLP_TIMEOUT`	SDK default	Export timeout
`OTEL_EXPORTER_OTLP_COMPRESSION`	`none`	`none` or `gzip`
`OTEL_EXPORTER_OTLP_CERTIFICATE`	Platform trust store	PEM trust certificate file
`OTEL_EXPORTER_OTLP_CLIENT_CERTIFICATE`	Unset	PEM client certificate file for mTLS
`OTEL_EXPORTER_OTLP_CLIENT_KEY`	Unset	PEM private key file for mTLS

Each transport setting also has a trace-specific form:

OTEL_EXPORTER_OTLP_TRACES_PROTOCOL
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT
OTEL_EXPORTER_OTLP_TRACES_HEADERS
OTEL_EXPORTER_OTLP_TRACES_TIMEOUT
OTEL_EXPORTER_OTLP_TRACES_COMPRESSION
OTEL_EXPORTER_OTLP_TRACES_CERTIFICATE
OTEL_EXPORTER_OTLP_TRACES_CLIENT_CERTIFICATE
OTEL_EXPORTER_OTLP_TRACES_CLIENT_KEY

Trace-specific settings take precedence over generic settings. A nonempty trace-specific header map replaces the generic headers.

Endpoint paths

With HTTP/protobuf, the SDK appends /v1/traces to the generic endpoint but uses a trace-specific endpoint exactly as supplied.

Form	Example
Generic HTTP endpoint	`OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318`
Complete trace endpoint	`OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://otel-collector:4318/v1/traces`
gRPC endpoint	`OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4317`

Use the base receiver URL for a generic HTTP endpoint or a gRPC endpoint. Langfuse requires an explicit http/protobuf setting for this server.

Header values

Use percent encoding for special characters in header values. Keep the header names, commas, and separator equals signs outside that encoding. Use %20 for a space and %2B for a literal plus. The Java SDK decodes a raw plus as a space.

See the Langfuse header recipe for an executable example.

TLS files

Use HTTPS for remote collectors. For mTLS, supply both the client certificate and the private key. For containers, mount those files read-only at paths inside the server filesystem.

Sampling and propagation

Environment variable	Default	Meaning
`OTEL_PROPAGATORS`	`tracecontext`	W3C `traceparent` and `tracestate`; remote baggage is off
`OTEL_TRACES_SAMPLER`	`parentbased_always_on`	Sampler for recorded traces
`OTEL_TRACES_SAMPLER_ARG`	Unset	Argument for the selected sampler

For a transport check, use always_on. For a production ratio, use a configuration such as:

OTEL_TRACES_SAMPLER=parentbased_traceidratio
OTEL_TRACES_SAMPLER_ARG=0.1

This configuration samples approximately ten percent of local root traces, while parent retains the caller sampling decision. The link policy instead uses a local decision. Head sampling uses information available at the start of the operation.

See application trace correlation for caller requirements.

Queue and attribute limits

GoodMem honors the standard OTEL_BSP_* and attribute-limit variables from the Java SDK configuration reference. Lower SDK limits can remove fields that backend filters need.

Startup and shutdown

If telemetry initialization fails, GoodMem disables export, emits a sanitized diagnostic, and continues to serve requests. The independent Prometheus endpoint exposes the initialization-failure gauge. Correct rejected configuration before the next restart.

The server drains requests, maintenance tasks, and background work before a short, bounded final export. For planned stops, use an explicit drain before container termination. See Allow time for shutdown for the command, recommended grace period, and deployment checks.

OpenTelemetry configuration

On this page