1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
|
//
// Copyright 2022 gRPC 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.
//
#ifndef GRPCPP_EXT_GCP_OBSERVABILITY_H
#define GRPCPP_EXT_GCP_OBSERVABILITY_H
#include <grpc/support/port_platform.h>
#include "y_absl/status/status.h"
#include "y_absl/status/statusor.h"
#include <grpcpp/impl/grpc_library.h>
namespace grpc {
// GcpObservability objects follow the RAII idiom and help manage the lifetime
// of gRPC Observability data exporting to GCP. `GcpObservability::Init()`
// should be invoked instead to return an `GcpObservability` instance.
// Observability data is flushed at regular intervals, and also when this
// instance goes out of scope and its destructor is invoked.
class GcpObservability {
public:
// Initialize GCP Observability for gRPC.
// This should be called before any other gRPC operations like creating a
// channel, server, credentials etc.
// The return value helps determine whether observability was
// successfully enabled or not. On success, an object of class `Observability`
// is returned. When this object goes out of scope, GCP Observability stats,
// tracing and logging data is flushed. On failure, the status message can be
// used to determine the cause of failure. It is up to the applications to
// either crash on failure, or continue without GCP observability being
// enabled. The status codes do not have any special meaning at present, and
// users should not make any assumptions based on the status code, other than
// a non-OK status code meaning that observability initialization failed.
//
// The expected usage is to call this at the top (or near the top) in
// main(), and let it go out of scope after all RPCs and activities that we
// want to observe are done. Please look at
// https://github.com/grpc/grpc/blob/master/examples/cpp/gcp_observability/helloworld/greeter_client.cc
// and
// https://github.com/grpc/grpc/blob/master/examples/cpp/gcp_observability/helloworld/greeter_server.cc
// for sample usage.
//
// It is possible for an initialized GcpObservability object to go out of
// scope while RPCs and other gRPC operations are still ongoing. In this case,
// GCP Observability tries to flush all observability data collected till that
// point.
//
// Note that this is a blocking call which properly sets up gRPC Observability
// to work with GCP and might take a few seconds to return. Similarly, the
// destruction of a non-moved-from `Observability` object is also blocking
// since it flushes the observability data to GCP.
//
// As an implementation detail, this properly initializes the OpenCensus stats
// and tracing plugin, so applications do not need to perform any additional
// gRPC C++ OpenCensus setup/registration to get GCP Observability for gRPC.
static y_absl::StatusOr<GcpObservability> Init() GRPC_MUST_USE_RESULT;
GcpObservability() = default;
// Move constructor and Move-assignment operator.
// The moved-from object will no longer be valid and will not cause GCP
// Observability stats, tracing and logging data to flush.
GcpObservability(GcpObservability&& other) noexcept;
GcpObservability& operator=(GcpObservability&& other) noexcept;
// Delete copy and copy-assignment operator
GcpObservability(const GcpObservability&) = delete;
GcpObservability& operator=(const GcpObservability&) = delete;
private:
// Helper class that aids in implementing GCP Observability.
// Inheriting from GrpcLibrary makes sure that gRPC is initialized and remains
// initialized for the lifetime of GCP Observability. In the future, when gRPC
// initialization goes away, we might still want to keep gRPC Event Engine
// initialized, just in case, we need to perform some IO operations during
// observability close.
// Note that the lifetime guarantees are only one way, i.e., GcpObservability
// object guarantees that gRPC will not shutdown while the object is still in
// scope, but the other way around does not hold true. Even though that is not
// the expected usage, GCP Observability can shutdown before gRPC shuts down.
// It follows that gRPC should not hold any callbacks from GcpObservability. A
// change in this restriction should go through a design review.
class GcpObservabilityImpl : private internal::GrpcLibrary {
public:
~GcpObservabilityImpl() override;
};
std::unique_ptr<GcpObservabilityImpl> impl_;
};
namespace experimental {
// TODO(yashykt): Delete this after the 1.55 release.
GRPC_DEPRECATED("Use grpc::GcpObservability::Init() instead.")
y_absl::Status GcpObservabilityInit();
GRPC_DEPRECATED("Use grpc::GcpObservability::Init() instead.")
void GcpObservabilityClose();
} // namespace experimental
} // namespace grpc
#endif // GRPCPP_EXT_GCP_OBSERVABILITY_H
|
