Prototype: User facing logs API (including emit event)

api/all/src/main/java/io/opentelemetry/api/OpenTelemetry.java

@@ -5,6 +5,8 @@
 
 package io.opentelemetry.api;
 
+import io.opentelemetry.api.logs.Logger;
+import io.opentelemetry.api.logs.LoggerBuilder;
 import io.opentelemetry.api.logs.LoggerProvider;
 import io.opentelemetry.api.metrics.Meter;
 import io.opentelemetry.api.metrics.MeterBuilder;
@@ -114,6 +116,18 @@ default MeterBuilder meterBuilder(String instrumentationScopeName) {
     return getMeterProvider().meterBuilder(instrumentationScopeName);
   }
 
+  default LoggerProvider getLoggerProvider() {
+    return LoggerProvider.noop();
+  }
+
+  default Logger getLogger(String instrumentationScopeName) {
+    return getLoggerProvider().get(instrumentationScopeName);
+  }
+
+  default LoggerBuilder getLoggerBuilder(String instrumentationScopeName) {
+    return getLoggerProvider().loggerBuilder(instrumentationScopeName);
+  }
+
   /**
    * Returns the {@link LoggerProvider} for bridging logs into OpenTelemetry.
    *

api/all/src/main/java/io/opentelemetry/api/logs/DefaultLogger.java

@@ -6,6 +6,7 @@
 package io.opentelemetry.api.logs;
 
 import io.opentelemetry.api.common.AttributeKey;
+import io.opentelemetry.api.common.Attributes;
 import io.opentelemetry.api.common.Value;
 import io.opentelemetry.context.Context;
 import java.time.Instant;
@@ -15,6 +16,7 @@ class DefaultLogger implements Logger {
 
   private static final Logger INSTANCE = new DefaultLogger();
   private static final LogRecordBuilder NOOP_LOG_RECORD_BUILDER = new NoopLogRecordBuilder();
+  private static final EventBuilder NOOP_EVENT_BUILDER = new NoopEventBuilder();
 
   private DefaultLogger() {}
 
@@ -27,6 +29,11 @@ public LogRecordBuilder logRecordBuilder() {
     return NOOP_LOG_RECORD_BUILDER;
   }
 
+  @Override
+  public EventBuilder eventBuilder(String eventName) {
+    return NOOP_EVENT_BUILDER;
+  }
+
   private static final class NoopLogRecordBuilder implements LogRecordBuilder {
 
     private NoopLogRecordBuilder() {}
@@ -84,4 +91,40 @@ public <T> LogRecordBuilder setAttribute(AttributeKey<T> key, T value) {
     @Override
     public void emit() {}
   }
+
+  private static class NoopEventBuilder implements EventBuilder {
+
+    @Override
+    public EventBuilder put(String key, Value<?> value) {
+      return this;
+    }
+
+    @Override
+    public EventBuilder setTimestamp(long timestamp, TimeUnit unit) {
+      return this;
+    }
+
+    @Override
+    public EventBuilder setTimestamp(Instant instant) {
+      return this;
+    }
+
+    @Override
+    public EventBuilder setContext(Context context) {
+      return this;
+    }
+
+    @Override
+    public EventBuilder setSeverity(Severity severity) {
+      return this;
+    }
+
+    @Override
+    public EventBuilder setAttributes(Attributes attributes) {
+      return this;
+    }
+
+    @Override
+    public void emit() {}
+  }
 }

api/all/src/main/java/io/opentelemetry/api/logs/EventBuilder.java

@@ -0,0 +1,152 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.api.logs;
+
+import io.opentelemetry.api.common.AttributeKey;
+import io.opentelemetry.api.common.Attributes;
+import io.opentelemetry.api.common.Value;
+import io.opentelemetry.context.Context;
+import java.time.Instant;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.concurrent.TimeUnit;
+
+import static java.util.stream.Collectors.toList;
+
+/** The EventBuilder is used to {@link #emit()} events. */
+public interface EventBuilder {
+
+  /** Put the given {@code key} and {@code value} in the payload. */
+  default EventBuilder put(String key, String value) {
+    return put(key, Value.of(value));
+  }
+
+  /** Put the given {@code key} and {@code value} in the payload. */
+  default EventBuilder put(String key, long value) {
+    return put(key, Value.of(value));
+  }
+
+  /** Put the given {@code key} and {@code value} in the payload. */
+  default EventBuilder put(String key, double value) {
+    return put(key, Value.of(value));
+  }
+
+  /** Put the given {@code key} and {@code value} in the payload. */
+  default EventBuilder put(String key, boolean value) {
+    return put(key, Value.of(value));
+  }
+
+  /** Put the given {@code key} and {@code value} in the payload. */
+  default EventBuilder put(String key, String... value) {
+    List<Value<?>> values = new ArrayList<>(value.length);
+    for (String val : value) {
+      values.add(Value.of(val));
+    }
+    return put(key, Value.of(values));
+  }
+
+  /** Put the given {@code key} and {@code value} in the payload. */
+  default EventBuilder put(String key, long... value) {
+    List<Value<?>> values = new ArrayList<>(value.length);
+    for (long val : value) {
+      values.add(Value.of(val));
+    }
+    return put(key, Value.of(values));
+  }
+
+  /** Put the given {@code key} and {@code value} in the payload. */
+  default EventBuilder put(String key, double... value) {
+    List<Value<?>> values = new ArrayList<>(value.length);
+    for (double val : value) {
+      values.add(Value.of(val));
+    }
+    return put(key, Value.of(values));
+  }
+
+  /** Put the given {@code key} and {@code value} in the payload. */
+  default EventBuilder put(String key, boolean... value) {
+    List<Value<?>> values = new ArrayList<>(value.length);
+    for (boolean val : value) {
+      values.add(Value.of(val));
+    }
+    return put(key, Value.of(values));
+  }
+
+  /**
+   * Put the given key and value in the payload.
+   *
+   * <p>NOTE: The key value pair is NOT added to the event attributes. Setting event attributes is
+   * less common than adding entries to the event payload. Use {@link #setAttributes(Attributes)} if
+   * intending the data to be set in attributes instead of the payload.
+   */
+  @SuppressWarnings("unchecked")
+  default <T> EventBuilder put(AttributeKey<T> key, T value) {
+    switch (key.getType()) {
+      case STRING:
+        return put(key.getKey(), (String) value);
+      case BOOLEAN:
+        return put(key.getKey(), (boolean) value);
+      case LONG:
+        return put(key.getKey(), (long) value);
+      case DOUBLE:
+        return put(key.getKey(), (double) value);
+      case STRING_ARRAY:
+        return put(
+            key.getKey(),
+            Value.of(((List<String>) value).stream().map(Value::of).collect(toList())));
+      case BOOLEAN_ARRAY:
+        return put(
+            key.getKey(),
+            Value.of(((List<Boolean>) value).stream().map(Value::of).collect(toList())));
+      case LONG_ARRAY:
+        return put(
+            key.getKey(), Value.of(((List<Long>) value).stream().map(Value::of).collect(toList())));
+      case DOUBLE_ARRAY:
+        return put(
+            key.getKey(),
+            Value.of(((List<Double>) value).stream().map(Value::of).collect(toList())));
+    }
+    return this;
+  }
+
+  /** Put the given {@code key} and {@code value} in the payload. */
+  EventBuilder put(String key, Value<?> value);
+
+  /**
+   * Set the epoch {@code timestamp}, using the timestamp and unit.
+   *
+   * <p>The {@code timestamp} is the time at which the event occurred. If unset, it will be set to
+   * the current time when {@link #emit()} is called.
+   */
+  EventBuilder setTimestamp(long timestamp, TimeUnit unit);
+
+  /**
+   * Set the epoch {@code timestamp}, using the instant.
+   *
+   * <p>The {@code timestamp} is the time at which the event occurred. If unset, it will be set to
+   * the current time when {@link #emit()} is called.
+   */
+  EventBuilder setTimestamp(Instant instant);
+
+  /** Set the context. */
+  EventBuilder setContext(Context context);
+
+  /** Set the severity. */
+  EventBuilder setSeverity(Severity severity);
+
+  /**
+   * Set the attributes.
+   *
+   * <p>Event {@link Attributes} provide additional details about the
+   * Event which are not part of the well-defined {@link Value} payload. Setting event attributes is
+   * less common than adding entries to the event payload. Most users will want to call one of the
+   * {@code #put(String, ?)} methods instead.
+   */
+  EventBuilder setAttributes(Attributes attributes);
+
+  /** Emit an event. */
+  void emit();
+}

