Home | History | Annotate | Download | only in grpc 
      1 /*
      2  * Copyright 2017 The gRPC Authors
      3  *
      4  * Licensed under the Apache License, Version 2.0 (the "License");
      5  * you may not use this file except in compliance with the License.
      6  * You may obtain a copy of the License at
      7  *
      8  *     http://www.apache.org/licenses/LICENSE-2.0
      9  *
     10  * Unless required by applicable law or agreed to in writing, software
     11  * distributed under the License is distributed on an "AS IS" BASIS,
     12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
     13  * See the License for the specific language governing permissions and
     14  * limitations under the License.
     15  */
     16 
     17 package io.grpc;
     18 
     19 import javax.annotation.concurrent.ThreadSafe;
     20 
     21 /**
     22  * Listens to events on a stream to collect metrics.
     23  *
     24  * <p>DO NOT MOCK: Use TestStreamTracer. Mocks are not thread-safe
     25  */
     26 @ExperimentalApi("https://github.com/grpc/grpc-java/issues/2861")
     27 @ThreadSafe
     28 public abstract class StreamTracer {
     29   /**
     30    * Stream is closed.  This will be called exactly once.
     31    */
     32   public void streamClosed(Status status) {
     33   }
     34 
     35   /**
     36    * An outbound message has been passed to the stream.  This is called as soon as the stream knows
     37    * about the message, but doesn't have further guarantee such as whether the message is serialized
     38    * or not.
     39    *
     40    * @param seqNo the sequential number of the message within the stream, starting from 0.  It can
     41    *              be used to correlate with {@link #outboundMessageSent} for the same message.
     42    */
     43   public void outboundMessage(int seqNo) {
     44   }
     45 
     46   /**
     47    * An inbound message has been received by the stream.  This is called as soon as the stream knows
     48    * about the message, but doesn't have further guarantee such as whether the message is
     49    * deserialized or not.
     50    *
     51    * @param seqNo the sequential number of the message within the stream, starting from 0.  It can
     52    *              be used to correlate with {@link #inboundMessageRead} for the same message.
     53    */
     54   public void inboundMessage(int seqNo) {
     55   }
     56 
     57   /**
     58    * An outbound message has been serialized and sent to the transport.
     59    *
     60    * @param seqNo the sequential number of the message within the stream, starting from 0.  It can
     61    *              be used to correlate with {@link #outboundMessage(int)} for the same message.
     62    * @param optionalWireSize the wire size of the message. -1 if unknown
     63    * @param optionalUncompressedSize the uncompressed serialized size of the message. -1 if unknown
     64    */
     65   public void outboundMessageSent(int seqNo, long optionalWireSize, long optionalUncompressedSize) {
     66   }
     67 
     68   /**
     69    * An inbound message has been fully read from the transport.
     70    *
     71    * @param seqNo the sequential number of the message within the stream, starting from 0.  It can
     72    *              be used to correlate with {@link #inboundMessage(int)} for the same message.
     73    * @param optionalWireSize the wire size of the message. -1 if unknown
     74    * @param optionalUncompressedSize the uncompressed serialized size of the message. -1 if unknown
     75    */
     76   public void inboundMessageRead(int seqNo, long optionalWireSize, long optionalUncompressedSize) {
     77   }
     78 
     79   /**
     80    * The wire size of some outbound data is revealed. This can only used to record the accumulative
     81    * outbound wire size. There is no guarantee wrt timing or granularity of this method.
     82    */
     83   public void outboundWireSize(long bytes) {
     84   }
     85 
     86   /**
     87    * The uncompressed size of some outbound data is revealed. This can only used to record the
     88    * accumulative outbound uncompressed size. There is no guarantee wrt timing or granularity of
     89    * this method.
     90    */
     91   public void outboundUncompressedSize(long bytes) {
     92   }
     93 
     94   /**
     95    * The wire size of some inbound data is revealed. This can only be used to record the
     96    * accumulative received wire size. There is no guarantee wrt timing or granularity of this
     97    * method.
     98    */
     99   public void inboundWireSize(long bytes) {
    100   }
    101 
    102   /**
    103    * The uncompressed size of some inbound data is revealed. This can only used to record the
    104    * accumulative received uncompressed size. There is no guarantee wrt timing or granularity of
    105    * this method.
    106    */
    107   public void inboundUncompressedSize(long bytes) {
    108   }
    109 }
    110