Add timestamp (wall time) information on the Event (#4034)

Co-authored-by: Jonatan Ivanov <jonatan.ivanov@gmail.com>

Closes gh-4032

micrometer-observation-test/src/main/java/io/micrometer/observation/tck/ObservationRegistryCompatibilityKit.java

@@ -18,10 +18,10 @@
 import io.micrometer.common.KeyValue;
 import io.micrometer.common.KeyValues;
 import io.micrometer.common.lang.Nullable;
+import io.micrometer.observation.GlobalObservationConvention;
 import io.micrometer.observation.Observation;
 import io.micrometer.observation.ObservationHandler;
 import io.micrometer.observation.ObservationRegistry;
-import io.micrometer.observation.GlobalObservationConvention;
 import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.DisplayName;
 import org.junit.jupiter.api.Test;
@@ -85,7 +85,12 @@ void observeWithHandlers() {
 
             Observation.Event event = Observation.Event.of("testEvent", "event for testing");
             observation.event(event);
+            Observation.Event event2 = Observation.Event.of("testEvent", "event for testing",
+                    System.currentTimeMillis());
+            observation.event(event2);
+
             inOrder.verify(handler).onEvent(same(event), isA(Observation.Context.class));
+            inOrder.verify(handler).onEvent(same(event2), isA(Observation.Context.class));
 
             Throwable exception = new IOException("simulated");
             observation.error(exception);

micrometer-observation/src/main/java/io/micrometer/observation/Observation.java

@@ -1271,22 +1271,19 @@ interface Event {
          * @return event
          */
         static Event of(String name, String contextualName) {
-            return new Event() {
-                @Override
-                public String getName() {
-                    return name;
-                }
-
-                @Override
-                public String getContextualName() {
-                    return contextualName;
-                }
+            return new SimpleEvent(name, contextualName);
+        }
 
-                @Override
-                public String toString() {
-                    return "event.name='" + getName() + "', event.contextualName='" + getContextualName() + '\'';
-                }
-            };
+        /**
+         * Creates an {@link Event} for the given names and timestamp (wall time).
+         * @param name The name of the event (should have low cardinality).
+         * @param contextualName The contextual name of the event (can have high
+         * cardinality).
+         * @param wallTime Wall time in milliseconds since the epoch
+         * @return event
+         */
+        static Event of(String name, String contextualName, long wallTime) {
+            return new SimpleEvent(name, contextualName, wallTime);
         }
 
         /**
@@ -1304,6 +1301,16 @@ static Event of(String name) {
          */
         String getName();
 
+        /**
+         * Wall time in milliseconds since the epoch. Typically equivalent to
+         * System.currentTimeMillis. Should not be used to determine durations. Used for
+         * timestamping events that happened during Observations.
+         * @return Wall time in milliseconds since the epoch
+         */
+        default long getWallTime() {
+            return 0;
+        }
+
         /**
          * Returns the contextual name of the event. You can use {@code %s} to represent
          * dynamic entries that should be resolved at runtime via

micrometer-observation/src/main/java/io/micrometer/observation/SimpleEvent.java

@@ -0,0 +1,72 @@
+/*
+ * Copyright 2023 VMware, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package io.micrometer.observation;
+
+import io.micrometer.observation.Observation.Event;
+
+/**
+ * Default implementation of {@link Event}.
+ *
+ * @author Jonatan Ivanov
+ * @author Tommy Ludwig
+ * @author Marcin Grzejszczak
+ * @since 1.12.0
+ */
+class SimpleEvent implements Event {
+
+    private final String name;
+
+    private final String contextualName;
+
+    private final long wallTime;
+
+    SimpleEvent(String name, String contextualName) {
+        this(name, contextualName, System.currentTimeMillis());
+    }
+
+    /**
+     * @param name The name of the event (should have low cardinality).
+     * @param contextualName The contextual name of the event (can have high cardinality).
+     * @param wallTime Wall time in milliseconds since the epoch
+     */
+    SimpleEvent(String name, String contextualName, long wallTime) {
+        this.name = name;
+        this.contextualName = contextualName;
+        this.wallTime = wallTime;
+    }
+
+    @Override
+    public String getName() {
+        return name;
+    }
+
+    @Override
+    public String getContextualName() {
+        return contextualName;
+    }
+
+    @Override
+    public long getWallTime() {
+        return this.wallTime;
+    }
+
+    @Override
+    public String toString() {
+        return "event.name='" + getName() + "', event.contextualName='" + getContextualName() + "', event.wallTime="
+                + getWallTime();
+    }
+
+}