Skip to content

Commit 4c5d278

Browse files
westarlewestarle
committed
style(gax-internal): Update doc comments in observability.rs
1 parent 5981c19 commit 4c5d278

File tree

1 file changed

+111
-37
lines changed

1 file changed

+111
-37
lines changed

‎src/gax-internal/src/observability.rs‎

Lines changed: 111 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -20,45 +20,83 @@ use gax::options::RequestOptions;
2020
// OpenTelemetry Semantic Convention Keys
2121
// See https://opentelemetry.io/docs/specs/semconv/http/http-spans/
2222

23-
/// Span Kind for OpenTelemetry interop. Always CLIENT for a span representing an outbound HTTP request.
23+
/// Span Kind for OpenTelemetry interop.
24+
///
25+
/// Always "Client" for a span representing an outbound HTTP request.
2426
const KEY_OTEL_KIND: &str = "otel.kind";
25-
/// Span Name for OpenTelemetry interop. Recommended to be "{http.request.method} {url.template}" if url.template is available, otherwise "{http.request.method}".
27+
/// Span Name for OpenTelemetry interop.
28+
///
29+
/// If `url.template` is available use "{http.request.method} {url.template}", otherwise use "{http.request.method}".
2630
const KEY_OTEL_NAME: &str = "otel.name";
27-
/// Span Status for OpenTelemetry interop. Set to Error in the event of an unrecoverable error, for example network error, 5xx status codes. Unset otherwise (including 4xx codes for CLIENT spans).
31+
/// Span Status for OpenTelemetry interop.
32+
///
33+
/// Use "Error" for unrecoverable errors like network issues or 5xx status codes.
34+
/// Otherwise, leave "Unset" (including for 4xx codes on CLIENT spans).
2835
const KEY_OTEL_STATUS: &str = "otel.status";
2936

30-
/// Which RPC system is being used. Set to "http" for REST calls.
37+
/// The RPC system used.
38+
///
39+
/// Always "http" for REST calls.
3140
const KEY_RPC_SYSTEM: &str = "rpc.system";
32-
/// The HTTP request method, for example GET; POST; HEAD.
41+
/// The HTTP request method.
42+
///
43+
/// Examples: GET, POST, HEAD.
3344
const KEY_HTTP_REQUEST_METHOD: &str = "http.request.method";
34-
/// The actual destination host name or IP address. May differ from the URL's host if overridden, for example myservice.googleapis.com; myservice-staging.sandbox.googleapis.com; 10.0.0.1.
45+
/// The destination host name or IP address.
46+
///
47+
/// Examples: myservice.googleapis.com, myservice-staging.sandbox.googleapis.com, 10.0.0.1
3548
const KEY_SERVER_ADDRESS: &str = "server.address";
36-
/// The actual destination port number. May differ from the URL's port if overridden, for example 443; 8080.
49+
/// The destination port number.
50+
///
51+
/// Examples: 443, 8080
3752
const KEY_SERVER_PORT: &str = "server.port";
38-
/// The absolute URL of the request, for example https://www.foo.bar/search?q=OpenTelemetry.
53+
/// The absolute URL of the request.
54+
///
55+
/// Example: https://www.foo.bar/search?q=OpenTelemetry
3956
const KEY_URL_FULL: &str = "url.full";
40-
/// The URI scheme component identifying the used protocol, for example http; https.
57+
/// The URI scheme component.
58+
///
59+
/// Examples: http, https
4160
const KEY_URL_SCHEME: &str = "url.scheme";
42-
/// The low-cardinality template of the absolute path, for example /v2/locations/{location}/projects/{project}/.
61+
/// The low-cardinality template of the absolute path.
62+
///
63+
/// Example: /v2/locations/{location}/projects/{project}/
4364
const KEY_URL_TEMPLATE: &str = "url.template";
44-
/// The nominal domain from the original URL, representing the intended service, for example myservice.googleapis.com.
65+
/// The nominal domain from the original URL.
66+
///
67+
/// Example: myservice.googleapis.com
4568
const KEY_URL_DOMAIN: &str = "url.domain";
4669

47-
/// The numeric HTTP response status code, for example 200; 404; 500.
70+
/// The numeric HTTP response status code.
71+
///
72+
/// Examples: 200, 404, 500
4873
const KEY_HTTP_RESPONSE_STATUS_CODE: &str = "http.response.status_code";
49-
/// A low cardinality a class of error the operation ended with.
74+
/// A low-cardinality classification of the error.
75+
///
76+
/// For HTTP status codes >= 400, this is the status code as a string.
77+
/// For network errors, use a short identifier like TIMEOUT, CONNECTION_ERROR.
5078
const KEY_ERROR_TYPE: &str = "error.type";
51-
/// The ordinal number of times this request has been resent (e.g., due to retries or redirects). None for the first attempt.
79+
/// The ordinal number of times this request has been resent.
80+
///
81+
/// None for the first attempt.
5282
const KEY_HTTP_REQUEST_RESEND_COUNT: &str = "http.request.resend_count";
5383

5484
// Custom GCP Attributes
55-
/// Identifies the Google Cloud service, for example appengine; run; firestore.
85+
/// The Google Cloud service name.
86+
///
87+
/// Examples: appengine, run, firestore
5688
const KEY_GCP_CLIENT_SERVICE: &str = "gcp.client.service";
57-
/// The version of the client library, for example v1.0.2.
89+
/// The client library version.
90+
///
91+
/// Example: v1.0.2
5892
const KEY_GCP_CLIENT_VERSION: &str = "gcp.client.version";
59-
/// The repository of the client library. Always "googleapis/google-cloud-rust".
93+
/// The client library repository.
94+
///
95+
/// Always "googleapis/google-cloud-rust".
6096
const KEY_GCP_CLIENT_REPO: &str = "gcp.client.repo";
61-
/// The crate name of the client library, for example google-cloud-storage.
97+
/// The client library crate name.
98+
///
99+
/// Example: google-cloud-storage
62100
const KEY_GCP_CLIENT_ARTIFACT: &str = "gcp.client.artifact";
63101

