Merge pull request #197 from DataDog/mconstantin/rumm-331/androidtrac…

…er-helper-methods-for-errors

RUMM-331 Tracer - add helper methods for logging an error

dd-sdk-android/apiSurface

@@ -68,5 +68,7 @@ class com.datadog.android.tracing.AndroidTracer : datadog.opentracing.DDTracer
     fun setServiceName(String): Builder
     fun setPartialFlushThreshold(Int): Builder
   companion object
+    fun logThrowable(io.opentracing.Span, Throwable)
+    fun logErrorMessage(io.opentracing.Span, String)
 class com.datadog.android.tracing.TracingInterceptor : okhttp3.Interceptor
   override fun intercept(okhttp3.Interceptor, Chain): okhttp3.Response

dd-sdk-android/src/main/kotlin/com/datadog/android/tracing/AndroidTracer.kt

@@ -15,6 +15,8 @@ import datadog.opentracing.LogHandler
 import datadog.opentracing.propagation.ExtractedContext
 import datadog.trace.api.Config
 import datadog.trace.api.sampling.PrioritySampling
+import io.opentracing.Span
+import io.opentracing.log.Fields
 import java.math.BigInteger
 import java.security.SecureRandom
 import java.util.Properties
@@ -137,5 +139,30 @@ class AndroidTracer internal constructor(
         internal const val TRACE_LOGGER_NAME = "trace"
 
         internal const val TRACE_ID_BIT_SIZE = 63
+
+        /**
+         * Helper method to attach a Throwable to a specific Span.
+         * The Throwable information (class name, message and stacktrace) will be added to the
+         * provided Span as standard Error Tags.
+         * @param span the active Span
+         * @param throwable the Throwable you wan to log
+         */
+        @JvmStatic
+        fun logThrowable(span: Span, throwable: Throwable) {
+            val fieldsMap = mapOf(Fields.ERROR_OBJECT to throwable)
+            span.log(fieldsMap)
+        }
+
+        /**
+         * Helper method to attach an error message to a specific Span.
+         * The error message will be added to the provided Span as a standard Error Tag.
+         * @param span the active Span
+         * @param message the error message you want to attach
+         */
+        @JvmStatic
+        fun logErrorMessage(span: Span, message: String) {
+            val fieldsMap = mapOf(Fields.MESSAGE to message)
+            span.log(fieldsMap)
+        }
     }
 }

dd-sdk-android/src/test/kotlin/com/datadog/android/tracing/internal/AndroidTracerTest.kt

@@ -8,7 +8,10 @@ import com.datadog.android.utils.mockContext
 import com.datadog.tools.unit.getStaticValue
 import com.datadog.tools.unit.invokeMethod
 import com.datadog.tools.unit.setFieldValue
+import com.nhaarman.mockitokotlin2.argumentCaptor
 import com.nhaarman.mockitokotlin2.inOrder
+import com.nhaarman.mockitokotlin2.mock
+import com.nhaarman.mockitokotlin2.verify
 import datadog.opentracing.DDSpan
 import datadog.opentracing.LogHandler
 import datadog.opentracing.scopemanager.ContextualScopeManager
@@ -19,6 +22,8 @@ import fr.xgouchet.elmyr.annotation.StringForgery
 import fr.xgouchet.elmyr.annotation.StringForgeryType
 import fr.xgouchet.elmyr.junit5.ForgeConfiguration
 import fr.xgouchet.elmyr.junit5.ForgeExtension
+import io.opentracing.Span
+import io.opentracing.log.Fields
 import io.opentracing.util.GlobalTracer
 import java.math.BigInteger
 import java.util.Random
@@ -46,6 +51,7 @@ internal class AndroidTracerTest {
     lateinit var mockAppContext: Application
     lateinit var fakeToken: String
     lateinit var fakeServiceName: String
+
     @Mock
     lateinit var mockLogsHandler: LogHandler
 
@@ -74,6 +80,8 @@ internal class AndroidTracerTest {
         tlsScope.remove()
     }
 
+    // region Tracer
+
     @Test
     fun `buildSpan will inject a parent context`(
         @StringForgery(StringForgeryType.ALPHA_NUMERICAL) operationName: String,
@@ -167,4 +175,48 @@ internal class AndroidTracerTest {
         inOrder.verify(mockLogsHandler).log(logMaps, span)
         inOrder.verify(mockLogsHandler).log(logTimestamp, logMaps, span)
     }
+
+    // endregion
+
+    // region Helpers
+
+    @Test
+    fun `it will delegate to the right fields when logging a throwable for a span`(forge: Forge) {
+        // given
+        val aThrowable: Throwable = forge.getForgery()
+        val mockSpan: Span = mock()
+
+        // when
+        AndroidTracer.logThrowable(mockSpan, aThrowable)
+
+        // then
+        argumentCaptor<Map<String, Any>>().apply {
+            verify(mockSpan).log(capture())
+            assertThat(firstValue)
+                .containsEntry(Fields.ERROR_OBJECT, aThrowable)
+                .containsOnlyKeys(Fields.ERROR_OBJECT)
+        }
+    }
+
+    @Test
+    fun `it will delegate to the right fields when logging an error message for a span`(
+        forge: Forge
+    ) {
+        // given
+        val anErrorMessage: String = forge.aString()
+        val mockSpan: Span = mock()
+
+        // when
+        AndroidTracer.logErrorMessage(mockSpan, anErrorMessage)
+
+        // then
+        argumentCaptor<Map<String, Any>>().apply {
+            verify(mockSpan).log(capture())
+            assertThat(firstValue)
+                .containsEntry(Fields.MESSAGE, anErrorMessage)
+                .containsOnlyKeys(Fields.MESSAGE)
+        }
+    }
+
+    // endregion
 }

docs/trace_collection.md

@@ -92,6 +92,24 @@ class SampleApplication : Application() {
     ```kotlin
     span.setTag("http.url", url)
     ```
+7. (Optional) Attach an error information to a Span:
+
+    If you want to mark a span as having an error, you can do so by logging it using the official OpenTracing tags
+
+    ```kotlin
+    span.log(mapOf(Fields.ERROR_OBJECT to throwable))
+    ```
+    ```kotlin
+    span.log(mapOf(Fields.MESSAGE to errorMessage))
+    ```
+    You can also use one of the following helper method in AndroidTracer
+
+    ```kotlin
+    AndroidTracer.logThrowable(span, throwable)
+    ```
+    ```kotlin
+    AndroidTracer.logErrorMessage(span, message)
+    ```
 
 ## Integrations