Skip to content

Commit aee4249

Browse files
authored
docs(proto): add documentation, guard generated types using features (open-telemetry#732)
* docs(proto): add documentation, guard generated types using features * docs(proto): add doc_auto_cfg.
1 parent 0b3b433 commit aee4249

File tree

6 files changed

+50
-15
lines changed

6 files changed

+50
-15
lines changed

opentelemetry-proto/Cargo.toml

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@ required-features = ["with-serde", "gen-protoc"]
2828
[features]
2929
default = []
3030

31-
full = ["gen-tonic", "gen-protoc", "traces", "metrics", "zpages", "build-server", "build-client", "with-serde"]
31+
full = ["gen-tonic", "gen-protoc", "traces", "logs", "metrics", "zpages", "build-server", "build-client", "with-serde"]
3232

3333
# crates used to generate rs files
3434
gen-tonic = ["tonic", "tonic-build", "prost"]
@@ -37,6 +37,7 @@ gen-protoc = ["grpcio", "protobuf"]
3737
# telemetry pillars and functions
3838
traces = []
3939
metrics = []
40+
logs = []
4041
zpages = ["traces"]
4142

4243
# add ons
@@ -48,7 +49,7 @@ build-client = []
4849
grpcio = { version = "0.9", optional = true }
4950
tonic = { version = "0.6.2", optional = true }
5051
prost = { version = "0.9", optional = true }
51-
protobuf = { version = "2.18", optional = true }
52+
protobuf = { version = "2.18", optional = true } # todo: update to 3.0 so we have docs for generated types.
5253
opentelemetry = { version = "0.17", default-features = false, features = ["trace", "metrics"], path = "../opentelemetry" }
5354
futures = { version = "0.3", default-features = false, features = ["std"] }
5455
futures-util = { version = "0.3", default-features = false, features = ["std"] }

opentelemetry-proto/src/lib.rs

Lines changed: 18 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,34 +1,45 @@
1+
#![cfg_attr(doc, feature(doc_auto_cfg))]
12
//! This crate contains generated files from [opentelemetry-proto](https://github.com/open-telemetry/opentelemetry-proto)
23
//! repository and transformation between types from generated files and types defined in [opentelemetry](https://github.com/open-telemetry/opentelemetry-rust/tree/main/opentelemetry)
34
//!
45
//! Based on the build tool needed, users can choose to generate files using [tonic](https://github.com/hyperium/tonic)
56
//! or [grpcio](https://github.com/tikv/grpc-rs).
67
//!
8+
//!
79
//! # Feature flags
810
//! `Opentelemetry-proto` includes a set of feature flags to avoid pull in unnecessary dependencies.
911
//! The following is the full list of currently supported features:
1012
//!
13+
//! ## Signals
14+
//! - `traces`: generate types that used in traces. Currently supports `gen-tonic` or `gen-protoc`.
15+
//! - `metrics`: generate types that used in metrics. Currently supports `gen-tonic`.
16+
//! - `logs`: generate types that used in logs. Currently supports `gen-tonic`.
17+
//! - `zpages`: generate types that used in zPages. Currently only tracez related types will be generated. Currently supports `gen-tonic` or `gen-protoc`.
18+
//!
19+
//! ## Creates used to generate files
1120
//! - `gen-tonic`: generate rs files using [tonic](https://github.com/hyperium/tonic) and [prost](https://github.com/tokio-rs/prost).
1221
//! - `gen-protoc`: generate rs files using [grpcio](https://github.com/tikv/grpc-rs).
13-
//! - `traces`: generate types that used in traces.
14-
//! - `metrics`: generate types that used in metrics.
15-
//! - `zpages`: generate types that used in zPages. Currently only tracez related types will be generated.
16-
//! - `build-server`: build grpc service servers if enabled. Only applied to `gen-tonic`.
17-
//! - `build-client`: build grpc service clients if enabled. Only applied to `gen-tonic`.
18-
//! - `with-serde`: add serde annotations to generated types. Only applied to `gen-protoc`.
22+
//!
23+
//! ## Additional configurations
24+
//! - `build-server`: build grpc service servers if enabled. Only applicable to `gen-tonic`.
25+
//! - `build-client`: build grpc service clients if enabled. Only applicable to `gen-tonic`.
26+
//! - `with-serde`: add serde annotations to generated types. Only applicable to `gen-protoc`.
27+
//!
28+
//! ## Misc
1929
//! - `full`: enabled all features above.
2030
//!
2131
//! By default, no feature is enabled.
2232
2333
// proto mod contains file generated by protobuf or other build tools.
24-
// we should manually change it. Thus skip format and lint check.
34+
// we shouldn't manually change it. Thus skip format and lint check.
2535
#[rustfmt::skip]
2636
#[allow(warnings)]
2737
#[doc(hidden)]
2838
mod proto;
2939

3040
#[cfg(feature = "gen-protoc")]
3141
pub use proto::grpcio;
42+
3243
#[cfg(feature = "gen-tonic")]
3344
pub use proto::tonic;
3445

opentelemetry-proto/src/proto.rs

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,49 +1,62 @@
11
#[cfg(feature = "gen-tonic")]
2+
/// Generated files using [`tonic`](https://docs.rs/crate/grpcio) and [`prost`](https://docs.rs/crate/protobuf/latest)
23
pub mod tonic {
4+
/// Service stub and clients
35
pub mod collector {
6+
#[cfg(feature = "logs")]
47
pub mod logs {
58
pub mod v1 {
69
tonic::include_proto!("opentelemetry.proto.collector.logs.v1");
710
}
811
}
912

13+
#[cfg(feature = "metrics")]
1014
pub mod metrics {
1115
pub mod v1 {
1216
tonic::include_proto!("opentelemetry.proto.collector.metrics.v1");
1317
}
1418
}
1519

20+
#[cfg(feature = "traces")]
1621
pub mod trace {
1722
pub mod v1 {
1823
tonic::include_proto!("opentelemetry.proto.collector.trace.v1");
1924
}
2025
}
2126
}
2227

28+
/// Common types used across all signals
2329
pub mod common {
2430
pub mod v1 {
2531
tonic::include_proto!("opentelemetry.proto.common.v1");
2632
}
2733
}
2834

35+
#[cfg(feature = "logs")]
36+
/// Generated types used in logging.
2937
pub mod logs {
3038
pub mod v1 {
3139
tonic::include_proto!("opentelemetry.proto.logs.v1");
3240
}
3341
}
3442

43+
#[cfg(feature = "metrics")]
44+
/// Generated types used in metrics.
3545
pub mod metrics {
3646
pub mod v1 {
3747
tonic::include_proto!("opentelemetry.proto.metrics.v1");
3848
}
3949
}
4050

51+
/// Generated types used in resources.
4152
pub mod resource {
4253
pub mod v1 {
4354
tonic::include_proto!("opentelemetry.proto.resource.v1");
4455
}
4556
}
4657

58+
#[cfg(feature = "traces")]
59+
/// Generated types used in traces.
4760
pub mod trace {
4861
pub mod v1 {
4962
tonic::include_proto!("opentelemetry.proto.trace.v1");
@@ -57,16 +70,25 @@ pub mod tonic {
5770
}
5871

5972
#[cfg(feature = "gen-protoc")]
73+
/// Generated files using [`grpcio`](https://docs.rs/crate/grpcio) and [`protobuf`](https://docs.rs/crate/protobuf/latest)
6074
pub mod grpcio {
6175
pub mod common;
76+
#[cfg(feature = "metrics")]
6277
pub mod metrics;
78+
#[cfg(feature = "metrics")]
6379
pub mod metrics_service;
80+
#[cfg(feature = "metrics")]
6481
pub mod metrics_service_grpc;
6582
pub mod resource;
83+
#[cfg(feature = "traces")]
6684
pub mod trace;
85+
#[cfg(feature = "traces")]
6786
pub mod trace_config;
87+
#[cfg(feature = "traces")]
6888
pub mod trace_service;
89+
#[cfg(feature = "traces")]
6990
pub mod trace_service_grpc;
91+
#[cfg(feature = "zpages")]
7092
pub mod tracez;
7193

7294
pub use crate::transform::common::grpcio::Attributes;

opentelemetry-proto/src/transform/common.rs

Lines changed: 3 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,3 @@
1-
use opentelemetry::sdk::trace::EvictedHashMap;
2-
use opentelemetry::{Array, Value};
3-
41
#[cfg(feature = "traces")]
52
use std::time::{Duration, SystemTime, UNIX_EPOCH};
63

@@ -13,10 +10,10 @@ pub(crate) fn to_nanos(time: SystemTime) -> u64 {
1310

1411
#[cfg(feature = "gen-tonic")]
1512
pub mod tonic {
16-
use super::*;
1713
use crate::proto::tonic::common::v1::{
1814
any_value, AnyValue, ArrayValue, InstrumentationLibrary, KeyValue,
1915
};
16+
use opentelemetry::{sdk::trace::EvictedHashMap, Array, Value};
2017
use std::borrow::Cow;
2118

2219
impl From<opentelemetry::sdk::InstrumentationLibrary> for InstrumentationLibrary {
@@ -28,6 +25,7 @@ pub mod tonic {
2825
}
2926
}
3027

28+
/// Wrapper type for Vec<[`KeyValue`](crate::proto::tonic::common::v1::KeyValue)>
3129
pub struct Attributes(pub ::std::vec::Vec<crate::proto::tonic::common::v1::KeyValue>);
3230

3331
impl From<EvictedHashMap> for Attributes {
@@ -91,8 +89,8 @@ pub mod tonic {
9189

9290
#[cfg(feature = "gen-protoc")]
9391
pub mod grpcio {
94-
use super::*;
9592
use crate::proto::grpcio::common::{AnyValue, ArrayValue, KeyValue};
93+
use opentelemetry::{sdk::trace::EvictedHashMap, Array, Value};
9694
use protobuf::RepeatedField;
9795

9896
pub struct Attributes(pub ::protobuf::RepeatedField<crate::proto::grpcio::common::KeyValue>);

opentelemetry-proto/src/transform/metrics.rs

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,8 @@ pub mod tonic {
1414

1515
use opentelemetry::{Key, Value};
1616

17-
/// Convert Number to target type based on it's NumberKind.
17+
/// Convert [`Number`](opentelemetry::metrics::NumberKind) to target type based
18+
/// on it's [`NumberKind`](opentelemetry::metrics::NumberKind).
1819
pub trait FromNumber {
1920
fn from_number(number: Number, number_kind: &NumberKind) -> Self;
2021
}

scripts/lint.sh

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,7 @@ if rustup component add clippy; then
4343
cargo_feature opentelemetry-dynatrace "metrics,rt-tokio,surf-client,surf/curl-client"
4444
cargo_feature opentelemetry-dynatrace "metrics,rt-async-std"
4545

46+
cargo_feature opentelemetry-proto "default"
4647
cargo_feature opentelemetry-proto "full"
4748
cargo_feature opentelemetry-proto "gen-tonic,traces"
4849
cargo_feature opentelemetry-proto "gen-tonic,traces,with-serde"
@@ -52,5 +53,6 @@ if rustup component add clippy; then
5253
cargo_feature opentelemetry-proto "gen-protoc,traces,with-serde"
5354
cargo_feature opentelemetry-proto "gen-protoc,zpages"
5455
cargo_feature opentelemetry-proto "gen-protoc,zpages,with-serde"
56+
cargo_feature opentelemetry-proto "gen-tonic, logs"
5557

5658
fi

0 commit comments

Comments
 (0)