Extend Logs API to allow passing in attributes (#4402)

* Extend Logs API to allow passing in attributes

* update (#4409)

* Improve Log Attributes API (#4416)

* Improve logger attributes API

* Review feedback

* changelog

---------

Co-authored-by: Lorenzo Cian <lorenzo.cian@sentry.io>

Author: adinauer

CHANGELOG.md

@@ -7,6 +7,19 @@
 - Add debug mode for Session Replay masking ([#4357](https://github.com/getsentry/sentry-java/pull/4357))
     - Use `Sentry.replay().enableDebugMaskingOverlay()` to overlay the screen with the Session Replay masks.
     - The masks will be invalidated at most once per `frameRate` (default 1 fps).
+- Extend Logs API to allow passing in `attributes` ([#4402](https://github.com/getsentry/sentry-java/pull/4402))
+  - `Sentry.logger.log` now takes a `SentryLogParameters`
+  - Use `SentryLogParameters.create(SentryAttributes.of(...))` to pass attributes
+    - Attribute values may be of type `string`, `boolean`, `integer` or `double`.
+    - Other types will be converted to `string`. Currently we simply call `toString()` but we might offer more in the future.
+    - You may manually flatten complex types into multiple separate attributes of simple types.
+      - e.g. intead of `SentryAttribute.named("point", Point(10, 20))` you may store it as `SentryAttribute.integerAttribute("point.x", point.x)` and `SentryAttribute.integerAttribute("point.y", point.y)`
+    - `SentryAttribute.named()` will automatically infer the type or fall back to `string`.
+    - `SentryAttribute.booleanAttribute()` takes a `Boolean` value
+    - `SentryAttribute.integerAttribute()` takes a `Integer` value
+    - `SentryAttribute.doubleAttribute()` takes a `Double` value
+    - `SentryAttribute.stringAttribute()` takes a `String` value
+  - We opted for handling parameters via `SentryLogParameters` to avoid creating tons of overloads that are ambiguous.
 
 ## 8.12.0
 

sentry/api/sentry.api

@@ -2668,6 +2668,34 @@ public final class io/sentry/SentryAppStartProfilingOptions$JsonKeys {
 	public fun <init> ()V
 }
 
+public final class io/sentry/SentryAttribute {
+	public static fun booleanAttribute (Ljava/lang/String;Ljava/lang/Boolean;)Lio/sentry/SentryAttribute;
+	public static fun doubleAttribute (Ljava/lang/String;Ljava/lang/Double;)Lio/sentry/SentryAttribute;
+	public fun getName ()Ljava/lang/String;
+	public fun getType ()Lio/sentry/SentryAttributeType;
+	public fun getValue ()Ljava/lang/Object;
+	public static fun integerAttribute (Ljava/lang/String;Ljava/lang/Integer;)Lio/sentry/SentryAttribute;
+	public static fun named (Ljava/lang/String;Ljava/lang/Object;)Lio/sentry/SentryAttribute;
+	public static fun stringAttribute (Ljava/lang/String;Ljava/lang/String;)Lio/sentry/SentryAttribute;
+}
+
+public final class io/sentry/SentryAttributeType : java/lang/Enum {
+	public static final field BOOLEAN Lio/sentry/SentryAttributeType;
+	public static final field DOUBLE Lio/sentry/SentryAttributeType;
+	public static final field INTEGER Lio/sentry/SentryAttributeType;
+	public static final field STRING Lio/sentry/SentryAttributeType;
+	public fun apiName ()Ljava/lang/String;
+	public static fun valueOf (Ljava/lang/String;)Lio/sentry/SentryAttributeType;
+	public static fun values ()[Lio/sentry/SentryAttributeType;
+}
+
+public final class io/sentry/SentryAttributes {
+	public fun add (Lio/sentry/SentryAttribute;)V
+	public static fun fromMap (Ljava/util/Map;)Lio/sentry/SentryAttributes;
+	public fun getAttributes ()Ljava/util/Map;
+	public static fun of ([Lio/sentry/SentryAttribute;)Lio/sentry/SentryAttributes;
+}
+
 public final class io/sentry/SentryAutoDateProvider : io/sentry/SentryDateProvider {
 	public fun <init> ()V
 	public fun now ()Lio/sentry/SentryDate;
@@ -3087,6 +3115,7 @@ public final class io/sentry/SentryLogEvent$JsonKeys {
 }
 
 public final class io/sentry/SentryLogEventAttributeValue : io/sentry/JsonSerializable, io/sentry/JsonUnknown {
+	public fun <init> (Lio/sentry/SentryAttributeType;Ljava/lang/Object;)V
 	public fun <init> (Ljava/lang/String;Ljava/lang/Object;)V
 	public fun getType ()Ljava/lang/String;
 	public fun getUnknown ()Ljava/util/Map;
@@ -4721,6 +4750,7 @@ public abstract interface class io/sentry/logger/ILoggerApi {
 	public abstract fun fatal (Ljava/lang/String;[Ljava/lang/Object;)V
 	public abstract fun info (Ljava/lang/String;[Ljava/lang/Object;)V
 	public abstract fun log (Lio/sentry/SentryLogLevel;Lio/sentry/SentryDate;Ljava/lang/String;[Ljava/lang/Object;)V
+	public abstract fun log (Lio/sentry/SentryLogLevel;Lio/sentry/logger/SentryLogParameters;Ljava/lang/String;[Ljava/lang/Object;)V
 	public abstract fun log (Lio/sentry/SentryLogLevel;Ljava/lang/String;[Ljava/lang/Object;)V
 	public abstract fun trace (Ljava/lang/String;[Ljava/lang/Object;)V
 	public abstract fun warn (Ljava/lang/String;[Ljava/lang/Object;)V
@@ -4738,6 +4768,7 @@ public final class io/sentry/logger/LoggerApi : io/sentry/logger/ILoggerApi {
 	public fun fatal (Ljava/lang/String;[Ljava/lang/Object;)V
 	public fun info (Ljava/lang/String;[Ljava/lang/Object;)V
 	public fun log (Lio/sentry/SentryLogLevel;Lio/sentry/SentryDate;Ljava/lang/String;[Ljava/lang/Object;)V
+	public fun log (Lio/sentry/SentryLogLevel;Lio/sentry/logger/SentryLogParameters;Ljava/lang/String;[Ljava/lang/Object;)V
 	public fun log (Lio/sentry/SentryLogLevel;Ljava/lang/String;[Ljava/lang/Object;)V
 	public fun trace (Ljava/lang/String;[Ljava/lang/Object;)V
 	public fun warn (Ljava/lang/String;[Ljava/lang/Object;)V
@@ -4758,6 +4789,7 @@ public final class io/sentry/logger/NoOpLoggerApi : io/sentry/logger/ILoggerApi
 	public static fun getInstance ()Lio/sentry/logger/NoOpLoggerApi;
 	public fun info (Ljava/lang/String;[Ljava/lang/Object;)V
 	public fun log (Lio/sentry/SentryLogLevel;Lio/sentry/SentryDate;Ljava/lang/String;[Ljava/lang/Object;)V
+	public fun log (Lio/sentry/SentryLogLevel;Lio/sentry/logger/SentryLogParameters;Ljava/lang/String;[Ljava/lang/Object;)V
 	public fun log (Lio/sentry/SentryLogLevel;Ljava/lang/String;[Ljava/lang/Object;)V
 	public fun trace (Ljava/lang/String;[Ljava/lang/Object;)V
 	public fun warn (Ljava/lang/String;[Ljava/lang/Object;)V
@@ -4769,6 +4801,16 @@ public final class io/sentry/logger/NoOpLoggerBatchProcessor : io/sentry/logger/
 	public static fun getInstance ()Lio/sentry/logger/NoOpLoggerBatchProcessor;
 }
 
+public final class io/sentry/logger/SentryLogParameters {
+	public fun <init> ()V
+	public static fun create (Lio/sentry/SentryAttributes;)Lio/sentry/logger/SentryLogParameters;
+	public static fun create (Lio/sentry/SentryDate;Lio/sentry/SentryAttributes;)Lio/sentry/logger/SentryLogParameters;
+	public fun getAttributes ()Lio/sentry/SentryAttributes;
+	public fun getTimestamp ()Lio/sentry/SentryDate;
+	public fun setAttributes (Lio/sentry/SentryAttributes;)V
+	public fun setTimestamp (Lio/sentry/SentryDate;)V
+}
+
 public final class io/sentry/opentelemetry/OpenTelemetryUtil {
 	public fun <init> ()V
 	public static fun applyIgnoredSpanOrigins (Lio/sentry/SentryOptions;)V

sentry/src/main/java/io/sentry/SentryAttribute.java

@@ -0,0 +1,57 @@
+package io.sentry;
+
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
+
+public final class SentryAttribute {
+
+  private final @NotNull String name;
+  private final @Nullable SentryAttributeType type;
+  private final @Nullable Object value;
+
+  private SentryAttribute(
+      final @NotNull String name,
+      final @Nullable SentryAttributeType type,
+      final @Nullable Object value) {
+    this.name = name;
+    this.type = type;
+    this.value = value;
+  }
+
+  public @NotNull String getName() {
+    return name;
+  }
+
+  public @Nullable SentryAttributeType getType() {
+    return type;
+  }
+
+  public @Nullable Object getValue() {
+    return value;
+  }
+
+  public static @NotNull SentryAttribute named(
+      final @NotNull String name, final @Nullable Object value) {
+    return new SentryAttribute(name, null, value);
+  }
+
+  public static @NotNull SentryAttribute booleanAttribute(
+      final @NotNull String name, final @Nullable Boolean value) {
+    return new SentryAttribute(name, SentryAttributeType.BOOLEAN, value);
+  }
+
+  public static @NotNull SentryAttribute integerAttribute(
+      final @NotNull String name, final @Nullable Integer value) {
+    return new SentryAttribute(name, SentryAttributeType.INTEGER, value);
+  }
+
+  public static @NotNull SentryAttribute doubleAttribute(
+      final @NotNull String name, final @Nullable Double value) {
+    return new SentryAttribute(name, SentryAttributeType.DOUBLE, value);
+  }
+
+  public static @NotNull SentryAttribute stringAttribute(
+      final @NotNull String name, final @Nullable String value) {
+    return new SentryAttribute(name, SentryAttributeType.STRING, value);
+  }
+}

sentry/src/main/java/io/sentry/SentryAttributeType.java

@@ -0,0 +1,15 @@
+package io.sentry;
+
+import java.util.Locale;
+import org.jetbrains.annotations.NotNull;
+
+public enum SentryAttributeType {
+  STRING,
+  BOOLEAN,
+  INTEGER,
+  DOUBLE;
+
+  public @NotNull String apiName() {
+    return name().toLowerCase(Locale.ROOT);
+  }
+}

sentry/src/main/java/io/sentry/SentryAttributes.java

@@ -0,0 +1,54 @@
+package io.sentry;
+
+import java.util.Map;
+import java.util.concurrent.ConcurrentHashMap;
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
+
+public final class SentryAttributes {
+
+  private final @NotNull Map<String, SentryAttribute> attributes;
+
+  private SentryAttributes(final @NotNull Map<String, SentryAttribute> attributes) {
+    this.attributes = attributes;
+  }
+
+  public void add(final @Nullable SentryAttribute attribute) {
+    if (attribute == null) {
+      return;
+    }
+    attributes.put(attribute.getName(), attribute);
+  }
+
+  public @NotNull Map<String, SentryAttribute> getAttributes() {
+    return attributes;
+  }
+
+  public static @NotNull SentryAttributes of(final @Nullable SentryAttribute... attributes) {
+    if (attributes == null) {
+      return new SentryAttributes(new ConcurrentHashMap<>());
+    }
+    final @NotNull SentryAttributes sentryAttributes =
+        new SentryAttributes(new ConcurrentHashMap<>(attributes.length));
+    for (SentryAttribute attribute : attributes) {
+      sentryAttributes.add(attribute);
+    }
+    return sentryAttributes;
+  }
+
+  public static @NotNull SentryAttributes fromMap(final @Nullable Map<String, Object> attributes) {
+    if (attributes == null) {
+      return new SentryAttributes(new ConcurrentHashMap<>());
+    }
+    final @NotNull SentryAttributes sentryAttributes =
+        new SentryAttributes(new ConcurrentHashMap<>(attributes.size()));
+    for (Map.Entry<String, Object> attribute : attributes.entrySet()) {
+      final @Nullable String key = attribute.getKey();
+      if (key != null) {
+        sentryAttributes.add(SentryAttribute.named(key, attribute.getValue()));
+      }
+    }
+
+    return sentryAttributes;
+  }
+}

sentry/src/main/java/io/sentry/SentryLogEventAttributeValue.java

@@ -15,6 +15,16 @@ public final class SentryLogEventAttributeValue implements JsonUnknown, JsonSeri
 
   public SentryLogEventAttributeValue(final @NotNull String type, final @Nullable Object value) {
     this.type = type;
+    if (value != null && type.equals("string")) {
+      this.value = value.toString();
+    } else {
+      this.value = value;
+    }
+  }
+
+  public SentryLogEventAttributeValue(
+      final @NotNull SentryAttributeType type, final @Nullable Object value) {
+    this.type = type.apiName();
     this.value = value;
   }
 

sentry/src/main/java/io/sentry/logger/ILoggerApi.java

@@ -28,4 +28,10 @@ void log(
       @Nullable SentryDate timestamp,
       @Nullable String message,
       @Nullable Object... args);
+
+  void log(
+      @NotNull SentryLogLevel level,
+      @NotNull SentryLogParameters params,
+      @Nullable String message,
+      @Nullable Object... args);
 }

sentry/src/main/java/io/sentry/logger/LoggerApi.java

@@ -5,6 +5,9 @@
 import io.sentry.ISpan;
 import io.sentry.PropagationContext;
 import io.sentry.Scopes;
+import io.sentry.SentryAttribute;
+import io.sentry.SentryAttributeType;
+import io.sentry.SentryAttributes;
 import io.sentry.SentryDate;
 import io.sentry.SentryLevel;
 import io.sentry.SentryLogEvent;
@@ -65,7 +68,7 @@ public void log(
       final @NotNull SentryLogLevel level,
       final @Nullable String message,
       final @Nullable Object... args) {
-    log(level, null, message, args);
+    captureLog(level, SentryLogParameters.create(null, null), message, args);
   }
 
   @Override
@@ -74,13 +77,22 @@ public void log(
       final @Nullable SentryDate timestamp,
       final @Nullable String message,
       final @Nullable Object... args) {
-    captureLog(level, timestamp, message, args);
+    captureLog(level, SentryLogParameters.create(timestamp, null), message, args);
+  }
+
+  @Override
+  public void log(
+      final @NotNull SentryLogLevel level,
+      final @NotNull SentryLogParameters params,
+      final @Nullable String message,
+      final @Nullable Object... args) {
+    captureLog(level, params, message, args);
   }
 
   @SuppressWarnings("AnnotateFormatMethod")
   private void captureLog(
       final @NotNull SentryLogLevel level,
-      final @Nullable SentryDate timestamp,
+      final @NotNull SentryLogParameters params,
       final @Nullable String message,
       final @Nullable Object... args) {
     final @NotNull SentryOptions options = scopes.getOptions();
@@ -103,6 +115,7 @@ private void captureLog(
         return;
       }
 
+      final @Nullable SentryDate timestamp = params.getTimestamp();
       final @NotNull SentryDate timestampToUse =
           timestamp == null ? options.getDateProvider().now() : timestamp;
       final @NotNull String messageToUse = maybeFormatMessage(message, args);
@@ -119,7 +132,7 @@ private void captureLog(
           span == null ? propagationContext.getSpanId() : span.getSpanContext().getSpanId();
       final SentryLogEvent logEvent =
           new SentryLogEvent(traceId, timestampToUse, messageToUse, level);
-      logEvent.setAttributes(createAttributes(message, spanId, args));
+      logEvent.setAttributes(createAttributes(params.getAttributes(), message, spanId, args));
       logEvent.setSeverityNumber(level.getSeverityNumber());
 
       scopes.getClient().captureLog(logEvent, combinedScope);
@@ -146,12 +159,25 @@ private void captureLog(
   }
 
   private @NotNull HashMap<String, SentryLogEventAttributeValue> createAttributes(
-      final @NotNull String message, final @NotNull SpanId spanId, final @Nullable Object... args) {
+      final @Nullable SentryAttributes incomingAttributes,
+      final @NotNull String message,
+      final @NotNull SpanId spanId,
+      final @Nullable Object... args) {
     final @NotNull HashMap<String, SentryLogEventAttributeValue> attributes = new HashMap<>();
+
+    if (incomingAttributes != null) {
+      for (SentryAttribute attribute : incomingAttributes.getAttributes().values()) {
+        final @Nullable Object value = attribute.getValue();
+        final @NotNull SentryAttributeType type =
+            attribute.getType() == null ? getType(value) : attribute.getType();
+        attributes.put(attribute.getName(), new SentryLogEventAttributeValue(type, value));
+      }
+    }
+
     if (args != null) {
       int i = 0;
       for (Object arg : args) {
-        final @NotNull String type = getType(arg);
+        final @NotNull SentryAttributeType type = getType(arg);
         attributes.put(
             "sentry.message.parameter." + i, new SentryLogEventAttributeValue(type, arg));
         i++;
@@ -205,16 +231,16 @@ private void setServerName(
     }
   }
 
-  private @NotNull String getType(final @Nullable Object arg) {
+  private @NotNull SentryAttributeType getType(final @Nullable Object arg) {
     if (arg instanceof Boolean) {
-      return "boolean";
+      return SentryAttributeType.BOOLEAN;
     }
     if (arg instanceof Integer) {
-      return "integer";
+      return SentryAttributeType.INTEGER;
     }
     if (arg instanceof Number) {
-      return "double";
+      return SentryAttributeType.DOUBLE;
     }
-    return "string";
+    return SentryAttributeType.STRING;
   }
 }

sentry/src/main/java/io/sentry/logger/NoOpLoggerApi.java

@@ -61,4 +61,13 @@ public void log(
       @Nullable Object... args) {
     // do nothing
   }
+
+  @Override
+  public void log(
+      @NotNull SentryLogLevel level,
+      @NotNull SentryLogParameters params,
+      @Nullable String message,
+      @Nullable Object... args) {
+    // do nothing
+  }
 }