api/all/src/main/java/io/opentelemetry/api/logs/Logger.java

@@ -33,4 +33,15 @@ public interface Logger {
    * LogRecordBuilder#emit()}.
    */
   LogRecordBuilder logRecordBuilder();
+
+  /**
+   * Return a {@link LogRecordBuilder} to emit an event.
+   *
+   * @param eventName the event name, which identifies the class or type of event. Event with the
+   *     same name are structurally similar to one another. Event names are subject to the same
+   *     naming rules as attribute names. Notably, they are namespaced to avoid collisions. See <a
+   *     href="https://opentelemetry.io/docs/specs/semconv/general/events/">event.name semantic
+   *     conventions</a> for more details.
+   */
+  EventBuilder eventBuilder(String eventName);
 }

api/incubator/src/main/java/io/opentelemetry/api/incubator/logs/ExtendedDefaultLogger.java

@@ -6,7 +6,9 @@
 package io.opentelemetry.api.incubator.logs;
 
 import io.opentelemetry.api.common.AttributeKey;
+import io.opentelemetry.api.common.Attributes;
 import io.opentelemetry.api.common.Value;
+import io.opentelemetry.api.logs.EventBuilder;
 import io.opentelemetry.api.logs.LogRecordBuilder;
 import io.opentelemetry.api.logs.Logger;
 import io.opentelemetry.api.logs.Severity;
