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 */ streamClosed(Status status)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 */ outboundMessage(int seqNo)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 */ inboundMessage(int seqNo)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 */ outboundMessageSent(int seqNo, long optionalWireSize, long optionalUncompressedSize)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 */ inboundMessageRead(int seqNo, long optionalWireSize, long optionalUncompressedSize)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 */ outboundWireSize(long bytes)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 */ outboundUncompressedSize(long bytes)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 */ inboundWireSize(long bytes)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 */ inboundUncompressedSize(long bytes)107 public void inboundUncompressedSize(long bytes) { 108 } 109 } 110