feat: O11Y-374 - Add identify span in TracingHook (#232)

## Summary

This PR implements the beforeIdentify and afterIdentify functions from
the Hook abstract class in `EvalTracingHook` for tracing identify events
through an span. It also makes the OpenTelemetry instance global in
`InstrumentationManager` to ensure it's accessible throughout the
application.

Additionally, the `BaseApplication.kt` in the e2e test app has been
updated to call `LDClient.get().identify(context)` after initialization
for testing purposes.

## How did you test this change?
Unit test

## Are there any deployment considerations?
No

Author: agrognetti

e2e/android/app/src/main/java/com/example/androidobservability/BaseApplication.kt

@@ -62,7 +62,6 @@ open class BaseApplication : Application() {
             .build()
 
         LDClient.init(this@BaseApplication, ldConfig, context)
-
         telemetryInspector = observabilityPlugin.getTelemetryInspector()
     }
 }

e2e/android/app/src/main/java/com/example/androidobservability/MainActivity.kt

@@ -38,14 +38,14 @@ class MainActivity : ComponentActivity() {
                 Scaffold(modifier = Modifier.fillMaxSize()) { innerPadding ->
                     var customLogText by remember { mutableStateOf("") }
                     var customSpanText by remember { mutableStateOf("") }
+                    var customContextKey by remember { mutableStateOf("") }
 
                     Column(
                         modifier = Modifier
                             .padding(innerPadding)
                             .padding(16.dp)
                             .verticalScroll(rememberScrollState())
                     ) {
-
                         Text(
                             text = "Hello Telemetry",
                             modifier = Modifier.padding(bottom = 16.dp)
@@ -137,6 +137,23 @@ class MainActivity : ComponentActivity() {
                         ) {
                             Text("Send custom span")
                         }
+
+                        Spacer(modifier = Modifier.height(16.dp))
+
+                        OutlinedTextField(
+                            value = customContextKey,
+                            onValueChange = { customContextKey = it },
+                            label = { Text("LD context key") },
+                            modifier = Modifier.padding(8.dp)
+                        )
+                        Button(
+                            onClick = {
+                                viewModel.identifyLDContext(customContextKey)
+                            },
+                            modifier = Modifier.padding(8.dp)
+                        ) {
+                            Text("Identify LD Context")
+                        }
                     }
                 }
             }

e2e/android/app/src/main/java/com/example/androidobservability/ViewModel.kt

@@ -4,6 +4,9 @@ import androidx.lifecycle.ViewModel
 import androidx.lifecycle.viewModelScope
 import com.launchdarkly.observability.interfaces.Metric
 import com.launchdarkly.observability.sdk.LDObserve
+import com.launchdarkly.sdk.ContextKind
+import com.launchdarkly.sdk.LDContext
+import com.launchdarkly.sdk.android.LDClient
 import io.opentelemetry.api.common.AttributeKey
 import io.opentelemetry.api.common.Attributes
 import io.opentelemetry.api.logs.Severity
@@ -94,6 +97,14 @@ class ViewModel : ViewModel() {
         }
     }
 
