Add MessageEvent and deprecate NetworkEvent. (closes #858) (#894)

24 files changed, 698 insertions, 54 deletions

diff --git a/api/src/main/java/io/opencensus/internal/BaseMessageEventUtil.java b/api/src/main/java/io/opencensus/internal/BaseMessageEventUtil.java
new file mode 100644
index 00000000..56ec3301
--- /dev/null
+++ b/api/src/main/java/io/opencensus/internal/BaseMessageEventUtil.java
@@ -0,0 +1,80 @@
+/*
+ * Copyright 2018, OpenCensus Authors
+ *
+ * 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
+ *
+ *     http://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.opencensus.internal;
+
+import static com.google.common.base.Preconditions.checkNotNull;
+
+import io.opencensus.trace.MessageEvent;
+
+/**
+ * Helper class to convert/cast between for {@link MessageEvent} and {@link NetworkEvent}.
+ *
+ * @since 0.12
+ */
+@SuppressWarnings("deprecation")
+public final class BaseMessageEventUtil {
+  /**
+   * Cast or convert a {@link io.opencensus.trace.BaseMessageEvent} to {@link MessageEvent}.
+   *
+   * <p>Warning: if the input is a {@code io.opencensus.trace.NetworkEvent} and contains {@code
+   * kernelTimestamp} information, this information will be dropped.
+   *
+   * @param event the {@code BaseMessageEvent} that is being cast or converted.
+   * @return a {@code MessageEvent} representation of the input.
+   */
+  public static MessageEvent asMessageEvent(io.opencensus.trace.BaseMessageEvent event) {
+    checkNotNull(event);
+    if (event instanceof MessageEvent) {
+      return (MessageEvent) event;
+    }
+    io.opencensus.trace.NetworkEvent networkEvent = (io.opencensus.trace.NetworkEvent) event;
+    MessageEvent.Type type =
+        (networkEvent.getType() == io.opencensus.trace.NetworkEvent.Type.RECV)
+            ? MessageEvent.Type.RECEIVED
+            : MessageEvent.Type.SENT;
+    return MessageEvent.builder(type, networkEvent.getMessageId())
+        .setUncompressedMessageSize(networkEvent.getUncompressedMessageSize())
+        .setCompressedMessageSize(networkEvent.getCompressedMessageSize())
+        .build();
+  }
+
+  /**
+   * Cast or convert a {@link io.opencensus.trace.BaseMessageEvent} to {@link
+   * io.opencensus.trace.NetworkEvent}.
+   *
+   * @param event the {@code BaseMessageEvent} that is being cast or converted.
+   * @return a {@code io.opencensus.trace.NetworkEvent} representation of the input.
+   */
+  public static io.opencensus.trace.NetworkEvent asNetworkEvent(
+      io.opencensus.trace.BaseMessageEvent event) {
+    checkNotNull(event);
+    if (event instanceof io.opencensus.trace.NetworkEvent) {
+      return (io.opencensus.trace.NetworkEvent) event;
+    }
+    MessageEvent messageEvent = (MessageEvent) event;
+    io.opencensus.trace.NetworkEvent.Type type =
+        (messageEvent.getType() == MessageEvent.Type.RECEIVED)
+            ? io.opencensus.trace.NetworkEvent.Type.RECV
+            : io.opencensus.trace.NetworkEvent.Type.SENT;
+    return io.opencensus.trace.NetworkEvent.builder(type, messageEvent.getMessageId())
+        .setUncompressedMessageSize(messageEvent.getUncompressedMessageSize())
+        .setCompressedMessageSize(messageEvent.getCompressedMessageSize())
+        .build();
+  }
+
+  private BaseMessageEventUtil() {}
+}
diff --git a/api/src/main/java/io/opencensus/trace/BaseMessageEvent.java b/api/src/main/java/io/opencensus/trace/BaseMessageEvent.java
new file mode 100644
index 00000000..5ad961f6
--- /dev/null
+++ b/api/src/main/java/io/opencensus/trace/BaseMessageEvent.java
@@ -0,0 +1,37 @@
+/*
+ * Copyright 2018, OpenCensus Authors
+ *
+ * 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
+ *
+ *     http://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.opencensus.trace;
+
+/**
+ * Superclass for {@link MessageEvent} and {@link NetworkEvent} to resolve API backward
+ * compatibility issue.
+ *
+ * <p>{@code SpanData.create} can't be overloaded with parameter types that differ only in the type
+ * of the TimedEvent, because the signatures are the same after generic type erasure. {@code
+ * BaseMessageEvent} allows the same method to accept both {@code TimedEvents<NetworkEvent>} and
+ * {@code TimedEvents<MessageEvent>}.
+ *
+ * <p>This class should only be extended by {@code NetworkEvent} and {@code MessageEvent}.
+ *
+ * @deprecated This class is for internal use only.
+ * @since 0.12
+ */
+@Deprecated
+public abstract class BaseMessageEvent {
+  // package protected to avoid users to extend it.
+  BaseMessageEvent() {}
+}
diff --git a/api/src/main/java/io/opencensus/trace/BlankSpan.java b/api/src/main/java/io/opencensus/trace/BlankSpan.java
index 0f11a034..641bad7e 100644
--- a/api/src/main/java/io/opencensus/trace/BlankSpan.java
+++ b/api/src/main/java/io/opencensus/trace/BlankSpan.java
@@ -58,8 +58,13 @@ public final class BlankSpan extends Span {
 
   /** No-op implementation of the {@link Span#addNetworkEvent(NetworkEvent)} method. */
   @Override
+  @Deprecated
   public void addNetworkEvent(NetworkEvent networkEvent) {}
 
+  /** No-op implementation of the {@link Span#addMessageEvent(MessageEvent)} method. */
+  @Override
+  public void addMessageEvent(MessageEvent messageEvent) {}
+
   /** No-op implementation of the {@link Span#addLink(Link)} method. */
   @Override
   public void addLink(Link link) {}
diff --git a/api/src/main/java/io/opencensus/trace/MessageEvent.java b/api/src/main/java/io/opencensus/trace/MessageEvent.java
new file mode 100644
index 00000000..49a4673c
--- /dev/null
+++ b/api/src/main/java/io/opencensus/trace/MessageEvent.java
@@ -0,0 +1,154 @@
+/*
+ * Copyright 2018, OpenCensus Authors
+ *
+ * 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
+ *
+ *     http://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.opencensus.trace;
+
+import static com.google.common.base.Preconditions.checkNotNull;
+
+import com.google.auto.value.AutoValue;
+import javax.annotation.concurrent.Immutable;
+
+/**
+ * A class that represents a generic messaging event. This class can represent messaging happened in
+ * any layer, especially higher application layer. Thus, it can be used when recording events in
+ * pipeline works, in-process bidirectional streams and batch processing.
+ *
+ * <p>It requires a {@link Type type} and a message id that serves to uniquely identify each
+ * message. It can optionally have information about the message size.
+ *
+ * @since 0.12
+ */
+@Immutable
+@AutoValue
+// Suppress Checker Framework warning about missing @Nullable in generated equals method.
+@AutoValue.CopyAnnotations
+@SuppressWarnings({"nullness", "deprecation"})
+public abstract class MessageEvent extends BaseMessageEvent {
+  /**
+   * Available types for a {@code MessageEvent}.
+   *
+   * @since 0.12
+   */
+  public enum Type {
+    /**
+     * When the message was sent.
+     *
+     * @since 0.12
+     */
+    SENT,
+    /**
+     * When the message was received.
+     *
+     * @since 0.12
+     */
+    RECEIVED,
+  }
+
+  /**
+   * Returns a new {@link Builder} with default values.
+   *
+   * @param type designates whether this is a send or receive message.
+   * @param messageId serves to uniquely identify each message.
+   * @return a new {@code Builder} with default values.
+   * @throws NullPointerException if {@code type} is {@code null}.
+   * @since 0.12
+   */
+  public static Builder builder(Type type, long messageId) {
+    return new AutoValue_MessageEvent.Builder()
+        .setType(checkNotNull(type, "type"))
+        .setMessageId(messageId)
+        // We need to set a value for the message size because the autovalue requires all
+        // primitives to be initialized.
+        .setUncompressedMessageSize(0)
+        .setCompressedMessageSize(0);
+  }
+
+  /**
+   * Returns the type of the {@code MessageEvent}.
+   *
+   * @return the type of the {@code MessageEvent}.
+   * @since 0.12
+   */
+  public abstract Type getType();
+
+  /**
+   * Returns the message id argument that serves to uniquely identify each message.
+   *
+   * @return the message id of the {@code MessageEvent}.
+   * @since 0.12
+   */
+  public abstract long getMessageId();
+
+  /**
+   * Returns the uncompressed size in bytes of the {@code MessageEvent}.
+   *
+   * @return the uncompressed size in bytes of the {@code MessageEvent}.
+   * @since 0.12
+   */
+  public abstract long getUncompressedMessageSize();
+
+  /**
+   * Returns the compressed size in bytes of the {@code MessageEvent}.
+   *
+   * @return the compressed size in bytes of the {@code MessageEvent}.
+   * @since 0.12
+   */
+  public abstract long getCompressedMessageSize();
+
+  /**
+   * Builder class for {@link MessageEvent}.
+   *
+   * @since 0.12
+   */
+  @AutoValue.Builder
+  public abstract static class Builder {
+    // Package protected methods because these values are mandatory and set only in the
+    // MessageEvent#builder() function.
+    abstract Builder setType(Type type);
+
+    abstract Builder setMessageId(long messageId);
+
+    /**
+     * Sets the uncompressed message size.
+     *
+     * @param uncompressedMessageSize represents the uncompressed size in bytes of this message.
+     * @return this.
+     * @since 0.12
+     */
+    public abstract Builder setUncompressedMessageSize(long uncompressedMessageSize);
+
+    /**
+     * Sets the compressed message size.
+     *
+     * @param compressedMessageSize represents the compressed size in bytes of this message.
+     * @return this.
+     * @since 0.12
+     */
+    public abstract Builder setCompressedMessageSize(long compressedMessageSize);
+
+    /**
+     * Builds and returns a {@code MessageEvent} with the desired values.
+     *
+     * @return a {@code MessageEvent} with the desired values.
+     * @since 0.12
+     */
+    public abstract MessageEvent build();
+
+    Builder() {}
+  }
+
+  MessageEvent() {}
+}
diff --git a/api/src/main/java/io/opencensus/trace/NetworkEvent.java b/api/src/main/java/io/opencensus/trace/NetworkEvent.java
index a8dfdb70..1c8fe393 100644
--- a/api/src/main/java/io/opencensus/trace/NetworkEvent.java
+++ b/api/src/main/java/io/opencensus/trace/NetworkEvent.java
@@ -28,6 +28,7 @@ import javax.annotation.concurrent.Immutable;
  * serves to uniquely identify each network message. It can optionally can have information about
  * the kernel time and message size.
  *
+ * @deprecated Use {@link MessageEvent}.
  * @since 0.5
  */
 @Immutable
@@ -35,7 +36,8 @@ import javax.annotation.concurrent.Immutable;
 // Suppress Checker Framework warning about missing @Nullable in generated equals method.
 @AutoValue.CopyAnnotations
 @SuppressWarnings("nullness")
-public abstract class NetworkEvent {
+@Deprecated
+public abstract class NetworkEvent extends io.opencensus.trace.BaseMessageEvent {
   /**
    * Available types for a {@code NetworkEvent}.
    *
@@ -131,9 +133,12 @@ public abstract class NetworkEvent {
   /**
    * Builder class for {@link NetworkEvent}.
    *
+   * @deprecated {@link NetworkEvent} is deprecated. Please use {@link MessageEvent} and its builder
+   *     {@link MessageEvent.Builder}.
    * @since 0.5
    */
   @AutoValue.Builder
+  @Deprecated
   public abstract static class Builder {
     // Package protected methods because these values are mandatory and set only in the
     // NetworkEvent#builder() function.
diff --git a/api/src/main/java/io/opencensus/trace/Span.java b/api/src/main/java/io/opencensus/trace/Span.java
index 29673930..ae0e9b4b 100644
--- a/api/src/main/java/io/opencensus/trace/Span.java
+++ b/api/src/main/java/io/opencensus/trace/Span.java
@@ -19,6 +19,7 @@ package io.opencensus.trace;
 import static com.google.common.base.Preconditions.checkArgument;
 import static com.google.common.base.Preconditions.checkNotNull;
 
+import io.opencensus.internal.BaseMessageEventUtil;
 import java.util.Collections;
 import java.util.EnumSet;
 import java.util.Map;
@@ -159,9 +160,30 @@ public abstract class Span {
    * higher level applications.
    *
    * @param networkEvent the network event to add.
+   * @deprecated Use {@link #addMessageEvent}.
    * @since 0.5
    */
-  public abstract void addNetworkEvent(NetworkEvent networkEvent);
+  @Deprecated
+  public void addNetworkEvent(NetworkEvent networkEvent) {
+    addMessageEvent(BaseMessageEventUtil.asMessageEvent(networkEvent));
+  }
+
+  /**
+   * Adds a MessageEvent to the {@code Span}.
+   *
+   * <p>This function can be used by higher level applications to record messaging event.
+   *
+   * <p>This method should always be overridden by users whose API versions are larger or equal to
+   * {@code 0.12}.
+   *
+   * @param messageEvent the message to add.
+   * @since 0.12
+   */
+  public void addMessageEvent(MessageEvent messageEvent) {
+    // Default implementation by invoking addNetworkEvent() so that any existing derived classes,
+    // including implementation and the mocked ones, do not need to override this method explicitly.
+    addNetworkEvent(BaseMessageEventUtil.asNetworkEvent(messageEvent));
+  }
 
   /**
    * Adds a {@link Link} to the {@code Span}.
diff --git a/api/src/main/java/io/opencensus/trace/config/TraceParams.java b/api/src/main/java/io/opencensus/trace/config/TraceParams.java
index 17dbbb9d..6c2ee7ff 100644
--- a/api/src/main/java/io/opencensus/trace/config/TraceParams.java
+++ b/api/src/main/java/io/opencensus/trace/config/TraceParams.java
@@ -21,7 +21,7 @@ import static com.google.common.base.Preconditions.checkArgument;
 import com.google.auto.value.AutoValue;
 import io.opencensus.trace.Annotation;
 import io.opencensus.trace.Link;
-import io.opencensus.trace.NetworkEvent;
+import io.opencensus.trace.MessageEvent;
 import io.opencensus.trace.Sampler;
 import io.opencensus.trace.Span;
 import io.opencensus.trace.samplers.Samplers;
@@ -43,7 +43,7 @@ public abstract class TraceParams {
   private static final Sampler DEFAULT_SAMPLER = Samplers.probabilitySampler(DEFAULT_PROBABILITY);
   private static final int DEFAULT_SPAN_MAX_NUM_ATTRIBUTES = 32;
   private static final int DEFAULT_SPAN_MAX_NUM_ANNOTATIONS = 32;
-  private static final int DEFAULT_SPAN_MAX_NUM_NETWORK_EVENTS = 128;
+  private static final int DEFAULT_SPAN_MAX_NUM_MESSAGE_EVENTS = 128;
   private static final int DEFAULT_SPAN_MAX_NUM_LINKS = 128;
 
   /**
@@ -56,7 +56,7 @@ public abstract class TraceParams {
           .setSampler(DEFAULT_SAMPLER)
           .setMaxNumberOfAttributes(DEFAULT_SPAN_MAX_NUM_ATTRIBUTES)
           .setMaxNumberOfAnnotations(DEFAULT_SPAN_MAX_NUM_ANNOTATIONS)
-          .setMaxNumberOfNetworkEvents(DEFAULT_SPAN_MAX_NUM_NETWORK_EVENTS)
+          .setMaxNumberOfMessageEvents(DEFAULT_SPAN_MAX_NUM_MESSAGE_EVENTS)
           .setMaxNumberOfLinks(DEFAULT_SPAN_MAX_NUM_LINKS)
           .build();
 
@@ -86,12 +86,25 @@ public abstract class TraceParams {
   public abstract int getMaxNumberOfAnnotations();
 
   /**
-   * Returns the global default max number of {@link NetworkEvent} events per {@link Span}.
+   * Returns the global default max number of {@link MessageEvent} events per {@link Span}.
+   *
+   * @return the global default max number of {@code MessageEvent} events per {@code Span}.
+   * @since 0.12
+   */
+  public abstract int getMaxNumberOfMessageEvents();
+
+  /**
+   * Returns the global default max number of {@link io.opencensus.trace.NetworkEvent} events per
+   * {@link Span}.
    *
    * @return the global default max number of {@code NetworkEvent} events per {@code Span}.
+   * @deprecated Use {@link getMaxNumberOfMessageEvents}.
    * @since 0.5
    */
-  public abstract int getMaxNumberOfNetworkEvents();
+  @Deprecated
+  public int getMaxNumberOfNetworkEvents() {
+    return getMaxNumberOfMessageEvents();
+  }
 
   /**
    * Returns the global default max number of {@link Link} entries per {@link Span}.
@@ -152,14 +165,30 @@ public abstract class TraceParams {
     public abstract Builder setMaxNumberOfAnnotations(int maxNumberOfAnnotations);
 
     /**
-     * Sets the global default max number of {@link NetworkEvent} events per {@link Span}.
+     * Sets the global default max number of {@link MessageEvent} events per {@link Span}.
      *
-     * @param maxNumberOfNetworkEvents the global default max number of {@link NetworkEvent} events
+     * @param maxNumberOfMessageEvents the global default max number of {@link MessageEvent} events
      *     per {@link Span}. It must be positive otherwise {@link #build()} will throw an exception.
+     * @since 0.12
      * @return this.
+     */
+    public abstract Builder setMaxNumberOfMessageEvents(int maxNumberOfMessageEvents);
+
+    /**
+     * Sets the global default max number of {@link io.opencensus.trace.NetworkEvent} events per
+     * {@link Span}.
+     *
+     * @param maxNumberOfNetworkEvents the global default max number of {@link
+     *     io.opencensus.trace.NetworkEvent} events per {@link Span}. It must be positive otherwise
+     *     {@link #build()} will throw an exception.
+     * @return this.
+     * @deprecated Use {@link setMaxNumberOfMessageEvents}.
      * @since 0.5
      */
-    public abstract Builder setMaxNumberOfNetworkEvents(int maxNumberOfNetworkEvents);
+    @Deprecated
+    public Builder setMaxNumberOfNetworkEvents(int maxNumberOfNetworkEvents) {
+      return setMaxNumberOfMessageEvents(maxNumberOfNetworkEvents);
+    }
 
     /**
      * Sets the global default max number of {@link Link} entries per {@link Span}.
@@ -185,7 +214,7 @@ public abstract class TraceParams {
       TraceParams traceParams = autoBuild();
       checkArgument(traceParams.getMaxNumberOfAttributes() > 0, "maxNumberOfAttributes");
       checkArgument(traceParams.getMaxNumberOfAnnotations() > 0, "maxNumberOfAnnotations");
-      checkArgument(traceParams.getMaxNumberOfNetworkEvents() > 0, "maxNumberOfNetworkEvents");
+      checkArgument(traceParams.getMaxNumberOfMessageEvents() > 0, "maxNumberOfMessageEvents");
       checkArgument(traceParams.getMaxNumberOfLinks() > 0, "maxNumberOfLinks");
       return traceParams;
     }
diff --git a/api/src/main/java/io/opencensus/trace/export/SpanData.java b/api/src/main/java/io/opencensus/trace/export/SpanData.java
index 546b65b6..120c231a 100644
--- a/api/src/main/java/io/opencensus/trace/export/SpanData.java
+++ b/api/src/main/java/io/opencensus/trace/export/SpanData.java
@@ -19,11 +19,13 @@ package io.opencensus.trace.export;
 import static com.google.common.base.Preconditions.checkNotNull;
 
 import com.google.auto.value.AutoValue;
+import com.google.common.collect.Lists;
 import io.opencensus.common.Timestamp;
+import io.opencensus.internal.BaseMessageEventUtil;
 import io.opencensus.trace.Annotation;
 import io.opencensus.trace.AttributeValue;
 import io.opencensus.trace.Link;
-import io.opencensus.trace.NetworkEvent;
+import io.opencensus.trace.MessageEvent;
 import io.opencensus.trace.Span;
 import io.opencensus.trace.SpanContext;
 import io.opencensus.trace.SpanId;
@@ -64,7 +66,8 @@ public abstract class SpanData {
    * @param startTimestamp the start {@code Timestamp} of the {@code Span}.
    * @param attributes the attributes associated with the {@code Span}.
    * @param annotations the annotations associated with the {@code Span}.
-   * @param networkEvents the network events associated with the {@code Span}.
+   * @param messageOrNetworkEvents the message events (or network events for backward compatibility)
+   *     associated with the {@code Span}.
    * @param links the links associated with the {@code Span}.
    * @param childSpanCount the number of child spans that were generated while the span was active.
    * @param status the {@code Status} of the {@code Span}. {@code null} if the {@code Span} is still
@@ -74,6 +77,7 @@ public abstract class SpanData {
    * @return a new immutable {@code SpanData}.
    * @since 0.5
    */
+  @SuppressWarnings("deprecation")
   public static SpanData create(
       SpanContext context,
       @Nullable SpanId parentSpanId,
@@ -82,11 +86,31 @@ public abstract class SpanData {
       Timestamp startTimestamp,
       Attributes attributes,
       TimedEvents<Annotation> annotations,
-      TimedEvents<NetworkEvent> networkEvents,
+      TimedEvents<? extends io.opencensus.trace.BaseMessageEvent> messageOrNetworkEvents,
       Links links,
       @Nullable Integer childSpanCount,
       @Nullable Status status,
       @Nullable Timestamp endTimestamp) {
+    if (messageOrNetworkEvents == null) {
+      throw new NullPointerException("Null messageOrNetworkEvents");
+    }
+    List<TimedEvent<MessageEvent>> messageEventsList = Lists.newArrayList();
+    for (TimedEvent<? extends io.opencensus.trace.BaseMessageEvent> timedEvent :
+        messageOrNetworkEvents.getEvents()) {
+      io.opencensus.trace.BaseMessageEvent event = timedEvent.getEvent();
+      if (event instanceof MessageEvent) {
+        @SuppressWarnings("unchecked")
+        TimedEvent<MessageEvent> timedMessageEvent = (TimedEvent<MessageEvent>) timedEvent;
+        messageEventsList.add(timedMessageEvent);
+      } else {
+        messageEventsList.add(
+            TimedEvent.<MessageEvent>create(
+                timedEvent.getTimestamp(), BaseMessageEventUtil.asMessageEvent(event)));
+      }
+    }
+    TimedEvents<MessageEvent> messageEvents =
+        TimedEvents.<MessageEvent>create(
+            messageEventsList, messageOrNetworkEvents.getDroppedEventsCount());
     return new AutoValue_SpanData(
         context,
         parentSpanId,
@@ -95,7 +119,7 @@ public abstract class SpanData {
         startTimestamp,
         attributes,
         annotations,
-        networkEvents,
+        messageEvents,
         links,
         childSpanCount,
         status,
@@ -167,9 +191,31 @@ public abstract class SpanData {
    * Returns network events recorded for this {@code Span}.
    *
    * @return network events recorded for this {@code Span}.
+   * @deprecated Use {@link #getMessageEvents}.
    * @since 0.5
    */
-  public abstract TimedEvents<NetworkEvent> getNetworkEvents();
+  @Deprecated
+  @SuppressWarnings({"deprecation"})
+  public TimedEvents<io.opencensus.trace.NetworkEvent> getNetworkEvents() {
+    TimedEvents<MessageEvent> timedEvents = getMessageEvents();
+    List<TimedEvent<io.opencensus.trace.NetworkEvent>> networkEventsList = Lists.newArrayList();
+    for (TimedEvent<MessageEvent> timedEvent : timedEvents.getEvents()) {
+      networkEventsList.add(
+          TimedEvent.<io.opencensus.trace.NetworkEvent>create(
+              timedEvent.getTimestamp(),
+              BaseMessageEventUtil.asNetworkEvent(timedEvent.getEvent())));
+    }
+    return TimedEvents.<io.opencensus.trace.NetworkEvent>create(
+        networkEventsList, timedEvents.getDroppedEventsCount());
+  }
+
+  /**
+   * Returns message events recorded for this {@code Span}.
+   *
+   * @return message events recorded for this {@code Span}.
+   * @since 0.12
+   */
+  public abstract TimedEvents<MessageEvent> getMessageEvents();
 
   /**
    * Returns links recorded for this {@code Span}.
diff --git a/api/src/test/java/io/opencensus/internal/BaseMessageEventUtilTest.java b/api/src/test/java/io/opencensus/internal/BaseMessageEventUtilTest.java
new file mode 100644
index 00000000..8de1b1c9
--- /dev/null
+++ b/api/src/test/java/io/opencensus/internal/BaseMessageEventUtilTest.java
@@ -0,0 +1,71 @@
+/*
+ * Copyright 2018, OpenCensus Authors
+ *
+ * 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
+ *
+ *     http://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.opencensus.internal;
+
+import static com.google.common.truth.Truth.assertThat;
+
+import io.opencensus.trace.MessageEvent;
+import io.opencensus.trace.NetworkEvent;
+import org.junit.Test;
+import org.junit.runner.RunWith;
+import org.junit.runners.JUnit4;
+
+/** Unit tests for {@link BaseMessageEventUtil}. */
+@RunWith(JUnit4.class)
+public class BaseMessageEventUtilTest {
+  private static final long SENT_EVENT_ID = 12345L;
+  private static final long RECV_EVENT_ID = 67890L;
+  private static final long UNCOMPRESSED_SIZE = 100;
+  private static final long COMPRESSED_SIZE = 99;
+
+  private static final MessageEvent SENT_MESSAGE_EVENT =
+      MessageEvent.builder(MessageEvent.Type.SENT, SENT_EVENT_ID)
+          .setUncompressedMessageSize(UNCOMPRESSED_SIZE)
+          .setCompressedMessageSize(COMPRESSED_SIZE)
+          .build();
+  private static final MessageEvent RECV_MESSAGE_EVENT =
+      MessageEvent.builder(MessageEvent.Type.RECEIVED, RECV_EVENT_ID)
+          .setUncompressedMessageSize(UNCOMPRESSED_SIZE)
+          .setCompressedMessageSize(COMPRESSED_SIZE)
+          .build();
+  private static final NetworkEvent SENT_NETWORK_EVENT =
+      NetworkEvent.builder(NetworkEvent.Type.SENT, SENT_EVENT_ID)
+          .setUncompressedMessageSize(UNCOMPRESSED_SIZE)
+          .setCompressedMessageSize(COMPRESSED_SIZE)
+          .build();
+  private static final NetworkEvent RECV_NETWORK_EVENT =
+      NetworkEvent.builder(NetworkEvent.Type.RECV, RECV_EVENT_ID)
+          .setUncompressedMessageSize(UNCOMPRESSED_SIZE)
+          .setCompressedMessageSize(COMPRESSED_SIZE)
+          .build();
+
+  @Test
+  public void networkEventToMessageEvent() {
+    assertThat(BaseMessageEventUtil.asMessageEvent(SENT_NETWORK_EVENT))
+        .isEqualTo(SENT_MESSAGE_EVENT);
+    assertThat(BaseMessageEventUtil.asMessageEvent(RECV_NETWORK_EVENT))
+        .isEqualTo(RECV_MESSAGE_EVENT);
+  }
+
+  @Test
+  public void messageEventToNetworkEvent() {
+    assertThat(BaseMessageEventUtil.asNetworkEvent(SENT_MESSAGE_EVENT))
+        .isEqualTo(SENT_NETWORK_EVENT);
+    assertThat(BaseMessageEventUtil.asNetworkEvent(RECV_MESSAGE_EVENT))
+        .isEqualTo(RECV_NETWORK_EVENT);
+  }
+}
diff --git a/api/src/test/java/io/opencensus/trace/BlankSpanTest.java b/api/src/test/java/io/opencensus/trace/BlankSpanTest.java
index b9760c2f..185a5acd 100644
--- a/api/src/test/java/io/opencensus/trace/BlankSpanTest.java
+++ b/api/src/test/java/io/opencensus/trace/BlankSpanTest.java
@@ -53,6 +53,7 @@ public class BlankSpanTest {
     BlankSpan.INSTANCE.addAnnotation("MyAnnotation", multipleAttributes);
     BlankSpan.INSTANCE.addAnnotation(Annotation.fromDescription("MyAnnotation"));
     BlankSpan.INSTANCE.addNetworkEvent(NetworkEvent.builder(NetworkEvent.Type.SENT, 1L).build());
+    BlankSpan.INSTANCE.addMessageEvent(MessageEvent.builder(MessageEvent.Type.SENT, 1L).build());
     BlankSpan.INSTANCE.addLink(
         Link.fromSpanContext(SpanContext.INVALID, Link.Type.CHILD_LINKED_SPAN));
     BlankSpan.INSTANCE.setStatus(Status.OK);
diff --git a/api/src/test/java/io/opencensus/trace/MessageEventTest.java b/api/src/test/java/io/opencensus/trace/MessageEventTest.java
new file mode 100644
index 00000000..fde32fe6
--- /dev/null
+++ b/api/src/test/java/io/opencensus/trace/MessageEventTest.java
@@ -0,0 +1,84 @@
+/*
+ * Copyright 2018, OpenCensus Authors
+ *
+ * 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
+ *
+ *     http://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.opencensus.trace;
+
+import static com.google.common.truth.Truth.assertThat;
+
+import org.junit.Test;
+import org.junit.runner.RunWith;
+import org.junit.runners.JUnit4;
+
+/** Unit tests for {@link MessageEvent}. */
+@RunWith(JUnit4.class)
+public class MessageEventTest {
+  @Test(expected = NullPointerException.class)
+  public void buildMessageEvent_NullType() {
+    MessageEvent.builder(null, 1L).build();
+  }
+
+  @Test
+  public void buildMessageEvent_WithRequiredFields() {
+    MessageEvent messageEvent = MessageEvent.builder(MessageEvent.Type.SENT, 1L).build();
+    assertThat(messageEvent.getType()).isEqualTo(MessageEvent.Type.SENT);
+    assertThat(messageEvent.getMessageId()).isEqualTo(1L);
+    assertThat(messageEvent.getUncompressedMessageSize()).isEqualTo(0L);
+  }
+
+  @Test
+  public void buildMessageEvent_WithUncompressedMessageSize() {
+    MessageEvent messageEvent =
+        MessageEvent.builder(MessageEvent.Type.SENT, 1L).setUncompressedMessageSize(123L).build();
+    assertThat(messageEvent.getType()).isEqualTo(MessageEvent.Type.SENT);
+    assertThat(messageEvent.getMessageId()).isEqualTo(1L);
+    assertThat(messageEvent.getUncompressedMessageSize()).isEqualTo(123L);
+  }
+
+  @Test
+  public void buildMessageEvent_WithCompressedMessageSize() {
+    MessageEvent messageEvent =
+        MessageEvent.builder(MessageEvent.Type.SENT, 1L).setCompressedMessageSize(123L).build();
+    assertThat(messageEvent.getType()).isEqualTo(MessageEvent.Type.SENT);
+    assertThat(messageEvent.getMessageId()).isEqualTo(1L);
+    assertThat(messageEvent.getCompressedMessageSize()).isEqualTo(123L);
+  }
+
+  @Test
+  public void buildMessageEvent_WithAllValues() {
+    MessageEvent messageEvent =
+        MessageEvent.builder(MessageEvent.Type.RECEIVED, 1L)
+            .setUncompressedMessageSize(123L)
+            .setCompressedMessageSize(63L)
+            .build();
+    assertThat(messageEvent.getType()).isEqualTo(MessageEvent.Type.RECEIVED);
+    assertThat(messageEvent.getMessageId()).isEqualTo(1L);
+    assertThat(messageEvent.getUncompressedMessageSize()).isEqualTo(123L);
+    assertThat(messageEvent.getCompressedMessageSize()).isEqualTo(63L);
+  }
+
+  @Test
+  public void messageEvent_ToString() {
+    MessageEvent messageEvent =
+        MessageEvent.builder(MessageEvent.Type.SENT, 1L)
+            .setUncompressedMessageSize(123L)
+            .setCompressedMessageSize(63L)
+            .build();
+    assertThat(messageEvent.toString()).contains("type=SENT");
+    assertThat(messageEvent.toString()).contains("messageId=1");
+    assertThat(messageEvent.toString()).contains("compressedMessageSize=63");
+    assertThat(messageEvent.toString()).contains("uncompressedMessageSize=123");
+  }
+}
diff --git a/api/src/test/java/io/opencensus/trace/NoopSpan.java b/api/src/test/java/io/opencensus/trace/NoopSpan.java
index 0217529d..7c8d9b7a 100644
--- a/api/src/test/java/io/opencensus/trace/NoopSpan.java
+++ b/api/src/test/java/io/opencensus/trace/NoopSpan.java
@@ -45,6 +45,9 @@ public class NoopSpan extends Span {
   public void addNetworkEvent(NetworkEvent networkEvent) {}
 
   @Override
+  public void addMessageEvent(MessageEvent messageEvent) {}
+
+  @Override
   public void addLink(Link link) {}
 
   @Override
diff --git a/api/src/test/java/io/opencensus/trace/SpanTest.java b/api/src/test/java/io/opencensus/trace/SpanTest.java
index 327b9abe..f7546ca4 100644
--- a/api/src/test/java/io/opencensus/trace/SpanTest.java
+++ b/api/src/test/java/io/opencensus/trace/SpanTest.java
@@ -98,4 +98,22 @@ public class SpanTest {
     span.end();
     verify(span).end(same(EndSpanOptions.DEFAULT));
   }
+
+  @Test
+  public void addMessageEventDefaultImplementation() {
+    Span mockSpan = Mockito.mock(Span.class);
+    MessageEvent messageEvent =
+        MessageEvent.builder(MessageEvent.Type.SENT, 123)
+            .setUncompressedMessageSize(456)
+            .setCompressedMessageSize(789)
+            .build();
+    NetworkEvent networkEvent =
+        NetworkEvent.builder(NetworkEvent.Type.SENT, 123)
+            .setUncompressedMessageSize(456)
+            .setCompressedMessageSize(789)
+            .build();
+    Mockito.doCallRealMethod().when(mockSpan).addMessageEvent(messageEvent);
+    mockSpan.addMessageEvent(messageEvent);
+    verify(mockSpan).addNetworkEvent(eq(networkEvent));
+  }
 }
diff --git a/api/src/test/java/io/opencensus/trace/config/TraceConfigTest.java b/api/src/test/java/io/opencensus/trace/config/TraceConfigTest.java
index ee80cab4..d48e0894 100644
--- a/api/src/test/java/io/opencensus/trace/config/TraceConfigTest.java
+++ b/api/src/test/java/io/opencensus/trace/config/TraceConfigTest.java
@@ -42,6 +42,7 @@ public class TraceConfigTest {
             .setMaxNumberOfAttributes(8)
             .setMaxNumberOfAnnotations(9)
             .setMaxNumberOfNetworkEvents(10)
+            .setMaxNumberOfMessageEvents(10)
             .setMaxNumberOfLinks(11)
             .build();
     traceConfig.updateActiveTraceParams(traceParams);
diff --git a/api/src/test/java/io/opencensus/trace/config/TraceParamsTest.java b/api/src/test/java/io/opencensus/trace/config/TraceParamsTest.java
index 7ede0a29..6c216174 100644
--- a/api/src/test/java/io/opencensus/trace/config/TraceParamsTest.java
+++ b/api/src/test/java/io/opencensus/trace/config/TraceParamsTest.java
@@ -32,6 +32,7 @@ public class TraceParamsTest {
     assertThat(TraceParams.DEFAULT.getMaxNumberOfAttributes()).isEqualTo(32);
     assertThat(TraceParams.DEFAULT.getMaxNumberOfAnnotations()).isEqualTo(32);
     assertThat(TraceParams.DEFAULT.getMaxNumberOfNetworkEvents()).isEqualTo(128);
+    assertThat(TraceParams.DEFAULT.getMaxNumberOfMessageEvents()).isEqualTo(128);
     assertThat(TraceParams.DEFAULT.getMaxNumberOfLinks()).isEqualTo(128);
   }
 
@@ -56,6 +57,11 @@ public class TraceParamsTest {
   }
 
   @Test(expected = IllegalArgumentException.class)
+  public void updateTraceParams_NonPositiveMaxNumberOfMessageEvents() {
+    TraceParams.DEFAULT.toBuilder().setMaxNumberOfMessageEvents(0).build();
+  }
+
+  @Test(expected = IllegalArgumentException.class)
   public void updateTraceParams_NonPositiveMaxNumberOfLinks() {
     TraceParams.DEFAULT.toBuilder().setMaxNumberOfLinks(0).build();
   }
@@ -68,13 +74,24 @@ public class TraceParamsTest {
             .setSampler(Samplers.alwaysSample())
             .setMaxNumberOfAttributes(8)
             .setMaxNumberOfAnnotations(9)
-            .setMaxNumberOfNetworkEvents(10)
+            .setMaxNumberOfMessageEvents(10)
             .setMaxNumberOfLinks(11)
             .build();
     assertThat(traceParams.getSampler()).isEqualTo(Samplers.alwaysSample());
     assertThat(traceParams.getMaxNumberOfAttributes()).isEqualTo(8);
     assertThat(traceParams.getMaxNumberOfAnnotations()).isEqualTo(9);
+    // test maxNumberOfNetworkEvent can be set via maxNumberOfMessageEvent
     assertThat(traceParams.getMaxNumberOfNetworkEvents()).isEqualTo(10);
+    assertThat(traceParams.getMaxNumberOfMessageEvents()).isEqualTo(10);
     assertThat(traceParams.getMaxNumberOfLinks()).isEqualTo(11);
   }
+
+  @Test
+  public void updateTraceParams_maxNumberOfNetworkEvents() {
+    TraceParams traceParams =
+        TraceParams.DEFAULT.toBuilder().setMaxNumberOfNetworkEvents(10).build();
+    assertThat(traceParams.getMaxNumberOfNetworkEvents()).isEqualTo(10);
+    // test maxNumberOfMessageEvent can be set via maxNumberOfNetworkEvent
+    assertThat(traceParams.getMaxNumberOfMessageEvents()).isEqualTo(10);
+  }
 }
diff --git a/api/src/test/java/io/opencensus/trace/export/SpanDataTest.java b/api/src/test/java/io/opencensus/trace/export/SpanDataTest.java
index 5c8097fa..399b35e0 100644
--- a/api/src/test/java/io/opencensus/trace/export/SpanDataTest.java
+++ b/api/src/test/java/io/opencensus/trace/export/SpanDataTest.java
@@ -24,6 +24,7 @@ import io.opencensus.trace.Annotation;
 import io.opencensus.trace.AttributeValue;
 import io.opencensus.trace.Link;
 import io.opencensus.trace.Link.Type;
+import io.opencensus.trace.MessageEvent;
 import io.opencensus.trace.NetworkEvent;
 import io.opencensus.trace.SpanContext;
 import io.opencensus.trace.SpanId;
@@ -60,6 +61,10 @@ public class SpanDataTest {
       NetworkEvent.builder(NetworkEvent.Type.RECV, 1).build();
   private static final NetworkEvent sentNetworkEvent =
       NetworkEvent.builder(NetworkEvent.Type.SENT, 1).build();
+  private static final MessageEvent recvMessageEvent =
+      MessageEvent.builder(MessageEvent.Type.RECEIVED, 1).build();
+  private static final MessageEvent sentMessageEvent =
+      MessageEvent.builder(MessageEvent.Type.SENT, 1).build();
   private static final Status status = Status.DEADLINE_EXCEEDED.withDescription("TooSlow");
   private static final int CHILD_SPAN_COUNT = 13;
   private final Random random = new Random(1234);
@@ -72,11 +77,14 @@ public class SpanDataTest {
       new ArrayList<TimedEvent<Annotation>>();
   private final List<TimedEvent<NetworkEvent>> networkEventsList =
       new ArrayList<SpanData.TimedEvent<NetworkEvent>>();
+  private final List<TimedEvent<MessageEvent>> messageEventsList =
+      new ArrayList<SpanData.TimedEvent<MessageEvent>>();
   private final List<Link> linksList = new ArrayList<Link>();
 
   private Attributes attributes;
   private TimedEvents<Annotation> annotations;
   private TimedEvents<NetworkEvent> networkEvents;
+  private TimedEvents<MessageEvent> messageEvents;
   private Links links;
 
   @Before
@@ -90,6 +98,9 @@ public class SpanDataTest {
     networkEventsList.add(SpanData.TimedEvent.create(eventTimestamp1, recvNetworkEvent));
     networkEventsList.add(SpanData.TimedEvent.create(eventTimestamp2, sentNetworkEvent));
     networkEvents = TimedEvents.create(networkEventsList, 3);
+    messageEventsList.add(SpanData.TimedEvent.create(eventTimestamp1, recvMessageEvent));
+    messageEventsList.add(SpanData.TimedEvent.create(eventTimestamp2, sentMessageEvent));
+    messageEvents = TimedEvents.create(messageEventsList, 3);
     linksList.add(Link.fromSpanContext(spanContext, Type.CHILD_LINKED_SPAN));
     links = Links.create(linksList, 0);
   }
@@ -105,6 +116,37 @@ public class SpanDataTest {
             startTimestamp,
             attributes,
             annotations,
+            messageEvents,
+            links,
+            CHILD_SPAN_COUNT,
+            status,
+            endTimestamp);
+    assertThat(spanData.getContext()).isEqualTo(spanContext);
+    assertThat(spanData.getParentSpanId()).isEqualTo(parentSpanId);
+    assertThat(spanData.getHasRemoteParent()).isTrue();
+    assertThat(spanData.getName()).isEqualTo(SPAN_NAME);
+    assertThat(spanData.getStartTimestamp()).isEqualTo(startTimestamp);
+    assertThat(spanData.getAttributes()).isEqualTo(attributes);
+    assertThat(spanData.getAnnotations()).isEqualTo(annotations);
+    assertThat(spanData.getNetworkEvents()).isEqualTo(networkEvents);
+    assertThat(spanData.getMessageEvents()).isEqualTo(messageEvents);
+    assertThat(spanData.getLinks()).isEqualTo(links);
+    assertThat(spanData.getChildSpanCount()).isEqualTo(CHILD_SPAN_COUNT);
+    assertThat(spanData.getStatus()).isEqualTo(status);
+    assertThat(spanData.getEndTimestamp()).isEqualTo(endTimestamp);
+  }
+
+  @Test
+  public void spanData_Create_Compatibility() {
+    SpanData spanData =
+        SpanData.create(
+            spanContext,
+            parentSpanId,
+            true,
+            SPAN_NAME,
+            startTimestamp,
+            attributes,
+            annotations,
             networkEvents,
             links,
             CHILD_SPAN_COUNT,
@@ -118,6 +160,7 @@ public class SpanDataTest {
     assertThat(spanData.getAttributes()).isEqualTo(attributes);
     assertThat(spanData.getAnnotations()).isEqualTo(annotations);
     assertThat(spanData.getNetworkEvents()).isEqualTo(networkEvents);
+    assertThat(spanData.getMessageEvents()).isEqualTo(messageEvents);
     assertThat(spanData.getLinks()).isEqualTo(links);
     assertThat(spanData.getChildSpanCount()).isEqualTo(CHILD_SPAN_COUNT);
     assertThat(spanData.getStatus()).isEqualTo(status);
@@ -135,7 +178,7 @@ public class SpanDataTest {
             startTimestamp,
             attributes,
             annotations,
-            networkEvents,
+            messageEvents,
             links,
             null,
             null,
@@ -148,6 +191,7 @@ public class SpanDataTest {
     assertThat(spanData.getAttributes()).isEqualTo(attributes);
     assertThat(spanData.getAnnotations()).isEqualTo(annotations);
     assertThat(spanData.getNetworkEvents()).isEqualTo(networkEvents);
+    assertThat(spanData.getMessageEvents()).isEqualTo(messageEvents);
     assertThat(spanData.getLinks()).isEqualTo(links);
     assertThat(spanData.getChildSpanCount()).isNull();
     assertThat(spanData.getStatus()).isNull();
@@ -165,7 +209,7 @@ public class SpanDataTest {
             startTimestamp,
             Attributes.create(Collections.<String, AttributeValue>emptyMap(), 0),
             TimedEvents.create(Collections.<SpanData.TimedEvent<Annotation>>emptyList(), 0),
-            TimedEvents.create(Collections.<SpanData.TimedEvent<NetworkEvent>>emptyList(), 0),
+            TimedEvents.create(Collections.<SpanData.TimedEvent<MessageEvent>>emptyList(), 0),
             Links.create(Collections.<Link>emptyList(), 0),
             0,
             status,
@@ -178,6 +222,7 @@ public class SpanDataTest {
     assertThat(spanData.getAttributes().getAttributeMap().isEmpty()).isTrue();
     assertThat(spanData.getAnnotations().getEvents().isEmpty()).isTrue();
     assertThat(spanData.getNetworkEvents().getEvents().isEmpty()).isTrue();
+    assertThat(spanData.getMessageEvents().getEvents().isEmpty()).isTrue();
     assertThat(spanData.getLinks().getLinks().isEmpty()).isTrue();
     assertThat(spanData.getChildSpanCount()).isEqualTo(0);
     assertThat(spanData.getStatus()).isEqualTo(status);
@@ -195,7 +240,7 @@ public class SpanDataTest {
             startTimestamp,
             attributes,
             annotations,
-            networkEvents,
+            messageEvents,
             links,
             CHILD_SPAN_COUNT,
             status,
@@ -209,7 +254,7 @@ public class SpanDataTest {
             startTimestamp,
             attributes,
             annotations,
-            networkEvents,
+            messageEvents,
             links,
             CHILD_SPAN_COUNT,
             status,
@@ -223,7 +268,7 @@ public class SpanDataTest {
             startTimestamp,
             Attributes.create(Collections.<String, AttributeValue>emptyMap(), 0),
             TimedEvents.create(Collections.<SpanData.TimedEvent<Annotation>>emptyList(), 0),
-            TimedEvents.create(Collections.<SpanData.TimedEvent<NetworkEvent>>emptyList(), 0),
+            TimedEvents.create(Collections.<SpanData.TimedEvent<MessageEvent>>emptyList(), 0),
             Links.create(Collections.<Link>emptyList(), 0),
             0,
             status,
@@ -245,7 +290,7 @@ public class SpanDataTest {
                 startTimestamp,
                 attributes,
                 annotations,
-                networkEvents,
+                messageEvents,
                 links,
                 CHILD_SPAN_COUNT,
                 status,
@@ -257,7 +302,7 @@ public class SpanDataTest {
     assertThat(spanDataString).contains(startTimestamp.toString());
     assertThat(spanDataString).contains(attributes.toString());
     assertThat(spanDataString).contains(annotations.toString());
-    assertThat(spanDataString).contains(networkEvents.toString());
+    assertThat(spanDataString).contains(messageEvents.toString());
     assertThat(spanDataString).contains(links.toString());
     assertThat(spanDataString).contains(status.toString());
     assertThat(spanDataString).contains(endTimestamp.toString());
diff --git a/benchmarks/src/jmh/java/io/opencensus/benchmarks/trace/RecordTraceEventsNonSampledSpanBenchmark.java b/benchmarks/src/jmh/java/io/opencensus/benchmarks/trace/RecordTraceEventsNonSampledSpanBenchmark.java
index 8eff5a26..ffdc802b 100644
--- a/benchmarks/src/jmh/java/io/opencensus/benchmarks/trace/RecordTraceEventsNonSampledSpanBenchmark.java
+++ b/benchmarks/src/jmh/java/io/opencensus/benchmarks/trace/RecordTraceEventsNonSampledSpanBenchmark.java
@@ -18,7 +18,6 @@ package io.opencensus.benchmarks.trace;
 
 import io.opencensus.trace.AttributeValue;
 import io.opencensus.trace.Link;
-import io.opencensus.trace.NetworkEvent;
 import io.opencensus.trace.Span;
 import io.opencensus.trace.Tracer;
 import io.opencensus.trace.Tracing;
@@ -80,9 +79,12 @@ public class RecordTraceEventsNonSampledSpanBenchmark {
   @Benchmark
   @BenchmarkMode(Mode.SampleTime)
   @OutputTimeUnit(TimeUnit.NANOSECONDS)
+  @SuppressWarnings("deprecation")
   public Span addNetworkEvent() {
     span.addNetworkEvent(
-        NetworkEvent.builder(NetworkEvent.Type.RECV, 1).setUncompressedMessageSize(3).build());
+        io.opencensus.trace.NetworkEvent.builder(io.opencensus.trace.NetworkEvent.Type.RECV, 1)
+            .setUncompressedMessageSize(3)
+            .build());
     return span;
   }
 
diff --git a/benchmarks/src/jmh/java/io/opencensus/benchmarks/trace/RecordTraceEventsSampledSpanBenchmark.java b/benchmarks/src/jmh/java/io/opencensus/benchmarks/trace/RecordTraceEventsSampledSpanBenchmark.java
index cf4bf2dd..71b97316 100644
--- a/benchmarks/src/jmh/java/io/opencensus/benchmarks/trace/RecordTraceEventsSampledSpanBenchmark.java
+++ b/benchmarks/src/jmh/java/io/opencensus/benchmarks/trace/RecordTraceEventsSampledSpanBenchmark.java
@@ -18,7 +18,6 @@ package io.opencensus.benchmarks.trace;
 
 import io.opencensus.trace.AttributeValue;
 import io.opencensus.trace.Link;
-import io.opencensus.trace.NetworkEvent;
 import io.opencensus.trace.Span;
 import io.opencensus.trace.Tracer;
 import io.opencensus.trace.Tracing;
@@ -80,9 +79,12 @@ public class RecordTraceEventsSampledSpanBenchmark {
   @Benchmark
   @BenchmarkMode(Mode.SampleTime)
   @OutputTimeUnit(TimeUnit.NANOSECONDS)
+  @SuppressWarnings("deprecation")
   public Span addNetworkEvent() {
     span.addNetworkEvent(
-        NetworkEvent.builder(NetworkEvent.Type.RECV, 1).setUncompressedMessageSize(3).build());
+        io.opencensus.trace.NetworkEvent.builder(io.opencensus.trace.NetworkEvent.Type.RECV, 1)
+            .setUncompressedMessageSize(3)
+            .build());
     return span;
   }
 
diff --git a/contrib/zpages/src/main/java/io/opencensus/contrib/zpages/TraceConfigzZPageHandler.java b/contrib/zpages/src/main/java/io/opencensus/contrib/zpages/TraceConfigzZPageHandler.java
index 9b075b30..0df86b96 100644
--- a/contrib/zpages/src/main/java/io/opencensus/contrib/zpages/TraceConfigzZPageHandler.java
+++ b/contrib/zpages/src/main/java/io/opencensus/contrib/zpages/TraceConfigzZPageHandler.java
@@ -29,6 +29,7 @@ import java.io.PrintWriter;
 import java.util.Map;
 
 // TODO(bdrutu): Add tests.
+// TODO(hailongwen): Remove the usage of `NetworkEvent` in the future.
 /**
  * HTML page formatter for tracing config. The page displays information about the current active
  * tracing configuration and allows users to change it.
@@ -90,6 +91,7 @@ final class TraceConfigzZPageHandler extends ZPageHandler {
   }
 
   @Override
+  @SuppressWarnings("deprecation")
   public void emitHtml(Map<String, String> queryMap, OutputStream outputStream) {
     PrintWriter out =
         new PrintWriter(new BufferedWriter(new OutputStreamWriter(outputStream, Charsets.UTF_8)));
@@ -131,6 +133,7 @@ final class TraceConfigzZPageHandler extends ZPageHandler {
   }
 
   // If this is a supported change (currently only permanent changes are supported) apply it.
+  @SuppressWarnings("deprecation")
   private void maybeApplyChanges(Map<String, String> queryMap) {
     String changeStr = queryMap.get(CHANGE);
     if (PERMANENT_CHANGE.equals(changeStr)) {
@@ -168,6 +171,7 @@ final class TraceConfigzZPageHandler extends ZPageHandler {
   }
 
   // Prints a table to a PrintWriter that shows existing trace parameters.
+  @SuppressWarnings("deprecation")
   private static void emitTraceParamsTable(TraceParams params, PrintWriter out) {
     out.write(
         "<b>Active tracing parameters:</b><br>\n"
diff --git a/contrib/zpages/src/main/java/io/opencensus/contrib/zpages/TracezZPageHandler.java b/contrib/zpages/src/main/java/io/opencensus/contrib/zpages/TracezZPageHandler.java
index 7a42c2c7..dc208574 100644
--- a/contrib/zpages/src/main/java/io/opencensus/contrib/zpages/TracezZPageHandler.java
+++ b/contrib/zpages/src/main/java/io/opencensus/contrib/zpages/TracezZPageHandler.java
@@ -27,8 +27,6 @@ import io.opencensus.common.Functions;
 import io.opencensus.common.Timestamp;
 import io.opencensus.trace.Annotation;
 import io.opencensus.trace.AttributeValue;
-import io.opencensus.trace.NetworkEvent;
-import io.opencensus.trace.NetworkEvent.Type;
 import io.opencensus.trace.SpanContext;
 import io.opencensus.trace.SpanId;
 import io.opencensus.trace.Status;
@@ -65,6 +63,7 @@ import java.util.TreeSet;
 import java.util.concurrent.TimeUnit;
 import javax.annotation.Nullable;
 
+// TODO(hailongwen): remove the usage of `NetworkEvent` in the future.
 /**
  * HTML page formatter for tracing debug. The page displays information about all active spans and
  * all sampled spans based on latency and errors.
@@ -280,6 +279,7 @@ final class TracezZPageHandler extends ZPageHandler {
   }
 
   // Emits the internal html for a single {@link SpanData}.
+  @SuppressWarnings("deprecation")
   private static void emitSingleSpan(PrintWriter out, Formatter formatter, SpanData span) {
     Calendar calendar = Calendar.getInstance();
     calendar.setTimeInMillis(TimeUnit.SECONDS.toMillis(span.getStartTimestamp().getSeconds()));
@@ -320,7 +320,7 @@ final class TracezZPageHandler extends ZPageHandler {
 
     Timestamp lastTimestampNanos = span.getStartTimestamp();
     TimedEvents<Annotation> annotations = span.getAnnotations();
-    TimedEvents<NetworkEvent> networkEvents = span.getNetworkEvents();
+    TimedEvents<io.opencensus.trace.NetworkEvent> networkEvents = span.getNetworkEvents();
     List<TimedEvent<?>> timedEvents = new ArrayList<TimedEvent<?>>(annotations.getEvents());
     timedEvents.addAll(networkEvents.getEvents());
     Collections.sort(timedEvents, new TimedEventComparator());
@@ -370,8 +370,8 @@ final class TracezZPageHandler extends ZPageHandler {
               .escape(
                   event.getEvent() instanceof Annotation
                       ? renderAnnotation((Annotation) event.getEvent())
-                      : renderNetworkEvents((NetworkEvent) castNonNull(event.getEvent()))));
-
+                      : renderNetworkEvents(
+                          (io.opencensus.trace.NetworkEvent) castNonNull(event.getEvent()))));
       lastTimestampNanos = event.getTimestamp();
     }
     Status status = span.getStatus();
@@ -576,11 +576,12 @@ final class TracezZPageHandler extends ZPageHandler {
     throw new IllegalArgumentException("No value string available for: " + latencyBucketBoundaries);
   }
 
-  private static String renderNetworkEvents(NetworkEvent networkEvent) {
+  @SuppressWarnings("deprecation")
+  private static String renderNetworkEvents(io.opencensus.trace.NetworkEvent networkEvent) {
     StringBuilder stringBuilder = new StringBuilder();
-    if (networkEvent.getType() == Type.RECV) {
+    if (networkEvent.getType() == io.opencensus.trace.NetworkEvent.Type.RECV) {
       stringBuilder.append("Received message");
-    } else if (networkEvent.getType() == Type.SENT) {
+    } else if (networkEvent.getType() == io.opencensus.trace.NetworkEvent.Type.SENT) {
       stringBuilder.append("Sent message");
     } else {
       stringBuilder.append("Unknown");
diff --git a/exporters/trace/stackdriver/src/main/java/io/opencensus/exporter/trace/stackdriver/StackdriverV2ExporterHandler.java b/exporters/trace/stackdriver/src/main/java/io/opencensus/exporter/trace/stackdriver/StackdriverV2ExporterHandler.java
index fc7e234a..7aea093e 100644
--- a/exporters/trace/stackdriver/src/main/java/io/opencensus/exporter/trace/stackdriver/StackdriverV2ExporterHandler.java
+++ b/exporters/trace/stackdriver/src/main/java/io/opencensus/exporter/trace/stackdriver/StackdriverV2ExporterHandler.java
@@ -42,8 +42,6 @@ import io.opencensus.common.OpenCensusLibraryInformation;
 import io.opencensus.common.Scope;
 import io.opencensus.common.Timestamp;
 import io.opencensus.trace.Annotation;
-import io.opencensus.trace.NetworkEvent;
-import io.opencensus.trace.NetworkEvent.Type;
 import io.opencensus.trace.Sampler;
 import io.opencensus.trace.SpanContext;
 import io.opencensus.trace.SpanId;
@@ -66,6 +64,7 @@ import java.util.Map;
 import org.checkerframework.checker.nullness.qual.Nullable;
 */
 
+// TODO(hailongwen): remove the usage of `NetworkEvent` in the future.
 /** Exporter to Stackdriver Trace API v2. */
 final class StackdriverV2ExporterHandler extends SpanExporter.Handler {
   private static final Tracer tracer = Tracing.getTracer();
@@ -115,6 +114,7 @@ final class StackdriverV2ExporterHandler extends SpanExporter.Handler {
     final String spanIdHex = encodeSpanId(context.getSpanId());
     SpanName spanName =
         SpanName.newBuilder().setProject(projectId).setTrace(traceIdHex).setSpan(spanIdHex).build();
+    @SuppressWarnings("deprecation")
     Span.Builder spanBuilder =
         Span.newBuilder()
             .setName(spanName.toString())
@@ -152,16 +152,18 @@ final class StackdriverV2ExporterHandler extends SpanExporter.Handler {
     return BaseEncoding.base16().lowerCase().encode(traceId.getBytes());
   }
 
+  @SuppressWarnings("deprecation")
   private static Span.TimeEvents toTimeEventsProto(
       TimedEvents<Annotation> annotationTimedEvents,
-      TimedEvents<NetworkEvent> networkEventTimedEvents) {
+      TimedEvents<io.opencensus.trace.NetworkEvent> networkEventTimedEvents) {
     Span.TimeEvents.Builder timeEventsBuilder = Span.TimeEvents.newBuilder();
     timeEventsBuilder.setDroppedAnnotationsCount(annotationTimedEvents.getDroppedEventsCount());
     for (TimedEvent<Annotation> annotation : annotationTimedEvents.getEvents()) {
       timeEventsBuilder.addTimeEvent(toTimeAnnotationProto(annotation));
     }
     timeEventsBuilder.setDroppedMessageEventsCount(networkEventTimedEvents.getDroppedEventsCount());
-    for (TimedEvent<NetworkEvent> networkEvent : networkEventTimedEvents.getEvents()) {
+    for (TimedEvent<io.opencensus.trace.NetworkEvent> networkEvent :
+        networkEventTimedEvents.getEvents()) {
       timeEventsBuilder.addTimeEvent(toTimeMessageEventProto(networkEvent));
     }
     return timeEventsBuilder.build();
@@ -179,10 +181,12 @@ final class StackdriverV2ExporterHandler extends SpanExporter.Handler {
     return timeEventBuilder.build();
   }
 
-  private static TimeEvent toTimeMessageEventProto(TimedEvent<NetworkEvent> timedEvent) {
+  @SuppressWarnings("deprecation")
+  private static TimeEvent toTimeMessageEventProto(
+      TimedEvent<io.opencensus.trace.NetworkEvent> timedEvent) {
     TimeEvent.Builder timeEventBuilder =
         TimeEvent.newBuilder().setTime(toTimestampProto(timedEvent.getTimestamp()));
-    NetworkEvent networkEvent = timedEvent.getEvent();
+    io.opencensus.trace.NetworkEvent networkEvent = timedEvent.getEvent();
     timeEventBuilder.setMessageEvent(
         TimeEvent.MessageEvent.newBuilder()
             .setId(networkEvent.getMessageId())
@@ -193,8 +197,10 @@ final class StackdriverV2ExporterHandler extends SpanExporter.Handler {
     return timeEventBuilder.build();
   }
 
-  private static TimeEvent.MessageEvent.Type toMessageEventTypeProto(NetworkEvent networkEvent) {
-    if (networkEvent.getType() == Type.RECV) {
+  @SuppressWarnings("deprecation")
+  private static TimeEvent.MessageEvent.Type toMessageEventTypeProto(
+      io.opencensus.trace.NetworkEvent networkEvent) {
+    if (networkEvent.getType() == io.opencensus.trace.NetworkEvent.Type.RECV) {
       return MessageEvent.Type.RECEIVED;
     } else {
       return MessageEvent.Type.SENT;
diff --git a/exporters/trace/zipkin/src/main/java/io/opencensus/exporter/trace/zipkin/ZipkinExporterHandler.java b/exporters/trace/zipkin/src/main/java/io/opencensus/exporter/trace/zipkin/ZipkinExporterHandler.java
index c724bbae..3ef27840 100644
--- a/exporters/trace/zipkin/src/main/java/io/opencensus/exporter/trace/zipkin/ZipkinExporterHandler.java
+++ b/exporters/trace/zipkin/src/main/java/io/opencensus/exporter/trace/zipkin/ZipkinExporterHandler.java
@@ -26,7 +26,6 @@ import io.opencensus.common.Scope;
 import io.opencensus.common.Timestamp;
 import io.opencensus.trace.Annotation;
 import io.opencensus.trace.AttributeValue;
-import io.opencensus.trace.NetworkEvent;
 import io.opencensus.trace.Sampler;
 import io.opencensus.trace.SpanContext;
 import io.opencensus.trace.SpanId;
@@ -54,6 +53,7 @@ import zipkin2.Span;
 import zipkin2.codec.SpanBytesEncoder;
 import zipkin2.reporter.Sender;
 
+// TODO(hailongwen): remove the usage of `NetworkEvent` in the future.
 final class ZipkinExporterHandler extends SpanExporter.Handler {
   private static final Tracer tracer = Tracing.getTracer();
   private static final Sampler probabilitySpampler = Samplers.probabilitySampler(0.0001);
@@ -106,6 +106,7 @@ final class ZipkinExporterHandler extends SpanExporter.Handler {
     return builder.build();
   }
 
+  @SuppressWarnings("deprecation")
   static Span generateSpan(SpanData spanData, Endpoint localEndpoint) {
     SpanContext context = spanData.getContext();
     long startTimestamp = toEpochMicros(spanData.getStartTimestamp());
@@ -147,7 +148,8 @@ final class ZipkinExporterHandler extends SpanExporter.Handler {
           toEpochMicros(annotation.getTimestamp()), annotation.getEvent().getDescription());
     }
 
-    for (TimedEvent<NetworkEvent> networkEvent : spanData.getNetworkEvents().getEvents()) {
+    for (TimedEvent<io.opencensus.trace.NetworkEvent> networkEvent :
+        spanData.getNetworkEvents().getEvents()) {
       spanBuilder.addAnnotation(
           toEpochMicros(networkEvent.getTimestamp()), networkEvent.getEvent().getType().name());
     }
diff --git a/findbugs-exclude.xml b/findbugs-exclude.xml
index 9a9c563c..b951a8cc 100644
--- a/findbugs-exclude.xml
+++ b/findbugs-exclude.xml
@@ -21,5 +21,9 @@
     <!-- Reason: It conflicts with Checker Framework null analysis. -->
     <Bug pattern="NP_METHOD_PARAMETER_TIGHTENS_ANNOTATION"/>
   </Match>
-
+  <Match>
+    <!-- Reason: BaseMessageEvent only has two visible subclasses. -->
+    <Bug pattern="BC_UNCONFIRMED_CAST"/>
+    <Class name="io.opencensus.internal.BaseMessageEventUtil" />
+  </Match>
 </FindBugsFilter>
diff --git a/impl_core/src/main/java/io/opencensus/implcore/trace/SpanImpl.java b/impl_core/src/main/java/io/opencensus/implcore/trace/SpanImpl.java
index 8ce863e7..20dde75d 100644
--- a/impl_core/src/main/java/io/opencensus/implcore/trace/SpanImpl.java
+++ b/impl_core/src/main/java/io/opencensus/implcore/trace/SpanImpl.java
@@ -29,7 +29,6 @@ import io.opencensus.trace.Annotation;
 import io.opencensus.trace.AttributeValue;
 import io.opencensus.trace.EndSpanOptions;
 import io.opencensus.trace.Link;
-import io.opencensus.trace.NetworkEvent;
 import io.opencensus.trace.Span;
 import io.opencensus.trace.SpanContext;
 import io.opencensus.trace.SpanId;
@@ -50,6 +49,7 @@ import javax.annotation.Nullable;
 import javax.annotation.concurrent.GuardedBy;
 import javax.annotation.concurrent.ThreadSafe;
 
+// TODO(hailongwen): remove the usage of `NetworkEvent` in the future.
 /** Implementation for the {@link Span} class. */
 @ThreadSafe
 public final class SpanImpl extends Span implements Element<SpanImpl> {
@@ -84,7 +84,8 @@ public final class SpanImpl extends Span implements Element<SpanImpl> {
   // List of recorded network events.
   @GuardedBy("this")
   @Nullable
-  private TraceEvents<EventWithNanoTime<NetworkEvent>> networkEvents;
+  @SuppressWarnings("deprecation")
+  private TraceEvents<EventWithNanoTime<io.opencensus.trace.NetworkEvent>> networkEvents;
   // List of recorded links to parent and child spans.
   @GuardedBy("this")
   @Nullable
@@ -238,7 +239,8 @@ public final class SpanImpl extends Span implements Element<SpanImpl> {
               : SpanData.Attributes.create(attributes, attributes.getNumberOfDroppedAttributes());
       SpanData.TimedEvents<Annotation> annotationsSpanData =
           createTimedEvents(getInitializedAnnotations(), timestampConverter);
-      SpanData.TimedEvents<NetworkEvent> networkEventsSpanData =
+      @SuppressWarnings("deprecation")
+      SpanData.TimedEvents<io.opencensus.trace.NetworkEvent> networkEventsSpanData =
           createTimedEvents(getInitializedNetworkEvents(), timestampConverter);
       SpanData.Links linksSpanData =
           links == null
@@ -327,7 +329,8 @@ public final class SpanImpl extends Span implements Element<SpanImpl> {
   }
 
   @Override
-  public void addNetworkEvent(NetworkEvent networkEvent) {
+  @SuppressWarnings("deprecation")
+  public void addNetworkEvent(io.opencensus.trace.NetworkEvent networkEvent) {
     if (!getOptions().contains(Options.RECORD_EVENTS)) {
       return;
     }
@@ -338,7 +341,7 @@ public final class SpanImpl extends Span implements Element<SpanImpl> {
       }
       getInitializedNetworkEvents()
           .addEvent(
-              new EventWithNanoTime<NetworkEvent>(
+              new EventWithNanoTime<io.opencensus.trace.NetworkEvent>(
                   clock.nowNanos(), checkNotNull(networkEvent, "networkEvent")));
     }
   }
@@ -409,10 +412,12 @@ public final class SpanImpl extends Span implements Element<SpanImpl> {
   }
 
   @GuardedBy("this")
-  private TraceEvents<EventWithNanoTime<NetworkEvent>> getInitializedNetworkEvents() {
+  @SuppressWarnings("deprecation")
+  private TraceEvents<EventWithNanoTime<io.opencensus.trace.NetworkEvent>>
+      getInitializedNetworkEvents() {
     if (networkEvents == null) {
       networkEvents =
-          new TraceEvents<EventWithNanoTime<NetworkEvent>>(
+          new TraceEvents<EventWithNanoTime<io.opencensus.trace.NetworkEvent>>(
               traceParams.getMaxNumberOfNetworkEvents());
     }
     return networkEvents;