@@ -18,6 +20,7 @@ class ExtendedDefaultLogger implements ExtendedLogger {
 
   private static final Logger INSTANCE = new ExtendedDefaultLogger();
   private static final LogRecordBuilder NOOP_LOG_RECORD_BUILDER = new NoopLogRecordBuilder();
+  private static final EventBuilder NOOP_EVENT_BUILDER = new NoopEventBuilder();
 
   private ExtendedDefaultLogger() {}
 
@@ -30,6 +33,11 @@ public LogRecordBuilder logRecordBuilder() {
     return NOOP_LOG_RECORD_BUILDER;
   }
 
+  @Override
+  public EventBuilder eventBuilder(String eventName) {
+    return NOOP_EVENT_BUILDER;
+  }
+
   private static final class NoopLogRecordBuilder implements ExtendedLogRecordBuilder {
 
     private NoopLogRecordBuilder() {}
@@ -87,4 +95,40 @@ public <T> LogRecordBuilder setAttribute(AttributeKey<T> key, T value) {
     @Override
     public void emit() {}
   }
+
+  private static class NoopEventBuilder implements EventBuilder {
+
+    @Override
+    public EventBuilder put(String key, Value<?> value) {
+      return this;
+    }
+
+    @Override
+    public EventBuilder setTimestamp(long timestamp, TimeUnit unit) {
+      return this;
+    }
+
+    @Override
+    public EventBuilder setTimestamp(Instant instant) {
+      return this;
+    }
+
+    @Override
+    public EventBuilder setContext(Context context) {
+      return this;
+    }
+
+    @Override
+    public EventBuilder setSeverity(Severity severity) {
+      return this;
+    }
+
+    @Override
+    public EventBuilder setAttributes(Attributes attributes) {
+      return this;
+    }
+
+    @Override
+    public void emit() {}
+  }
 }