Skip to content

Commit 0c19cf5

Browse files
frigus02frigus02
authored
Merge pull request #43 from frigus02/enable-test-without-features
Make cargo test work without metrics feature
2 parents 401daf1 + 0c18fd0 commit 0c19cf5

File tree

7 files changed

+65
-287
lines changed

7 files changed

+65
-287
lines changed

‎Cargo.toml‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -48,14 +48,15 @@ ureq = { version = "2", optional = true }
4848
[dev-dependencies]
4949
async-std = { version = "1.9.0", features = ["attributes"] }
5050
backtrace = "0.3.60"
51+
doc-comment = "0.3.3"
5152
env_logger = "0.9.0"
5253
opentelemetry = { version = "0.16", features = ["rt-tokio"] }
5354
opentelemetry-application-insights = { path = ".", features = ["reqwest-client", "reqwest-blocking-client"] }
5455
rand = "0.8.4"
5556
surf = "2.2.0"
5657
test-case = "1.1.0"
5758
tokio = { version = "1.7.0", features = ["rt", "macros", "process", "time"] }
58-
version-sync = "0.9.2"
59+
version-sync = { version = "0.9.2", default-features = false, features = ["html_root_url_updated", "contains_regex"] }
5960

6061
[badges]
6162
github = { repository = "frigus02/opentelemetry-application-insights", workflow = "CI" }

‎README.md‎

