agents-features-opentelemetry/ai.koog.agents.features.opentelemetry.feature/OpenTelemetryConfig

OpenTelemetryConfig

expect class OpenTelemetryConfig : FeatureConfig, OpenTelemetryConfigAPI(source)

Configuration class for the OpenTelemetry integration.

Tracing is backed by the Kotlin Multiplatform OpenTelemetry SDK - the tracing surface defined here (span processors, resource attributes, verbose mode, service info) is available on every target.

Tracing-side integrations (Langfuse, W&B Weave, Datadog) ship as commonMain extensions on top of an OTLP/JSON exporter, so they work on every target. The Kotlin SDK ships no metrics module, so metrics still live behind JVM-only extension functions declared in jvmMain (addMetricExporter, addMetricFilter, meter).

Power users who need full control over the SDK (custom samplers, custom span processors, span limits, etc.) can construct their own OpenTelemetry via createOpenTelemetry and inject it via setSdk - in that case the other configuration setters become inert.

actual class OpenTelemetryConfig : <ERROR CLASS> ERROR CLASS: Symbol not found for FeatureConfig, OpenTelemetryConfigAPI(source)

Configuration class for the OpenTelemetry feature, providing integration and export mechanisms for traces, metrics, and other telemetry data. This class abstracts the underlying implementation and offers convenient methods for setup and configuration within the Kotlin Multiplatform SDK.

The class includes constructors, methods, and properties used to manage telemetry exporters, filters, and adapters, as well as Java-friendly API overrides for compatibility with Java callers.

This configuration is designed to work across different platforms and integrates seamlessly with Java SDK.

Note: Some configurations rely on the Java SDK due to limitations in the current Kotlin Multiplatform SDK.

actual class OpenTelemetryConfig : FeatureConfig, OpenTelemetryConfigAPI(source)

Configuration class for the OpenTelemetry integration.

Tracing is backed by the Kotlin Multiplatform OpenTelemetry SDK - the tracing surface defined here (span processors, resource attributes, verbose mode, service info) is available on every target.

Constructors

OpenTelemetryConfig

expect constructor()

Constructs a new OpenTelemetryConfig with default service information.

actual constructor()

Constructs a new OpenTelemetryConfig with default service information.

actual constructor()

Constructs a new OpenTelemetryConfig with default service information.

Properties

eventFilter

val eventFilter: (AgentLifecycleEventContext) -> Boolean

isShutdownOnAgentClose

expect open override val isShutdownOnAgentClose: Boolean

Indicates whether OpenTelemetry resources should be shut down when the agent closes.

open override val isShutdownOnAgentClose: Boolean

Indicates whether OpenTelemetry resources should be shut down when the agent closes.

open override val isShutdownOnAgentClose: Boolean

Indicates whether OpenTelemetry resources should be shut down when the agent closes.

isVerbose

expect open override val isVerbose: Boolean

Indicates whether verbose telemetry data is enabled.

open override val isVerbose: Boolean

Indicates whether verbose telemetry data is enabled.

open override val isVerbose: Boolean

Indicates whether verbose telemetry data is enabled.

messageProcessors

val messageProcessors: List<FeatureMessageProcessor>

meter

val meter: Meter

Java-SDK Meter used to create counters, histograms, and gauges.

serviceName

expect open override val serviceName: String

The service name reported in resource attributes.

open override val serviceName: String

The service name reported in resource attributes.

open override val serviceName: String

The service name reported in resource attributes.

serviceNamespace

expect open override val serviceNamespace: String?

The service namespace reported in resource attributes, or null if not set.

open override val serviceNamespace: String?

The service namespace reported in resource attributes, or null if not set.

open override val serviceNamespace: String?

The service namespace reported in resource attributes, or null if not set.

serviceVersion

expect open override val serviceVersion: String

The service version reported in resource attributes.

open override val serviceVersion: String

The service version reported in resource attributes.

open override val serviceVersion: String

The service version reported in resource attributes.

tracer

expect open override val tracer: Tracer

The Kotlin Multiplatform OpenTelemetry SDK Tracer used by the feature.

open override val tracer: io/opentelemetry/kotlin/tracing/Tracer

The Kotlin Multiplatform OpenTelemetry SDK Tracer used by the feature.

open override val tracer: Tracer

The Kotlin Multiplatform OpenTelemetry SDK Tracer used by the feature.

Functions

addDatadogExporter

fun addDatadogExporter(datadogApiKey: String? = null, url: String? = null, timeout: Duration? = null, resourceAttributes: Map<String, String>? = null)

