tremor_otelapis/

lib.rs

// Copyright 2020-2021, The Tremor Team
//
// 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.

//! The code in the `gen` folder was seeded by [`tonic-build`].
//!
//! The code in the `src` folder extends the generated source with utility
//! code to allow for convenient usage and definition of tonic-based gRPC
//! servers. Specifically, this library is designed for use by the Tremor Project
//! but has no dependencies on tremor and can be used standalone.
//!
//! This library does not provide an API or SDK designed for use as a tracing
//! facility. The official [OpenTelemetry Rust](https://github.com/open-telemetry/opentelemetry-rust) project
//! is a complete OpenTelemetry SDK designed for that purpose. It uses the same
//! underlying protocol buffer definitions and will be a better target for projects that
//! require OpenTelemetry based observability instrumentation and iteroperability with
//! the wider observability ecosystem through third party crates.
//!
//! This library is designed for system integration and interoperability and is not
//! recommended for use as a tracing SDK or for instrumentation as that is well covered
//! already by the OpenTelemetry Rust crate. For instrumentation, use the official crate.
//!
//! For those projects that need basic interworking, interoperability or integration with
//! OpenTelemetry based systems at a wire level, this project may be useful.
//!
//! ## Example
//! The complete code can be found [here](https://github.com/tremor-rs/tremor-otelapis).
//!
//! Cargo.toml:
//! ```toml
//! [dependencies]
//! tremor-otelapis = { version = "0.1", features = ["otel-all"] }
//! tonic = { version = "0.8.2", features = ["tls"] }
//! prost = "0.11"
//! prost-types = "0.11"
//! tokio = { version = "1.1", features = ["rt-multi-thread", "time", "fs", "macros"] }
//! ```
//!
//! Example OpenTelemetry Log client. Note that clients simply use the generated
//! client stub code from `tonic-build`. This library adds no extra utility or
//! convenience.
//!
//! ```ignore
//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
//!     let channel = Endpoint::from_static("http://0.0.0.0:4316")
//!         .connect()
//!         .await?;
//!
//!     let mut client = LogsServiceClient::new(channel);
//!
//!     let resource_logs = ResourceLogs {
//!         ...
//!     };
//!
//!     client
//!         .export(ExportLogsServiceRequest {
//!             resource_logs: vec![resource_logs],
//!         })
//!         .await?;
//!
//!     Ok(())
//! }
//! ```
//!
//! Example OpenTelemetry Log Server. Note that we use utility code
//! to expose the server side functionality. We pass through the generated
//! Protocol Buffer message data binding generated code unadorned. The
//! data bindings for protocol buffer messages are generated by `tonic-build`.
//! The `tonic-build` in turns builds on `prost-build`.
//!
//! ```ignore
//! fn on_logs(
//!     request: tonic::Request<ExportLogsServiceRequest>,
//! ) -> Result<tonic::Response<ExportLogsServiceResponse>, tonic::Status> {
//!     println!("Got a request from {:?}", request.remote_addr());
//!     let reply = ExportLogsServiceResponse::default();
//!     Ok(tonic::Response::new(reply))
//! }
//!
//! #[tokio::main]
//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
//!     let addr = "0.0.0.0:4317".parse()?;
//!     let svc = otelapis::logs::make_service(Box::new(on_logs));
//!     Server::builder().add_service(svc).serve(addr).await?;
//!
//!     Ok(())
//! }
//! ```
//!
//! [`otelapis`]: https://github.com/open-telemetry/opentelemetry-specification
//! [`tonic-build`]: https://github.com/hyperium/tonic/tree/master/tonic-build
//!

#![deny(warnings)] // this cannot be `forbid`, because the generated code uses `allow`
#![deny(
    clippy::all,
    clippy::unwrap_used,
    clippy::unnecessary_unwrap,
    missing_docs
    // clippy::pedantic - this makes the generated code unhappy
)]

extern crate prost;

mod otelapis;

/// Common facilities and conveniences
pub mod common;

pub use otelapis::opentelemetry;

#[cfg(feature = "otel-trace")]
/// This module defines a skeleton implementation of the open telemetry
/// collector tracing service
///
pub mod trace;

/// This module defines a skeleton implementation of the open telemetry
/// collector logging service
///
#[cfg(feature = "otel-logs")]
pub mod logs;

/// This module defines a skeleton implementation of the open telemetry
/// collector metrics service
///
#[cfg(feature = "otel-metrics")]
pub mod metrics;

/// A unified set of services that provide log, metrics and trace events
#[cfg(feature = "otel-all")]
pub mod all;

#[cfg(test)]
mod test {
    use crate::opentelemetry::proto::collector::{
        logs::v1::{ExportLogsPartialSuccess, ExportLogsServiceResponse},
        metrics::v1::{ExportMetricsPartialSuccess, ExportMetricsServiceResponse},
        trace::v1::{ExportTracePartialSuccess, ExportTraceServiceResponse},
    };

    use super::common::FallibleOtelResponse;

    #[test]
    pub fn make_fallible_error() {
        let mut e = FallibleOtelResponse::new(0, 0, 0, "snot".to_string());
        assert_eq!(e.error_message, "snot".to_string());
        assert_eq!(e.rejected_logs, 0);
        assert_eq!(e.rejected_metrics, 0);
        assert_eq!(e.rejected_spans, 0);
        assert!(e.is_ok());
        e.rejected_logs = 1;
        assert!(!e.is_ok());
        e.rejected_logs = -1;
        assert!(!e.is_ok());
        e.rejected_logs = 0;
        e.rejected_metrics = 1;
        assert!(!e.is_ok());
        e.rejected_metrics = -1;
        assert!(!e.is_ok());
        e.rejected_metrics = 0;
        e.rejected_spans = 1;
        assert!(!e.is_ok());
        e.rejected_spans = -1;
        assert!(!e.is_ok());
    }

    #[test]
    pub fn fallible_from_log_response() {
        let log = ExportLogsServiceResponse {
            partial_success: Some(ExportLogsPartialSuccess {
                rejected_log_records: 1,
                error_message: "beep".to_string(),
            }),
        };
        let e = FallibleOtelResponse::from(log);
        assert_eq!(e.error_message, "beep".to_string());
        assert_eq!(e.rejected_logs, 1);
        assert_eq!(e.rejected_metrics, 0);
        assert_eq!(e.rejected_spans, 0);
    }

    #[test]
    pub fn fallible_from_metric_response() {
        let metric = ExportMetricsServiceResponse {
            partial_success: Some(ExportMetricsPartialSuccess {
                rejected_data_points: 1,
                error_message: "boop".to_string(),
            }),
        };
        let e = FallibleOtelResponse::from(metric);
        assert_eq!(e.error_message, "boop".to_string());
        assert_eq!(e.rejected_logs, 0);
        assert_eq!(e.rejected_metrics, 1);
        assert_eq!(e.rejected_spans, 0);
    }

    #[test]
    pub fn fallible_from_trace_response() {
        let metric = ExportTraceServiceResponse {
            partial_success: Some(ExportTracePartialSuccess {
                rejected_spans: 1,
                error_message: "fleek".to_string(),
            }),
        };
        let e = FallibleOtelResponse::from(metric);
        assert_eq!(e.error_message, "fleek".to_string());
        assert_eq!(e.rejected_logs, 0);
        assert_eq!(e.rejected_metrics, 0);
        assert_eq!(e.rejected_spans, 1);
    }
}