xref: /aosp_15_r20/external/grpc-grpc/include/grpcpp/ext/otel_plugin.h (revision cc02d7e222339f7a4f6ba5f422e6413f4bd931f2)
1*cc02d7e2SAndroid Build Coastguard Worker //
2*cc02d7e2SAndroid Build Coastguard Worker //
3*cc02d7e2SAndroid Build Coastguard Worker // Copyright 2023 gRPC authors.
4*cc02d7e2SAndroid Build Coastguard Worker //
5*cc02d7e2SAndroid Build Coastguard Worker // Licensed under the Apache License, Version 2.0 (the "License");
6*cc02d7e2SAndroid Build Coastguard Worker // you may not use this file except in compliance with the License.
7*cc02d7e2SAndroid Build Coastguard Worker // You may obtain a copy of the License at
8*cc02d7e2SAndroid Build Coastguard Worker //
9*cc02d7e2SAndroid Build Coastguard Worker //     http://www.apache.org/licenses/LICENSE-2.0
10*cc02d7e2SAndroid Build Coastguard Worker //
11*cc02d7e2SAndroid Build Coastguard Worker // Unless required by applicable law or agreed to in writing, software
12*cc02d7e2SAndroid Build Coastguard Worker // distributed under the License is distributed on an "AS IS" BASIS,
13*cc02d7e2SAndroid Build Coastguard Worker // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14*cc02d7e2SAndroid Build Coastguard Worker // See the License for the specific language governing permissions and
15*cc02d7e2SAndroid Build Coastguard Worker // limitations under the License.
16*cc02d7e2SAndroid Build Coastguard Worker //
17*cc02d7e2SAndroid Build Coastguard Worker //
18*cc02d7e2SAndroid Build Coastguard Worker 
19*cc02d7e2SAndroid Build Coastguard Worker #ifndef GRPCPP_EXT_OTEL_PLUGIN_H
20*cc02d7e2SAndroid Build Coastguard Worker #define GRPCPP_EXT_OTEL_PLUGIN_H
21*cc02d7e2SAndroid Build Coastguard Worker 
22*cc02d7e2SAndroid Build Coastguard Worker #include <stddef.h>
23*cc02d7e2SAndroid Build Coastguard Worker #include <stdint.h>
24*cc02d7e2SAndroid Build Coastguard Worker 
25*cc02d7e2SAndroid Build Coastguard Worker #include <memory>
26*cc02d7e2SAndroid Build Coastguard Worker 
27*cc02d7e2SAndroid Build Coastguard Worker #include "absl/functional/any_invocable.h"
28*cc02d7e2SAndroid Build Coastguard Worker #include "absl/status/status.h"
29*cc02d7e2SAndroid Build Coastguard Worker #include "absl/strings/string_view.h"
30*cc02d7e2SAndroid Build Coastguard Worker #include "opentelemetry/metrics/meter_provider.h"
31*cc02d7e2SAndroid Build Coastguard Worker 
32*cc02d7e2SAndroid Build Coastguard Worker #include <grpc/support/metrics.h>
33*cc02d7e2SAndroid Build Coastguard Worker #include <grpc/support/port_platform.h>
34*cc02d7e2SAndroid Build Coastguard Worker 
35*cc02d7e2SAndroid Build Coastguard Worker namespace grpc {
36*cc02d7e2SAndroid Build Coastguard Worker 
37*cc02d7e2SAndroid Build Coastguard Worker namespace internal {
38*cc02d7e2SAndroid Build Coastguard Worker class OpenTelemetryPluginBuilderImpl;
39*cc02d7e2SAndroid Build Coastguard Worker class OpenTelemetryPlugin;
40*cc02d7e2SAndroid Build Coastguard Worker }  // namespace internal
41*cc02d7e2SAndroid Build Coastguard Worker 
42*cc02d7e2SAndroid Build Coastguard Worker class OpenTelemetryPluginOption {
43*cc02d7e2SAndroid Build Coastguard Worker  public:
44*cc02d7e2SAndroid Build Coastguard Worker   virtual ~OpenTelemetryPluginOption() = default;
45*cc02d7e2SAndroid Build Coastguard Worker };
46*cc02d7e2SAndroid Build Coastguard Worker 
47*cc02d7e2SAndroid Build Coastguard Worker /// The most common way to use this API is -
48*cc02d7e2SAndroid Build Coastguard Worker ///
49*cc02d7e2SAndroid Build Coastguard Worker /// OpenTelemetryPluginBuilder().SetMeterProvider(provider).BuildAndRegister();
50*cc02d7e2SAndroid Build Coastguard Worker ///
51*cc02d7e2SAndroid Build Coastguard Worker /// The set of instruments available are -
52*cc02d7e2SAndroid Build Coastguard Worker /// grpc.client.attempt.started
53*cc02d7e2SAndroid Build Coastguard Worker /// grpc.client.attempt.duration
54*cc02d7e2SAndroid Build Coastguard Worker /// grpc.client.attempt.sent_total_compressed_message_size
55*cc02d7e2SAndroid Build Coastguard Worker /// grpc.client.attempt.rcvd_total_compressed_message_size
56*cc02d7e2SAndroid Build Coastguard Worker /// grpc.server.call.started
57*cc02d7e2SAndroid Build Coastguard Worker /// grpc.server.call.duration
58*cc02d7e2SAndroid Build Coastguard Worker /// grpc.server.call.sent_total_compressed_message_size
59*cc02d7e2SAndroid Build Coastguard Worker /// grpc.server.call.rcvd_total_compressed_message_size
60*cc02d7e2SAndroid Build Coastguard Worker class OpenTelemetryPluginBuilder {
61*cc02d7e2SAndroid Build Coastguard Worker  public:
62*cc02d7e2SAndroid Build Coastguard Worker   using ChannelScope = grpc_core::experimental::StatsPluginChannelScope;
63*cc02d7e2SAndroid Build Coastguard Worker 
64*cc02d7e2SAndroid Build Coastguard Worker   /// Metrics
65*cc02d7e2SAndroid Build Coastguard Worker   static constexpr absl::string_view kClientAttemptStartedInstrumentName =
66*cc02d7e2SAndroid Build Coastguard Worker       "grpc.client.attempt.started";
67*cc02d7e2SAndroid Build Coastguard Worker   static constexpr absl::string_view kClientAttemptDurationInstrumentName =
68*cc02d7e2SAndroid Build Coastguard Worker       "grpc.client.attempt.duration";
69*cc02d7e2SAndroid Build Coastguard Worker   static constexpr absl::string_view
70*cc02d7e2SAndroid Build Coastguard Worker       kClientAttemptSentTotalCompressedMessageSizeInstrumentName =
71*cc02d7e2SAndroid Build Coastguard Worker           "grpc.client.attempt.sent_total_compressed_message_size";
72*cc02d7e2SAndroid Build Coastguard Worker   static constexpr absl::string_view
73*cc02d7e2SAndroid Build Coastguard Worker       kClientAttemptRcvdTotalCompressedMessageSizeInstrumentName =
74*cc02d7e2SAndroid Build Coastguard Worker           "grpc.client.attempt.rcvd_total_compressed_message_size";
75*cc02d7e2SAndroid Build Coastguard Worker   static constexpr absl::string_view kServerCallStartedInstrumentName =
76*cc02d7e2SAndroid Build Coastguard Worker       "grpc.server.call.started";
77*cc02d7e2SAndroid Build Coastguard Worker   static constexpr absl::string_view kServerCallDurationInstrumentName =
78*cc02d7e2SAndroid Build Coastguard Worker       "grpc.server.call.duration";
79*cc02d7e2SAndroid Build Coastguard Worker   static constexpr absl::string_view
80*cc02d7e2SAndroid Build Coastguard Worker       kServerCallSentTotalCompressedMessageSizeInstrumentName =
81*cc02d7e2SAndroid Build Coastguard Worker           "grpc.server.call.sent_total_compressed_message_size";
82*cc02d7e2SAndroid Build Coastguard Worker   static constexpr absl::string_view
83*cc02d7e2SAndroid Build Coastguard Worker       kServerCallRcvdTotalCompressedMessageSizeInstrumentName =
84*cc02d7e2SAndroid Build Coastguard Worker           "grpc.server.call.rcvd_total_compressed_message_size";
85*cc02d7e2SAndroid Build Coastguard Worker 
86*cc02d7e2SAndroid Build Coastguard Worker   OpenTelemetryPluginBuilder();
87*cc02d7e2SAndroid Build Coastguard Worker   ~OpenTelemetryPluginBuilder();
88*cc02d7e2SAndroid Build Coastguard Worker   /// If `SetMeterProvider()` is not called, no metrics are collected.
89*cc02d7e2SAndroid Build Coastguard Worker   OpenTelemetryPluginBuilder& SetMeterProvider(
90*cc02d7e2SAndroid Build Coastguard Worker       std::shared_ptr<opentelemetry::metrics::MeterProvider> meter_provider);
91*cc02d7e2SAndroid Build Coastguard Worker   /// If set, \a target_attribute_filter is called per channel to decide whether
92*cc02d7e2SAndroid Build Coastguard Worker   /// to record the target attribute on client or to replace it with "other".
93*cc02d7e2SAndroid Build Coastguard Worker   /// This helps reduce the cardinality on metrics in cases where many channels
94*cc02d7e2SAndroid Build Coastguard Worker   /// are created with different targets in the same binary (which might happen
95*cc02d7e2SAndroid Build Coastguard Worker   /// for example, if the channel target string uses IP addresses directly).
96*cc02d7e2SAndroid Build Coastguard Worker   OpenTelemetryPluginBuilder& SetTargetAttributeFilter(
97*cc02d7e2SAndroid Build Coastguard Worker       absl::AnyInvocable<bool(absl::string_view /*target*/) const>
98*cc02d7e2SAndroid Build Coastguard Worker           target_attribute_filter);
99*cc02d7e2SAndroid Build Coastguard Worker   /// If set, \a generic_method_attribute_filter is called per call with a
100*cc02d7e2SAndroid Build Coastguard Worker   /// generic method type to decide whether to record the method name or to
101*cc02d7e2SAndroid Build Coastguard Worker   /// replace it with "other". Non-generic or pre-registered methods remain
102*cc02d7e2SAndroid Build Coastguard Worker   /// unaffected. If not set, by default, generic method names are replaced with
103*cc02d7e2SAndroid Build Coastguard Worker   /// "other" when recording metrics.
104*cc02d7e2SAndroid Build Coastguard Worker   OpenTelemetryPluginBuilder& SetGenericMethodAttributeFilter(
105*cc02d7e2SAndroid Build Coastguard Worker       absl::AnyInvocable<bool(absl::string_view /*generic_method*/) const>
106*cc02d7e2SAndroid Build Coastguard Worker           generic_method_attribute_filter);
107*cc02d7e2SAndroid Build Coastguard Worker   // Methods to manipulate which instruments are enabled in the OpenTelemetry
108*cc02d7e2SAndroid Build Coastguard Worker   // Stats Plugin.
109*cc02d7e2SAndroid Build Coastguard Worker   OpenTelemetryPluginBuilder& EnableMetrics(
110*cc02d7e2SAndroid Build Coastguard Worker       absl::Span<const absl::string_view> metric_names);
111*cc02d7e2SAndroid Build Coastguard Worker   OpenTelemetryPluginBuilder& DisableMetrics(
112*cc02d7e2SAndroid Build Coastguard Worker       absl::Span<const absl::string_view> metric_names);
113*cc02d7e2SAndroid Build Coastguard Worker   OpenTelemetryPluginBuilder& DisableAllMetrics();
114*cc02d7e2SAndroid Build Coastguard Worker   /// Add a plugin option to add to the opentelemetry plugin being built. At
115*cc02d7e2SAndroid Build Coastguard Worker   /// present, this type is an opaque type. Ownership of \a option is
116*cc02d7e2SAndroid Build Coastguard Worker   /// transferred when `AddPluginOption` is invoked. A maximum of 64 plugin
117*cc02d7e2SAndroid Build Coastguard Worker   /// options can be added.
118*cc02d7e2SAndroid Build Coastguard Worker   OpenTelemetryPluginBuilder& AddPluginOption(
119*cc02d7e2SAndroid Build Coastguard Worker       std::unique_ptr<OpenTelemetryPluginOption> option);
120*cc02d7e2SAndroid Build Coastguard Worker   /// Records \a optional_label_key on all metrics that provide it.
121*cc02d7e2SAndroid Build Coastguard Worker   OpenTelemetryPluginBuilder& AddOptionalLabel(
122*cc02d7e2SAndroid Build Coastguard Worker       absl::string_view optional_label_key);
123*cc02d7e2SAndroid Build Coastguard Worker   /// Set scope filter to choose which channels are recorded by this plugin.
124*cc02d7e2SAndroid Build Coastguard Worker   /// Server-side recording remains unaffected.
125*cc02d7e2SAndroid Build Coastguard Worker   OpenTelemetryPluginBuilder& SetChannelScopeFilter(
126*cc02d7e2SAndroid Build Coastguard Worker       absl::AnyInvocable<bool(const ChannelScope& /*scope*/) const>
127*cc02d7e2SAndroid Build Coastguard Worker           channel_scope_filter);
128*cc02d7e2SAndroid Build Coastguard Worker   /// Registers a global plugin that acts on all channels and servers running on
129*cc02d7e2SAndroid Build Coastguard Worker   /// the process.
130*cc02d7e2SAndroid Build Coastguard Worker   absl::Status BuildAndRegisterGlobal();
131*cc02d7e2SAndroid Build Coastguard Worker 
132*cc02d7e2SAndroid Build Coastguard Worker  private:
133*cc02d7e2SAndroid Build Coastguard Worker   std::unique_ptr<internal::OpenTelemetryPluginBuilderImpl> impl_;
134*cc02d7e2SAndroid Build Coastguard Worker };
135*cc02d7e2SAndroid Build Coastguard Worker 
136*cc02d7e2SAndroid Build Coastguard Worker namespace experimental {
137*cc02d7e2SAndroid Build Coastguard Worker // TODO(yashykt): Delete this after the 1.62 release.
138*cc02d7e2SAndroid Build Coastguard Worker GRPC_DEPRECATED(
139*cc02d7e2SAndroid Build Coastguard Worker     "Use grpc::OpenTelemetryPluginBuilder instead. The experimental version "
140*cc02d7e2SAndroid Build Coastguard Worker     "will be deleted after the 1.62 release.")
141*cc02d7e2SAndroid Build Coastguard Worker typedef grpc::OpenTelemetryPluginBuilder OpenTelemetryPluginBuilder;
142*cc02d7e2SAndroid Build Coastguard Worker }  // namespace experimental
143*cc02d7e2SAndroid Build Coastguard Worker 
144*cc02d7e2SAndroid Build Coastguard Worker }  // namespace grpc
145*cc02d7e2SAndroid Build Coastguard Worker 
146*cc02d7e2SAndroid Build Coastguard Worker #endif  // GRPCPP_EXT_OTEL_PLUGIN_H
147