Java-friendly entry point for the Datadog integration. Mirrors the commonMain addDatadogExporter but accepts java.time.Duration for timeout so Java callers can pass every parameter - the commonMain overload uses kotlin.time.Duration, whose value-class JVM-name mangling makes the resourceAttributes argument unreachable from Java.

addDatadogExporter

@JvmOverloads

fun OpenTelemetryConfig.addDatadogExporter(datadogApiKey: String? = null, url: String? = null, timeout: Duration? = null, resourceAttributes: Map<String, String>? = null)

Configure an OpenTelemetry span exporter that sends data to Datadog via direct OTLP intake.

addLangfuseExporter

fun addLangfuseExporter(langfuseUrl: String? = null, langfusePublicKey: String? = null, langfuseSecretKey: String? = null, timeout: Duration? = null, traceAttributes: List<CustomAttribute>? = null)

Java-friendly entry point for the Langfuse integration. Mirrors the commonMain addLangfuseExporter but accepts java.time.Duration for timeout so Java callers can pass every parameter - the commonMain overload uses kotlin.time.Duration, whose value-class JVM-name mangling makes the traceAttributes argument unreachable from Java.

addLangfuseExporter

@JvmOverloads

fun OpenTelemetryConfig.addLangfuseExporter(langfuseUrl: String? = null, langfusePublicKey: String? = null, langfuseSecretKey: String? = null, timeout: Duration? = null, traceAttributes: List<CustomAttribute>? = null)

Configures a span exporter that sends data to Langfuse and installs the Langfuse SpanAdapter that reshapes spans to the Langfuse-recommended attribute layout.

addLangfuseSpanAdapter

@JvmOverloads

fun OpenTelemetryConfig.addLangfuseSpanAdapter(traceAttributes: List<CustomAttribute>? = null)

Installs the Langfuse SpanAdapter without registering the Langfuse cloud exporter. Spans are reshaped to the Langfuse-recommended attribute layout but are emitted only through whatever exporters the caller registers separately.

addMessageProcessor

fun addMessageProcessor(processor: FeatureMessageProcessor)

addMetricExporter

fun addMetricExporter(exporter: MetricExporter, meterInterval: ERROR CLASS: Symbol not found for Duration = defaultMeterInterval)

Registers a Java-SDK MetricExporter driven by a PeriodicMetricReader at meterInterval.

fun addMetricExporter(exporter: MetricExporter, meterInterval: Duration)

Registers a OTel Java SDK MetricExporter driven by a PeriodicMetricReader at meterInterval.

addMetricFilter

fun addMetricFilter(metricName: String, keysToRetain: Set<String>)

Registers a filter that restricts the attribute keys retained on a given metric during aggregation.

addResourceAttributes

expect open override fun addResourceAttributes(attributes: Map<String, Any>)

Adds resource attributes reported alongside every exported span.

open override fun addResourceAttributes(attributes: Map<String, Any>)

Adds resource attributes reported alongside every exported span.

open override fun addResourceAttributes(attributes: Map<String, Any>)

Adds resource attributes reported alongside every exported span.

addSpanAdapter

expect open override fun addSpanAdapter(adapter: SpanAdapter)

Installs a SpanAdapter that post-processes every GenAI span. Replaces any previously installed adapter.

open override fun addSpanAdapter(adapter: SpanAdapter)

Installs a SpanAdapter that post-processes every GenAI span. Replaces any previously installed adapter.

open override fun addSpanAdapter(adapter: SpanAdapter)

Installs a SpanAdapter that post-processes every GenAI span. Replaces any previously installed adapter.

addSpanExporter

expect open override fun addSpanExporter(exporter: SpanExporter)

Registers exporter wrapped in a batchSpanProcessor - the OTel-recommended default for production deployments. Spans are buffered and flushed on a worker so the agent never blocks on network I/O at the span end.

fun addSpanExporter(exporter: SpanExporter)

JVM convenience that bridges a Java-SDK SpanExporter to the Kotlin SDK via toOtelKotlinSpanExporter and registers it through addSpanExporter.

open override fun addSpanExporter(exporter: io/opentelemetry/kotlin/tracing/export/SpanExporter)

open override fun addSpanExporter(exporter: SpanExporter)

addSpanProcessor

expect open override fun addSpanProcessor(factory: TraceExportConfigDsl.() -> SpanProcessor)