+    fun identifyLDContext(contextKey: String = "test-context-key") {
+        val context = LDContext.builder(ContextKind.DEFAULT, contextKey)
+            .name("test-context-name")
+            .build()
+
+        LDClient.get().identify(context)
+    }
+
     private fun sendOkHttpRequest() {
         // Create HTTP client
         val client = OkHttpClient()

sdk/@launchdarkly/observability-android/lib/src/main/kotlin/com/launchdarkly/observability/client/InstrumentationManager.kt

@@ -290,6 +290,13 @@ class InstrumentationManager(
      */
     fun getTelemetryInspector(): TelemetryInspector? = telemetryInspector
 
+    /**
+     * Returns the tracer instance for creating spans.
+     *
+     * @return Tracer instance
+     */
+    fun getTracer(): Tracer = otelTracer
+
     /**
      * Flushes all pending telemetry data (traces, logs, metrics).
      * @return true if all flush operations succeeded, false otherwise

sdk/@launchdarkly/observability-android/lib/src/main/kotlin/com/launchdarkly/observability/client/ObservabilityClient.kt

@@ -87,6 +87,13 @@ class ObservabilityClient : Observe {
         return instrumentationManager.getTelemetryInspector()
     }
 
+    /**
+     * Returns the tracer instance for creating spans.
+     *
+     * @return Tracer instance
+     */
+    fun getTracer() = instrumentationManager.getTracer()
+
     override fun flush(): Boolean {
         return instrumentationManager.flush()
     }

sdk/@launchdarkly/observability-android/lib/src/main/kotlin/com/launchdarkly/observability/plugin/Observability.kt

@@ -95,7 +95,7 @@ class Observability(
 
     override fun getHooks(metadata: EnvironmentMetadata?): MutableList<Hook> {
         return Collections.singletonList(
-            EvalTracingHook(true, true)
+            TracingHook(withSpans = true, withValue = true) { observabilityClient?.getTracer() }
         )
     }
 

sdk/@launchdarkly/observability-android/lib/src/main/kotlin/com/launchdarkly/observability/plugin/EvalTracingHook.kt renamed to sdk/@launchdarkly/observability-android/lib/src/main/kotlin/com/launchdarkly/observability/plugin/TracingHook.kt

@@ -4,37 +4,47 @@ import com.launchdarkly.sdk.EvaluationDetail
 import com.launchdarkly.sdk.LDValue
 import com.launchdarkly.sdk.android.integrations.EvaluationSeriesContext
 import com.launchdarkly.sdk.android.integrations.Hook
+import com.launchdarkly.sdk.android.integrations.IdentifySeriesContext
+import com.launchdarkly.sdk.android.integrations.IdentifySeriesResult
 import io.opentelemetry.api.GlobalOpenTelemetry
 import io.opentelemetry.api.common.Attributes
 import io.opentelemetry.api.trace.Span
 import io.opentelemetry.api.trace.Tracer
 import io.opentelemetry.context.Context
+import io.opentelemetry.context.Scope
 
 /**
- * This class is a hook implementation for recording flag evaluation events
+ * This class is a hook implementation for recording flag evaluation and identify events
  * on spans.
  */
-class EvalTracingHook
+class TracingHook
+
 /**
- * Creates an [EvalTracingHook]
+ * Creates an [TracingHook]
  *
  * @param withSpans will include child spans for the various hook series when they happen
  * @param withValue will include the value of the feature flag in the recorded evaluation events
- */ internal constructor(private val withSpans: Boolean, private val withValue: Boolean) :
-    Hook(HOOK_NAME) {
-    // TODO: O11Y-374: add before/after identify support
+ * @param tracerProvider optional tracer provider function, if not provided will use GlobalOpenTelemetry
+ */
+internal constructor(
+    private val withSpans: Boolean, 
+    private val withValue: Boolean,
+    private val tracerProvider: (() -> Tracer?)
+) : Hook(HOOK_NAME) {
+
     override fun beforeEvaluation(
         seriesContext: EvaluationSeriesContext,
         seriesData: Map<String, Any>
     ): Map<String, Any> {
+        val tracer = tracerProvider.invoke() ?: GlobalOpenTelemetry.get().getTracer(INSTRUMENTATION_NAME)
         return beforeEvaluationInternal(
-            GlobalOpenTelemetry.get().getTracer(INSTRUMENTATION_NAME),
+            tracer,
             seriesContext,
             seriesData
         )
     }
 
-    fun beforeEvaluationInternal(
+    private fun beforeEvaluationInternal(
         tracer: Tracer,
         seriesContext: EvaluationSeriesContext,
         seriesData: Map<String, Any>
@@ -52,7 +62,7 @@ class EvalTracingHook
         builder.setAllAttributes(attrBuilder.build())
         val span = builder.startSpan()
         val retSeriesData: MutableMap<String, Any> = HashMap(seriesData)
-        retSeriesData[DATA_KEY_SPAN] = span
+        retSeriesData[DATA_KEY_FEATURE_FLAG_SPAN] = span
         return retSeriesData
     }
 
@@ -61,7 +71,7 @@ class EvalTracingHook
         seriesData: Map<String, Any>,
         evaluationDetail: EvaluationDetail<LDValue>
     ): Map<String, Any> {
-        val value = seriesData[DATA_KEY_SPAN]
+        val value = seriesData[DATA_KEY_FEATURE_FLAG_SPAN]
         if (value is Span) {
             value.end()
         }
@@ -85,21 +95,90 @@ class EvalTracingHook
 
         // Here we make best effort the log the event and let the library handle the "no current span" case; which at the
         // time of writing this, it does handle.
-        Span.current().addEvent(EVENT_NAME, attrBuilder.build())
+        Span.current().addEvent(FEATURE_FLAG_EVENT_NAME, attrBuilder.build())
+        return seriesData
+    }
+
+    override fun beforeIdentify(
+        seriesContext: IdentifySeriesContext,
+        seriesData: Map<String, Any>
+    ): Map<String, Any> {
+        val tracer = tracerProvider.invoke() ?: GlobalOpenTelemetry.get().getTracer(INSTRUMENTATION_NAME)
+        return beforeIdentifyInternal(
+            tracer,
+            seriesContext,
+            seriesData
+        )
+    }
+
+    private fun beforeIdentifyInternal(
+        tracer: Tracer,
+        seriesContext: IdentifySeriesContext,
+        seriesData: Map<String, Any>
+    ): Map<String, Any> {
+        if (!withSpans) {
+            return seriesData
+        }
+
+        val spanBuilder = tracer.spanBuilder(SEMCONV_IDENTIFY_SPAN_NAME)
+            .setParent(Context.current().with(Span.current()))
+        val span = spanBuilder.startSpan()
+        span.addEvent(IDENTIFY_EVENT_START)
+
+        val attrBuilder = Attributes.builder()
+        attrBuilder.put(SEMCONV_IDENTIFY_CONTEXT_ID, seriesContext.context.fullyQualifiedKey)
+        seriesContext.timeout?.let {
+            attrBuilder.put(SEMCONV_IDENTIFY_TIMEOUT, it.toLong())
+        }
+        span.setAllAttributes(attrBuilder.build())
+
+        return HashMap(seriesData).apply {
+            this[DATA_KEY_IDENTIFY_SPAN] = span
+            this[DATA_KEY_IDENTIFY_SCOPE] = span.makeCurrent()
+        }
+    }
+
+    override fun afterIdentify(
+        seriesContext: IdentifySeriesContext,
+        seriesData: Map<String, Any>,
+        result: IdentifySeriesResult
+    ): Map<String, Any> {
+        val span = seriesData[DATA_KEY_IDENTIFY_SPAN] as? Span
+        val scope = seriesData[DATA_KEY_IDENTIFY_SCOPE] as? Scope
+
+        span?.let {
+            val attrBuilder = Attributes.builder()
+            attrBuilder.put(SEMCONV_IDENTIFY_EVENT_RESULT_VALUE, result.status.name)
+
+            it.addEvent(IDENTIFY_EVENT_FINISH, attrBuilder.build())
+            it.end()
+        }
+
+        // Closes the current span scope and restores the previous span context
+        scope?.close()
+
         return seriesData
     }
 
     companion object {
         const val PROVIDER_NAME: String = "LaunchDarkly"
         const val HOOK_NAME: String = "LaunchDarkly Evaluation Tracing Hook"
         const val INSTRUMENTATION_NAME: String = "com.launchdarkly.observability"
-        const val DATA_KEY_SPAN: String = "variationSpan"
-        const val EVENT_NAME: String = "feature_flag"
+        const val DATA_KEY_FEATURE_FLAG_SPAN: String = "variationSpan"
+        const val FEATURE_FLAG_EVENT_NAME: String = "feature_flag"
         const val SEMCONV_FEATURE_FLAG_CONTEXT_ID: String = "feature_flag.context.id"
         const val SEMCONV_FEATURE_FLAG_PROVIDER_NAME: String = "feature_flag.provider.name"
         const val SEMCONV_FEATURE_FLAG_KEY: String = "feature_flag.key"
         const val SEMCONV_FEATURE_FLAG_RESULT_VALUE: String = "feature_flag.result.value"
         const val CUSTOM_FEATURE_FLAG_RESULT_VARIATION_INDEX: String = "feature_flag.result.variationIndex"
         const val CUSTOM_FEATURE_FLAG_RESULT_REASON_IN_EXPERIMENT: String = "feature_flag.result.reason.inExperiment"
+        const val SEMCONV_IDENTIFY_SPAN_NAME: String = "Identify"
+        const val SEMCONV_IDENTIFY_CONTEXT_ID: String = "identify.context.id"
+        const val SEMCONV_IDENTIFY_TIMEOUT: String = "identify.timeout"
+        const val IDENTIFY_EVENT_START: String = "start"
+        const val IDENTIFY_EVENT_FINISH: String = "finish"
+        const val SEMCONV_IDENTIFY_EVENT_RESULT_VALUE: String = "result"
+        const val DATA_KEY_IDENTIFY_SPAN: String = "identifySpan"
+        const val DATA_KEY_IDENTIFY_SCOPE: String = "identifyScope"
     }
 }