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/common/Value.java

@@ -84,6 +84,14 @@ static Value<List<KeyValue>> of(Map<String, Value<?>> value) {
     return KeyValueList.createFromMap(value);
   }
 
+  static ValueMapBuilder mapBuilder() {
+    return new ValueMapBuilderImpl();
+  }
+
+  static ValueListBuilder listBuilder() {
+    return new ValueListBuilderImpl();
+  }
+
   /** Returns the type of this {@link Value}. Useful for building switch statements. */
   ValueType getType();
 

api/all/src/main/java/io/opentelemetry/api/common/ValueListBuilder.java

@@ -0,0 +1,13 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.api.common;
+
+public interface ValueListBuilder {
+
+  ValueListBuilder add(Value<?> value);
+
+  Value<?> build();
+}

api/all/src/main/java/io/opentelemetry/api/common/ValueListBuilderImpl.java

@@ -0,0 +1,25 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.api.common;
+
+import java.util.ArrayList;
+import java.util.List;
+
+class ValueListBuilderImpl implements ValueListBuilder {
+
+  private final List<Value<?>> values = new ArrayList<>();
+
+  @Override
+  public ValueListBuilder add(Value<?> value) {
+    values.add(value);
+    return this;
+  }
+
+  @Override
+  public Value<?> build() {
+    return Value.of(values.toArray(new Value[0]));
+  }
+}

api/all/src/main/java/io/opentelemetry/api/common/ValueMapBuilder.java

@@ -0,0 +1,33 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.api.common;
+
+public interface ValueMapBuilder {
+
+  default ValueMapBuilder put(String key, String value) {
+    put(key, Value.of(value));
+    return this;
+  }
+
+  default ValueMapBuilder put(String key, long value) {
+    put(key, Value.of(value));
+    return this;
+  }
+
+  default ValueMapBuilder put(String key, double value) {
+    put(key, Value.of(value));
+    return this;
+  }
+
+  default ValueMapBuilder put(String key, boolean value) {
+    put(key, Value.of(value));
+    return this;
+  }
+
+  ValueMapBuilder put(String key, Value<?> value);
+
+  Value<?> build();
+}

api/all/src/main/java/io/opentelemetry/api/common/ValueMapBuilderImpl.java

@@ -0,0 +1,25 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.api.common;
+
+import java.util.ArrayList;
+import java.util.List;
+
+class ValueMapBuilderImpl implements ValueMapBuilder {
+
+  private final List<KeyValue> keyValues = new ArrayList<>();
+
+  @Override
+  public ValueMapBuilder put(String key, Value<?> value) {
+    keyValues.add(KeyValue.of(key, value));
+    return this;
+  }
+
+  @Override
+  public Value<?> build() {
+    return Value.of(keyValues.toArray(new KeyValue[0]));
+  }
+}

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 setBody(Value<?> body) {
+      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,53 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.api.logs;
+
+import io.opentelemetry.api.common.Attributes;
+import io.opentelemetry.api.common.Value;
+import io.opentelemetry.context.Context;
+import java.time.Instant;
+import java.util.concurrent.TimeUnit;
+
+/** The EventBuilder is used to {@link #emit()} events. */
+public interface EventBuilder {
+
+  EventBuilder setBody(Value<?> body);
+
+  /**
+   * 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,17 @@ 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.
+   */
+  default EventBuilder eventBuilder(String eventName) {
+    return DefaultLogger.getInstance().eventBuilder(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 setBody(Value<?> body) {
+      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() {}
+  }
 }