64102
#[derive(Debug, Clone, PartialEq)]
@@ -88,48 +126,84 @@ impl OtelStatus {
88126
#[derive(Debug, Clone)]
89127
pub(crate) struct HttpSpanInfo {
90128
// Attributes for OpenTelemetry SDK interop
91-
/// Span Kind for OpenTelemetry interop. Always CLIENT for a span representing an outbound HTTP request.
129+
/// The span kind for OpenTelemetry interop.
130+
///
131+
/// Always "Client" for a span representing an outbound HTTP request.
92132
otel_kind: String,
93-
/// Span Name for OpenTelemetry interop. Recommended to be "{http.request.method} {url.template}" if url.template is available, otherwise "{http.request.method}".
133+
/// The span name for OpenTelemetry interop.
134+
///
135+
/// If `url.template` is available use "{http.request.method} {url.template}", otherwise use "{http.request.method}".
94136
otel_name: String,
95-
/// Span Status for OpenTelemetry interop. Set to Error in the event of an unrecoverable error, for example network error, 5xx status codes. Unset otherwise (including 4xx codes for CLIENT spans).
137+
/// The span status for OpenTelemetry interop.
138+
///
139+
/// Use "Error" for unrecoverable errors like network issues or 5xx status codes.
140+
/// Otherwise, leave "Unset" (including for 4xx codes on CLIENT spans).
96141
otel_status: OtelStatus,
97142

98143
// OpenTelemetry Semantic Conventions
99-
/// Which RPC system is being used. Set to "http" for REST calls.
144+
/// The RPC system used.
145+
///
146+
/// Always "http" for REST calls.
100147
rpc_system: String,
101-
/// The HTTP request method, for example GET; POST; HEAD.
148+
/// The HTTP request method.
149+
///
150+
/// Examples: GET, POST, HEAD.
102151
http_request_method: String,
103-
/// The actual destination host name or IP address. May differ from the URL's host if overridden, for example myservice.googleapis.com; myservice-staging.sandbox.googleapis.com; 10.0.0.1.
152+
/// The destination host name or IP address.
153+
///
154+
/// Examples: myservice.googleapis.com, myservice-staging.sandbox.googleapis.com, 10.0.0.1
104155
server_address: String,
105-
/// The actual destination port number. May differ from the URL's port if overridden, for example 443; 8080.
156+
/// The destination port number.
157+
///
158+
/// Examples: 443, 8080
106159
server_port: i64,
107-
/// The absolute URL of the request, for example https://www.foo.bar/search?q=OpenTelemetry.
160+
/// The absolute URL of the request.
161+
///
162+
/// Example: https://www.foo.bar/search?q=OpenTelemetry
108163
url_full: String,
109-
/// The URI scheme component identifying the used protocol, for example http; https.
164+
/// The URI scheme component.
165+
///
166+
/// Examples: http, https
110167
url_scheme: Option<String>,
111-
/// The low-cardinality template of the absolute path, for example /v2/locations/{location}/projects/{project}/.
168+
/// The low-cardinality template of the absolute path.
169+
///
170+
/// Example: /v2/locations/{location}/projects/{project}/
112171
url_template: Option<String>,
113-
/// The nominal domain from the original URL, representing the intended service, for example myservice.googleapis.com.
172+
/// The nominal domain from the original URL.
173+
///
174+
/// Example: myservice.googleapis.com
114175
url_domain: Option<String>,
115176

116-
/// The numeric HTTP response status code, for example 200; 404; 500.
177+
/// The numeric HTTP response status code.
178+
///
179+
/// Examples: 200, 404, 500
117180
http_response_status_code: Option<i64>,
118-
/// A low cardinality a class of error the operation ended with.
181+
/// A low-cardinality classification of the error.
182+
///
119183
/// For HTTP status codes >= 400, this is the status code as a string.
120-
/// For network errors, a short identifier like TIMEOUT, CONNECTION_ERROR.
184+
/// For network errors, use a short identifier like TIMEOUT, CONNECTION_ERROR.
121185
error_type: Option<String>,
122-
/// The ordinal number of times this request has been resent (e.g., due to retries or redirects). None for the first attempt.
186+
/// The ordinal number of times this request has been resent.
187+
///
188+
/// None for the first attempt.
123189
http_request_resend_count: Option<i64>,
124190

125191
// Custom GCP Attributes
126-
/// Identifies the Google Cloud service, for example appengine; run; firestore.
192+
/// The Google Cloud service name.
193+
///
194+
/// Examples: appengine, run, firestore
127195
gcp_client_service: Option<String>,
128-
/// The version of the client library, for example v1.0.2.
196+
/// The client library version.
197+
///
198+
/// Example: v1.0.2
129199
gcp_client_version: Option<String>,
130-
/// The repository of the client library. Always "googleapis/google-cloud-rust".
200+
/// The client library repository.
201+
///
202+
/// Always "googleapis/google-cloud-rust".
131203
gcp_client_repo: String,
132-
/// The crate name of the client library, for example google-cloud-storage.
204+
/// The client library crate name.
205+
///
206+
/// Example: google-cloud-storage
133207
gcp_client_artifact: Option<String>,
134208
}
135209

0 commit comments

Comments
 (0)