feat!: telemetry utils (#206)

[mstepien]

Signed-off-by: Marcin Stepien marcin.stepien@fluxon.com

Add Telemetry Utils #206

Adds Appendix D (Observability/Telemetry) mapping utilities to the Kotlin SDK.

• Adds dev.openfeature.kotlin.sdk.telemetry.EvaluationEvent data construct mapped to OpenTelemetry
• Adds dev.openfeature.kotlin.sdk.telemetry.Telemetry static mapping object exposing the createEvaluationEvent() bridging utility.
• Implements parsing logic translating HookContext and FlagEvaluationDetails payloads, accounting for Error state mutations, Context evaluations, and natively unwrapping SDK Value objects iteratively down to pure primitives/Maps.
• Adds unit and integration testing

Related Issues

Fixes #206

Breaking changes

EvaluationEvent and createEvaluationEvent() moved from dev.openfeature.kotlin.sdk to dev.openfeature.kotlin.sdk.telemetry.Telemetry. The old top-level function is replaced by Telemetry.createEvaluationEvent().

Notes

• Value Parsing: OpenFeature Value definitions natively wrap structures (Value.Structure, Value.List, etc). Because downstream standard OTEL loggers require primitives, createEvaluationEvent employs a robust recursive unwrapping mechanic natively translating custom dev.openfeature.kotlin.sdk.Value elements gracefully down to decoupled Kotlin Map<String, Any?> interfaces to prevent logging friction.
• This implementation relies on zero external dependencies.

How to test

./gradlew :kotlin-sdk:testDebugUnitTest --tests "dev.openfeature.kotlin.sdk.telemetry.*"

[gemini-code-assist]

Code Review

This pull request introduces a telemetry module to the Kotlin SDK, enabling the creation of OpenTelemetry-compliant evaluation events based on the OpenFeature specification. It includes a new EvaluationEvent data class and a Telemetry utility that maps evaluation details to standard OTel semantic conventions. The review feedback identifies a potential issue with case-sensitive string comparisons when detecting error states and suggests converting Instant values to strings to ensure compatibility with downstream OTel exporters.

[typotter]

This PR removes dev.openfeature.kotlin.sdk.EvaluationEvent and dev.openfeature.kotlin.sdk.TelemetryKt (the top-level createEvaluationEvent function) from the binary API and replaces them with dev.openfeature.kotlin.sdk.telemetry.*. Binary breaking change for any consumer importing the old symbols.

Pre-1.0 SDK so this is fine, but worth noting in the PR description so it shows up in release notes. Something like:

Breaking: EvaluationEvent and createEvaluationEvent() moved from dev.openfeature.kotlin.sdk to dev.openfeature.kotlin.sdk.telemetry.Telemetry. The old top-level function is replaced by Telemetry.createEvaluationEvent().