1 // 2 // 3 // Copyright 2021 gRPC authors. 4 // 5 // Licensed under the Apache License, Version 2.0 (the "License"); 6 // you may not use this file except in compliance with the License. 7 // You may obtain a copy of the License at 8 // 9 // http://www.apache.org/licenses/LICENSE-2.0 10 // 11 // Unless required by applicable law or agreed to in writing, software 12 // distributed under the License is distributed on an "AS IS" BASIS, 13 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 // See the License for the specific language governing permissions and 15 // limitations under the License. 16 // 17 // 18 19 #ifndef GRPC_CORE_LIB_CHANNEL_CALL_TRACER_H 20 #define GRPC_CORE_LIB_CHANNEL_CALL_TRACER_H 21 22 #include <grpc/support/port_platform.h> 23 24 #include "absl/strings/string_view.h" 25 26 #include "src/core/lib/channel/channel_stack.h" 27 #include "src/core/lib/transport/byte_stream.h" 28 #include "src/core/lib/transport/metadata_batch.h" 29 30 namespace grpc_core { 31 32 // Interface for a tracer that records activities on a call. Actual attempts for 33 // this call are traced with CallAttemptTracer after invoking RecordNewAttempt() 34 // on the CallTracer object. 35 class CallTracer { 36 public: 37 // Interface for a tracer that records activities on a particular call 38 // attempt. 39 // (A single RPC can have multiple attempts due to retry/hedging policies or 40 // as transparent retry attempts.) 41 class CallAttemptTracer { 42 public: ~CallAttemptTracer()43 virtual ~CallAttemptTracer() {} 44 // Please refer to `grpc_transport_stream_op_batch_payload` for details on 45 // arguments. 46 virtual void RecordSendInitialMetadata( 47 grpc_metadata_batch* send_initial_metadata, uint32_t flags) = 0; 48 // TODO(yashkt): We are using gpr_atm here instead of absl::string_view 49 // since that's what the transport API uses, and performing an atomic load 50 // is unnecessary if the census tracer does not need it at present. Fix this 51 // when the transport API changes. 52 virtual void RecordOnDoneSendInitialMetadata(gpr_atm* peer_string) = 0; 53 virtual void RecordSendTrailingMetadata( 54 grpc_metadata_batch* send_trailing_metadata) = 0; 55 virtual void RecordSendMessage(const ByteStream& send_message) = 0; 56 // The `RecordReceivedInitialMetadata()` and `RecordReceivedMessage()` 57 // methods should only be invoked when the metadata/message was 58 // successfully received, i.e., without any error. 59 virtual void RecordReceivedInitialMetadata( 60 grpc_metadata_batch* recv_initial_metadata, uint32_t flags) = 0; 61 virtual void RecordReceivedMessage(const ByteStream& recv_message) = 0; 62 virtual void RecordReceivedTrailingMetadata( 63 absl::Status status, grpc_metadata_batch* recv_trailing_metadata, 64 const grpc_transport_stream_stats& transport_stream_stats) = 0; 65 virtual void RecordCancel(grpc_error_handle cancel_error) = 0; 66 // Should be the last API call to the object. Once invoked, the tracer 67 // library is free to destroy the object. 68 virtual void RecordEnd(const gpr_timespec& latency) = 0; 69 }; 70 ~CallTracer()71 virtual ~CallTracer() {} 72 73 // Records a new attempt for the associated call. \a transparent denotes 74 // whether the attempt is being made as a transparent retry or as a 75 // non-transparent retry/heding attempt. (There will be at least one attempt 76 // even if the call is not being retried.) The `CallTracer` object retains 77 // ownership to the newly created `CallAttemptTracer` object. RecordEnd() 78 // serves as an indication that the call stack is done with all API calls, and 79 // the tracer library is free to destroy it after that. 80 virtual CallAttemptTracer* StartNewAttempt(bool is_transparent_retry) = 0; 81 }; 82 83 } // namespace grpc_core 84 85 #endif // GRPC_CORE_LIB_CHANNEL_CALL_TRACER_H 86