Registers a SpanProcessor produced by a factory invoked inside the SDK's TraceExportConfigDsl scope. Use this when the convenience addSpanExporter (which always wraps in batchSpanProcessor) doesn't fit - e.g., custom batching parameters, custom processor implementations, or a compositeSpanProcessor over several inner processors.

open override fun addSpanProcessor(factory: io/opentelemetry/kotlin/init/TraceExportConfigDsl.() -> io/opentelemetry/kotlin/tracing/export/SpanProcessor)

open override fun addSpanProcessor(factory: TraceExportConfigDsl.() -> SpanProcessor)

addWeaveExporter

fun addWeaveExporter(weaveOtelBaseUrl: String? = null, weaveEntity: String? = null, weaveProjectName: String? = null, weaveApiKey: String? = null, timeout: Duration? = null)

Java-friendly entry point for the W&B Weave integration. Mirrors the commonMain addWeaveExporter but accepts java.time.Duration for timeout - the commonMain overload uses kotlin.time.Duration, whose value-class JVM-name mangling hides the timeout overload from Java callers.

addWeaveExporter

@JvmOverloads

fun OpenTelemetryConfig.addWeaveExporter(weaveOtelBaseUrl: String? = null, weaveEntity: String? = null, weaveProjectName: String? = null, weaveApiKey: String? = null, timeout: Duration? = null)

Configures a span exporter that sends data to W&B Weave and installs the Weave SpanAdapter that reshapes spans to the Weave-recommended attribute layout.

addWeaveSpanAdapter

fun OpenTelemetryConfig.addWeaveSpanAdapter()

Installs the W&B Weave SpanAdapter without registering the Weave cloud exporter. Spans are reshaped to the Weave-recommended attribute layout but are emitted only through whatever exporters the caller registers separately.

restrictToolNameCardinality

fun OpenTelemetryConfig.restrictToolNameCardinality(allowedToolNames: Set<String>, fallbackToolName: String = FALLBACK_TOOL_NAME)

Restricts tool names in the attributes' metric and sets the fallback tool name when a tool is not allowed. Helps to manage cardinality of the metric.

setEventFilter

open fun setEventFilter(filter: (AgentLifecycleEventContext) -> Boolean)

open override fun setEventFilter(filter: (ERROR CLASS: Symbol not found for AgentLifecycleEventContext) -> Boolean)

open override fun setEventFilter(filter: (AgentLifecycleEventContext) -> Boolean)

setSdk

expect open override fun setSdk(openTelemetry: OpenTelemetry)

Injects a pre-built Kotlin OpenTelemetry SDK to use for tracing.

open override fun setSdk(openTelemetry: io/opentelemetry/kotlin/OpenTelemetry)

Injects a pre-built Kotlin OpenTelemetry SDK to use for tracing.

open override fun setSdk(openTelemetry: OpenTelemetry)

Injects a pre-built Kotlin OpenTelemetry SDK to use for tracing.

setServiceInfo

expect open override fun setServiceInfo(serviceName: String, serviceVersion: String, serviceNamespace: String? = null)

Sets the service information reported in resource attributes.

fun setServiceInfo(serviceName: String, serviceVersion: String)

Java-friendly 2-arg overload of setServiceInfo that omits the optional serviceNamespace.

open override fun setServiceInfo(serviceName: String, serviceVersion: String, serviceNamespace: String? = null)

Sets the service information reported in resource attributes.

open override fun setServiceInfo(serviceName: String, serviceVersion: String, serviceNamespace: String? = null)

Sets the service information reported in resource attributes.

setShutdownOnAgentClose

expect open override fun setShutdownOnAgentClose(shutdownOnAgentClose: Boolean)

Toggles whether OpenTelemetryPlatform.shutdown runs when the agent closes. See isShutdownOnAgentClose.

open override fun setShutdownOnAgentClose(shutdownOnAgentClose: Boolean)

Toggles whether OpenTelemetryPlatform.shutdown runs when the agent closes. See isShutdownOnAgentClose.

open override fun setShutdownOnAgentClose(shutdownOnAgentClose: Boolean)

Toggles whether OpenTelemetryPlatform.shutdown runs when the agent closes. See isShutdownOnAgentClose.

setVerbose

expect open override fun setVerbose(verbose: Boolean)

Toggles verbose telemetry capture. See isVerbose.

open override fun setVerbose(verbose: Boolean)

Toggles verbose telemetry capture. See isVerbose.

open override fun setVerbose(verbose: Boolean)

Toggles verbose telemetry capture. See isVerbose.