|
1 | | -//! The OTLP Exporter supports exporting logs, metrics and traces in the OTLP |
2 | | -//! format to the OpenTelemetry collector or other compatible backend. |
| 1 | +//! # OpenTelemetry OTLP Exporter |
3 | 2 | //! |
4 | | -//! The OpenTelemetry Collector offers a vendor-agnostic implementation on how |
5 | | -//! to receive, process, and export telemetry data. In addition, it removes |
6 | | -//! the need to run, operate, and maintain multiple agents/collectors in |
7 | | -//! order to support open-source telemetry data formats (e.g. Jaeger, |
8 | | -//! Prometheus, etc.) sending to multiple open-source or commercial back-ends. |
| 3 | +//! The OTLP Exporter enables exporting telemetry data (logs, metrics, and traces) in the |
| 4 | +//! OpenTelemetry Protocol (OTLP) format to compatible backends. These backends include: |
9 | 5 | //! |
10 | | -//! Currently, this crate supports sending telemetry in OTLP |
11 | | -//! via gRPC and http (binary and json). |
| 6 | +//! - OpenTelemetry Collector |
| 7 | +//! - Open-source observability tools (Prometheus, Jaeger, etc.) |
| 8 | +//! - Vendor-specific monitoring platforms |
12 | 9 | //! |
13 | | -//! # Quickstart |
| 10 | +//! This crate supports sending OTLP data via: |
| 11 | +//! - gRPC |
| 12 | +//! - HTTP (binary protobuf or JSON) |
14 | 13 | //! |
15 | | -//! First make sure you have a running version of the opentelemetry collector |
16 | | -//! you want to send data to: |
| 14 | +//! ## Quickstart with OpenTelemetry Collector |
| 15 | +//! |
| 16 | +//! ### HTTP Transport (Port 4318) |
| 17 | +//! |
| 18 | +//! Run the OpenTelemetry Collector: |
17 | 19 | //! |
18 | 20 | //! ```shell |
19 | | -//! $ docker run -p 4317:4317 otel/opentelemetry-collector:latest |
| 21 | +//! $ docker run -p 4318:4318 otel/opentelemetry-collector:latest |
| 22 | +//! ``` |
| 23 | +//! |
| 24 | +//! Configure your application to export traces via HTTP: |
| 25 | +//! |
| 26 | +//! ```no_run |
| 27 | +//! # #[cfg(all(feature = "trace", feature = "http-proto"))] |
| 28 | +//! # { |
| 29 | +//! use opentelemetry::global; |
| 30 | +//! use opentelemetry::trace::Tracer; |
| 31 | +//! use opentelemetry_otlp::Protocol; |
| 32 | +//! use opentelemetry_otlp::WithExportConfig; |
| 33 | +//! |
| 34 | +//! fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync + 'static>> { |
| 35 | +//! // Initialize OTLP exporter using HTTP binary protocol |
| 36 | +//! let otlp_exporter = opentelemetry_otlp::SpanExporter::builder() |
| 37 | +//! .with_http() |
| 38 | +//! .with_protocol(Protocol::HttpBinary) |
| 39 | +//! .build()?; |
| 40 | +//! |
| 41 | +//! // Create a tracer provider with the exporter |
| 42 | +//! let _ = opentelemetry_sdk::trace::SdkTracerProvider::builder() |
| 43 | +//! .with_simple_exporter(otlp_exporter) |
| 44 | +//! .build(); |
| 45 | +//! |
| 46 | +//! // Get a tracer and create spans |
| 47 | +//! let tracer = global::tracer("my_tracer"); |
| 48 | +//! tracer.in_span("doing_work", |_cx| { |
| 49 | +//! // Your application logic here... |
| 50 | +//! }); |
| 51 | +//! |
| 52 | +//! Ok(()) |
| 53 | +//! # } |
| 54 | +//! } |
20 | 55 | //! ``` |
21 | 56 | //! |
22 | | -//! Then create a new `Exporter`, and `Provider` with the recommended defaults to start exporting |
23 | | -//! telemetry. |
| 57 | +//! ### gRPC Transport (Port 4317) |
| 58 | +//! |
| 59 | +//! Run the OpenTelemetry Collector: |
24 | 60 | //! |
25 | | -//! You will have to build a OTLP exporter first. Create the correct exporter based on the signal |
26 | | -//! you are looking to export `SpanExporter::builder()`, `MetricExporter::builder()`, |
27 | | -//! `LogExporter::builder()` respectively for traces, metrics, and logs. |
| 61 | +//! ```shell |
| 62 | +//! $ docker run -p 4317:4317 otel/opentelemetry-collector:latest |
| 63 | +//! ``` |
28 | 64 | //! |
29 | | -//! Once you have the exporter, you can create your `Provider` by starting with `TracerProvider::builder()`, |
30 | | -//! `SdkMeterProvider::builder()`, and `LoggerProvider::builder()` respectively for traces, metrics, and logs. |
| 65 | +//! Configure your application to export traces via gRPC: |
31 | 66 | //! |
32 | 67 | //! ```no_run |
33 | 68 | //! # #[cfg(all(feature = "trace", feature = "grpc-tonic"))] |
|
36 | 71 | //! use opentelemetry::trace::Tracer; |
37 | 72 | //! |
38 | 73 | //! fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync + 'static>> { |
39 | | -//! // First, create a OTLP exporter builder. Configure it as you need. |
40 | | -//! let otlp_exporter = opentelemetry_otlp::SpanExporter::builder().with_tonic().build()?; |
41 | | -//! // Then pass it into provider builder |
| 74 | +//! // Initialize OTLP exporter using gRPC (Tonic) |
| 75 | +//! let otlp_exporter = opentelemetry_otlp::SpanExporter::builder() |
| 76 | +//! .with_tonic() |
| 77 | +//! .build()?; |
| 78 | +//! |
| 79 | +//! // Create a tracer provider with the exporter |
42 | 80 | //! let _ = opentelemetry_sdk::trace::SdkTracerProvider::builder() |
43 | 81 | //! .with_simple_exporter(otlp_exporter) |
44 | 82 | //! .build(); |
| 83 | +//! |
| 84 | +//! // Get a tracer and create spans |
45 | 85 | //! let tracer = global::tracer("my_tracer"); |
46 | | -//! tracer.in_span("doing_work", |cx| { |
47 | | -//! // Traced app logic here... |
| 86 | +//! tracer.in_span("doing_work", |_cx| { |
| 87 | +//! // Your application logic here... |
48 | 88 | //! }); |
49 | 89 | //! |
50 | 90 | //! Ok(()) |
51 | | -//! # } |
| 91 | +//! # } |
52 | 92 | //! } |
53 | 93 | //! ``` |
54 | 94 | //! |
| 95 | +//! ## Using with Jaeger |
| 96 | +//! |
| 97 | +//! Jaeger natively supports the OTLP protocol, making it easy to send traces directly: |
| 98 | +//! |
| 99 | +//! ```shell |
| 100 | +//! $ docker run -p 16686:16686 -p 4317:4317 -e COLLECTOR_OTLP_ENABLED=true jaegertracing/all-in-one:latest |
| 101 | +//! ``` |
| 102 | +//! |
| 103 | +//! After running your application configured with the OTLP exporter, view traces at: |
| 104 | +//! `http://localhost:16686` |
| 105 | +//! |
| 106 | +//! ## Using with Prometheus (TODO) |
| 107 | +//! ## Show Logs, Metrics too (TODO) |
| 108 | +//! |
55 | 109 | //! ## Performance |
56 | 110 | //! |
57 | 111 | //! For optimal performance, a batch exporting processor is recommended as the simple |
|
87 | 141 | //! ``` |
88 | 142 | //! |
89 | 143 | //! [`tokio`]: https://tokio.rs |
90 | | -//! [`async-std`]: https://async.rs |
91 | 144 | //! |
92 | 145 | //! # Feature Flags |
93 | 146 | //! The following feature flags can enable exporters for different telemetry signals: |
|
0 commit comments