Lines changed: 12 additions & 205 deletions
Original file line numberDiff line numberDiff line change
@@ -1,22 +1,18 @@
1-
[![Crates.io 0.18.0](https://img.shields.io/crates/v/opentelemetry-application-insights.svg)](https://crates.io/crates/opentelemetry-application-insights)
2-
[![Documentation 0.18.0](https://docs.rs/opentelemetry-application-insights/badge.svg)](https://docs.rs/opentelemetry-application-insights)
1+
[![Crates.io](https://img.shields.io/crates/v/opentelemetry-application-insights.svg)](https://crates.io/crates/opentelemetry-application-insights)
2+
[![Documentation](https://docs.rs/opentelemetry-application-insights/badge.svg)](https://docs.rs/opentelemetry-application-insights)
33
[![Workflow Status](https://github.com/frigus02/opentelemetry-application-insights/workflows/CI/badge.svg)](https://github.com/frigus02/opentelemetry-application-insights/actions?query=workflow%3A%22CI%22)
44

55
# opentelemetry-application-insights
66

7-
An [Azure Application Insights] exporter implementation for [OpenTelemetry Rust].
8-
9-
[Azure Application Insights]: https://docs.microsoft.com/en-us/azure/azure-monitor/app/app-insights-overview
10-
[OpenTelemetry Rust]: https://github.com/open-telemetry/opentelemetry-rust
7+
An [Azure Application Insights](https://docs.microsoft.com/en-us/azure/azure-monitor/app/app-insights-overview) exporter implementation for [OpenTelemetry Rust](https://github.com/open-telemetry/opentelemetry-rust).
118

129
**Disclaimer**: This is not an official Microsoft product.
1310

1411
## Usage
1512

16-
Configure a OpenTelemetry pipeline using the Application Insights exporter and start creating
17-
spans (this example requires the **reqwest-client-blocking** feature):
13+
Configure a OpenTelemetry pipeline using the Application Insights exporter and start creating spans (this example requires the **reqwest-client** feature):
1814

19-
```rust
15+
```rust,no_run
2016
use opentelemetry::trace::Tracer as _;
2117
2218
fn main() {
@@ -29,213 +25,24 @@ fn main() {
2925
}
3026
```
3127

32-
### Simple or Batch
33-
34-
The functions `build_simple` and `install_simple` build/install a trace pipeline using the
35-
simple span processor. This means each span is processed and exported synchronously at the time
36-
it ends.
37-
38-
The functions `build_batch` and `install_batch` use the batch span processor instead. This
39-
means spans are exported periodically in batches, which can be better for performance. This
40-
feature requires an async runtime such as Tokio or async-std. If you decide to use a batch span
41-
processor, make sure to call `opentelemetry::global::shutdown_tracer_provider()` before your
42-
program exits to ensure all remaining spans are exported properly (this example requires the
43-
**reqwest-client** and **opentelemetry/rt-tokio** features).
44-
45-
```rust
46-
use opentelemetry::trace::Tracer as _;
47-
48-
#[tokio::main]
49-
async fn main() {
50-
let instrumentation_key = std::env::var("INSTRUMENTATION_KEY").unwrap();
51-
let tracer = opentelemetry_application_insights::new_pipeline(instrumentation_key)
52-
.with_client(reqwest::Client::new())
53-
.install_batch(opentelemetry::runtime::Tokio);
54-
55-
tracer.in_span("main", |_cx| {});
56-
57-
opentelemetry::global::shutdown_tracer_provider();
58-
}
59-
```
60-
61-
### Async runtimes and HTTP clients
62-
63-
In order to support different async runtimes, the exporter requires you to specify an HTTP
64-
client that works with your chosen runtime. The [`opentelemetry-http`] crate comes with support
65-
for:
66-
67-
- [`surf`] for [`async-std`]: enable the **surf-client** and **opentelemetry/rt-async-std**
68-
features and configure the exporter with `with_client(surf::Client::new())`.
69-
- [`reqwest`] for [`tokio`]: enable the **reqwest-client** and **opentelemetry/rt-tokio**
70-
features and configure the exporter with either `with_client(reqwest::Client::new())` or
71-
`with_client(reqwest::blocking::Client::new())`.
72-
73-
[`async-std`]: https://crates.io/crates/async-std
74-
[`opentelemetry-http`]: https://crates.io/crates/opentelemetry-http
75-
[`reqwest`]: https://crates.io/crates/reqwest
76-
[`surf`]: https://crates.io/crates/surf
77-
[`tokio`]: https://crates.io/crates/tokio
78-
79-
Alternatively you can bring any other HTTP client by implementing the `HttpClient` trait.
80-
81-
### Metrics
82-
83-
Please note: Metrics are still experimental both in the OpenTelemetry specification as well as
84-
Rust implementation.
28+
See documentation for more:
8529

86-
Please note: The metrics export configuration is still a bit rough in this crate. But once
87-
configured it should work as expected.
88-
89-
This requires the **metrics** feature.
90-
91-
```rust
92-
use opentelemetry::{global, sdk};
93-
use std::time::Duration;
94-
95-
#[tokio::main]
96-
async fn main() {
97-
// Setup exporter
98-
let instrumentation_key = std::env::var("INSTRUMENTATION_KEY").unwrap();
99-
let exporter = opentelemetry_application_insights::Exporter::new(instrumentation_key, ());
100-
let controller = sdk::metrics::controllers::push(
101-
sdk::metrics::selectors::simple::Selector::Exact,
102-
sdk::export::metrics::ExportKindSelector::Stateless,
103-
exporter,
104-
tokio::spawn,
105-
opentelemetry::util::tokio_interval_stream,
106-
)
107-
.with_period(Duration::from_secs(1))
108-
.build();
109-
global::set_meter_provider(controller.provider());
110-
111-
// Record value
112-
let meter = global::meter("example");
113-
let value_recorder = meter.f64_value_recorder("pi").init();
114-
value_recorder.record(3.14, &[]);
115-
116-
// Give exporter some time to export values before exiting
117-
tokio::time::sleep(Duration::from_secs(5)).await;
118-
}
119-
```
120-
121-
## Attribute mapping
122-
123-
OpenTelemetry and Application Insights are using different terminology. This crate tries it's
124-
best to map OpenTelemetry fields to their correct Application Insights pendant.
125-
126-
- [OpenTelemetry specification: Span](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/trace/api.md#span)
127-
- [Application Insights data model](https://docs.microsoft.com/en-us/azure/azure-monitor/app/data-model)
128-
129-
### Spans
130-
131-
The OpenTelemetry SpanKind determines the Application Insights telemetry type:
132-
133-
| OpenTelemetry SpanKind | Application Insights telemetry type |
134-
| -------------------------------- | ----------------------------------- |
135-
| `CLIENT`, `PRODUCER`, `INTERNAL` | Dependency |
136-
| `SERVER`, `CONSUMER` | Request |
137-
138-
The Span's status determines the Success field of a Dependency or Request. Success is `false` if
139-
the status `Error`; otherwise `true`.
140-
141-
The following of the Span's attributes map to special fields in Application Insights (the
142-
mapping tries to follow the OpenTelemetry semantic conventions for [trace] and [resource]).
143-
144-
Note: for `INTERNAL` Spans the Dependency Type is always `"InProc"`.
145-
146-
[trace]: https://github.com/open-telemetry/opentelemetry-specification/tree/master/specification/trace/semantic_conventions
147-
[resource]: https://github.com/open-telemetry/opentelemetry-specification/tree/master/specification/resource/semantic_conventions
148-
149-
| OpenTelemetry attribute key | Application Insights field |
150-
| ------------------------------------------------- | ----------------------------------------------------- |
151-
| `service.version` | Context: Application version (`ai.application.ver`) |
152-
| `enduser.id` | Context: Authenticated user id (`ai.user.authUserId`) |
153-
| `service.namespace` + `service.name` | Context: Cloud role (`ai.cloud.role`) |
154-
| `service.instance.id` | Context: Cloud role instance (`ai.cloud.roleInstance`) |
155-
| `telemetry.sdk.name` + `telemetry.sdk.version` | Context: Internal SDK version (`ai.internal.sdkVersion`) |
156-
| `SpanKind::Server` + `http.method` + `http.route` | Context: Operation Name (`ai.operation.name`) |
157-
| `ai.*` | Context: AppInsights Tag (`ai.*`) |
158-
| `http.url` | Dependency Data |
159-
| `db.statement` | Dependency Data |
160-
| `http.host` | Dependency Target |
161-
| `net.peer.name` + `net.peer.port` | Dependency Target |
162-
| `net.peer.ip` + `net.peer.port` | Dependency Target |
163-
| `db.name` | Dependency Target |
164-
| `http.status_code` | Dependency Result code |
165-
| `db.system` | Dependency Type |
166-
| `messaging.system` | Dependency Type |
167-
| `rpc.system` | Dependency Type |
168-
| `"HTTP"` if any `http.` attribute exists | Dependency Type |
169-
| `"DB"` if any `db.` attribute exists | Dependency Type |
170-
| `http.url` | Request Url |
171-
| `http.scheme` + `http.host` + `http.target` | Request Url |
172-
| `http.client_ip` | Request Source |
173-
| `net.peer.ip` | Request Source |
174-
| `http.status_code` | Request Response code |
175-
176-
All other attributes are directly converted to custom properties.
177-
178-
For Requests the attributes `http.method` and `http.route` override the Name.
179-
180-
### Events
181-
182-
Events are converted into Exception telemetry if the event name equals `"exception"` (see
183-
OpenTelemetry semantic conventions for [exceptions]) with the following mapping:
184-
185-
| OpenTelemetry attribute key | Application Insights field |
186-
| --------------------------- | -------------------------- |
187-
| `exception.type` | Exception type |
188-
| `exception.message` | Exception message |
189-
| `exception.stacktrace` | Exception call stack |
190-
191-
All other events are converted into Trace telemetry.
192-
193-
All other attributes are directly converted to custom properties.
194-
195-
[exceptions]: https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/trace/semantic_conventions/exceptions.md
196-
197-
### Metrics
198-
199-
Metrics get reported to Application Insights as Metric Data. The [`Aggregator`] (chosen through
200-
the [`Selector`] passed to the controller) determines how the data is represented.
201-
202-
| Aggregator | Data representation |
203-
| -------------- | --------------------------------------------------------- |
204-
| Array | list of measurements |
205-
| DDSketch | aggregation with value, min, max and count |
206-
| Histogram | aggregation with sum and count (buckets are not exported) |
207-
| LastValue | one measurement |
208-
| MinMaxSumCount | aggregation with value, min, max and count |
209-
| Sum | aggregation with only a value |
210-
211-
[`Aggregator`]: https://docs.rs/opentelemetry/0.16.0/opentelemetry/sdk/export/metrics/trait.Aggregator.html
212-
[`Selector`]: https://docs.rs/opentelemetry/0.16.0/opentelemetry/sdk/metrics/selectors/simple/enum.Selector.html
30+
- [Simple or Batch](https://docs.rs/opentelemetry-application-insights/latest/opentelemetry_application_insights/#simple-or-batch)
31+
- [Async runtimes and HTTP clients](https://docs.rs/opentelemetry-application-insights/latest/opentelemetry_application_insights/#async-runtimes-and-http-clients)
32+
- [Metrics](https://docs.rs/opentelemetry-application-insights/latest/opentelemetry_application_insights/#metrics)
21333

21434
## Application Insights integration
21535

21636
### Thanks
21737

218-
Huge thanks goes to [Denis Molokanov] for the amazing [appinsights] crate.
219-
Check it out if you want a more direct integration with Application Insights.
220-
221-
[Denis Molokanov]: https://github.com/dmolokanov
222-
[appinsights]: https://github.com/dmolokanov/appinsights-rs
38+
Huge thanks goes to [Denis Molokanov](https://github.com/dmolokanov) for the amazing [appinsights](https://github.com/dmolokanov/appinsights-rs) crate. Check it out if you want a more direct integration with Application Insights.
22339

22440
### Documentation
22541

226-
The only official documentation I could find is this one. Follow the links to
227-
see the data model and endpoint description.
42+
The only official documentation I could find is this one. Follow the links to see the data model and endpoint description.
22843

22944
> Can I send telemetry to the Application Insights portal?
23045
>
231-
> We recommend you use our SDKs and use the [SDK API]. There are variants of
232-
> the SDK for various [platforms]. These SDKs handle buffering, compression,
233-
> throttling, retries, and so on. However, the [ingestion schema] and [endpoint
234-
> protocol] are public.
46+
> We recommend you use our SDKs and use the [SDK API](https://docs.microsoft.com/en-us/azure/azure-monitor/app/api-custom-events-metrics). There are variants of the SDK for various [platforms](https://docs.microsoft.com/en-us/azure/azure-monitor/app/platforms). These SDKs handle buffering, compression, throttling, retries, and so on. However, the [ingestion schema](https://github.com/microsoft/ApplicationInsights-dotnet/tree/master/BASE/Schema/PublicSchema) and [endpoint protocol](https://github.com/Microsoft/ApplicationInsights-Home/blob/master/EndpointSpecs/ENDPOINT-PROTOCOL.md) are public.
23547
>
23648
> -- https://docs.microsoft.com/en-us/azure/azure-monitor/faq#can-i-send-telemetry-to-the-application-insights-portal
237-
238-
[SDK API]: https://docs.microsoft.com/en-us/azure/azure-monitor/app/api-custom-events-metrics
239-
[platforms]: https://docs.microsoft.com/en-us/azure/azure-monitor/app/platforms
240-
[ingestion schema]: https://github.com/microsoft/ApplicationInsights-dotnet/tree/master/BASE/Schema/PublicSchema
241-
[endpoint protocol]: https://github.com/Microsoft/ApplicationInsights-Home/blob/master/EndpointSpecs/ENDPOINT-PROTOCOL.md

‎README.tpl‎

Lines changed: 0 additions & 36 deletions
This file was deleted.

‎docs/releasing.md‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -8,8 +8,6 @@ In order to release a new version, follow these steps.
88

99
1. Update the version number in the `html_root_url` tag in [lib.rs](../src/lib.rs).
1010

11-
1. Update the [README.md](../README.md) by running `cargo readme -o README.md` in the root of the repository.
12-
1311
1. Commit the changes.
1412

1513
1. Tag the commit.

0 commit comments

Comments
 (0)