Crate opentelemetry_application_insights

Expand description

An Azure Application Insights exporter implementation for OpenTelemetry Rust.

Disclaimer: This is not an official Microsoft product.

§Usage

Configure a OpenTelemetry pipeline using the Application Insights exporter and start creating spans (this example requires the opentelemetry-http/reqwest feature):

use opentelemetry::trace::Tracer as _;

fn main() {
    let connection_string = std::env::var("APPLICATIONINSIGHTS_CONNECTION_STRING").unwrap();
    let tracer = opentelemetry_application_insights::new_pipeline_from_connection_string(connection_string)
        .expect("valid connection string")
        .with_client(reqwest::blocking::Client::new())
        .install_simple();

    tracer.in_span("main", |_cx| {});
}

§Simple or Batch

The functions build_simple and install_simple build/install a trace pipeline using the simple span processor. This means each span is processed and exported synchronously at the time it ends.

The functions build_batch and install_batch use the batch span processor instead. This means spans are exported periodically in batches, which can be better for performance. This feature requires an async runtime such as Tokio or async-std. If you decide to use a batch span processor, make sure to call opentelemetry::global::shutdown_tracer_provider() before your program exits to ensure all remaining spans are exported properly (this example requires the opentelemetry/rt-tokio and opentelemetry-http/reqwest features).

use opentelemetry::trace::Tracer as _;

#[tokio::main]
async fn main() {
    let tracer = opentelemetry_application_insights::new_pipeline_from_env()
        .expect("env var APPLICATIONINSIGHTS_CONNECTION_STRING is valid connection string")
        .with_client(reqwest::Client::new())
        .install_batch(opentelemetry_sdk::runtime::Tokio);

    tracer.in_span("main", |_cx| {});

    opentelemetry::global::shutdown_tracer_provider();
}

§Async runtimes and HTTP clients

In order to support different async runtimes, the exporter requires you to specify an HTTP client that works with your chosen runtime. The opentelemetry-http crate comes with support for:

isahc: enable the opentelemetry-http/isahc feature and configure the exporter with with_client(isahc::HttpClient::new()?).
reqwest: enable the opentelemetry-http/reqwest feature and configure the exporter with either with_client(reqwest::Client::new()) or with_client(reqwest::blocking::Client::new()).
and more…

Alternatively you can bring any other HTTP client by implementing the HttpClient trait.

§Metrics

Please note: Metrics are still experimental both in the OpenTelemetry specification as well as Rust implementation.

Please note: The metrics export configuration is still a bit rough in this crate. But once configured it should work as expected.

This requires the metrics feature.

use opentelemetry::global;
use opentelemetry_sdk::metrics::{PeriodicReader, SdkMeterProvider};
use std::time::Duration;

#[tokio::main]
async fn main() {
    // Setup exporter
    let connection_string = std::env::var("APPLICATIONINSIGHTS_CONNECTION_STRING").unwrap();
    let exporter = opentelemetry_application_insights::Exporter::new_from_connection_string(
        connection_string,
        reqwest::Client::new(),
    )
    .expect("valid connection string");
    let reader = PeriodicReader::builder(exporter, opentelemetry_sdk::runtime::Tokio).build();
    let meter_provider = SdkMeterProvider::builder().with_reader(reader).build();
    global::set_meter_provider(meter_provider);

    // Record value
    let meter = global::meter("example");
    let histogram = meter.f64_histogram("pi").init();
    histogram.record(3.14, &[]);

    // Simulate work, during which metrics will periodically be reported.
    tokio::time::sleep(Duration::from_secs(300)).await;
}

§Live Metrics

Enable live metrics collection: https://learn.microsoft.com/en-us/azure/azure-monitor/app/live-stream.

Metrics are based on traces. See attribute mapping below for how traces are mapped to requests, dependencies and exceptions and how they are deemed “successful” or not.

To configure role, instance, and machine name provide service.name, service.instance.id, and host.name resource attributes respectively in the trace config.

Sample telemetry is not supported, yet.

This requires the live-metrics feature and the build_batch/install_batch methods.

use opentelemetry::trace::Tracer as _;

#[tokio::main]
async fn main() {
    let tracer = opentelemetry_application_insights::new_pipeline_from_env()
        .expect("env var APPLICATIONINSIGHTS_CONNECTION_STRING is valid connection string")
        .with_client(reqwest::Client::new())
        .with_live_metrics(true)
        .install_batch(opentelemetry_sdk::runtime::Tokio);

    // ... send traces ...

    opentelemetry::global::shutdown_tracer_provider();
}

§Attribute mapping

OpenTelemetry and Application Insights are using different terminology. This crate tries it’s best to map OpenTelemetry fields to their correct Application Insights pendant.

§Spans

The OpenTelemetry SpanKind determines the Application Insights telemetry type:

OpenTelemetry SpanKind	Application Insights telemetry type
`CLIENT`, `PRODUCER`, `INTERNAL`	Dependency
`SERVER`, `CONSUMER`	Request

The Span’s status determines the Success field of a Dependency or Request. Success is false if the status Error; otherwise true.

The following of the Span’s attributes map to special fields in Application Insights (the mapping tries to follow the OpenTelemetry semantic conventions for trace and resource).

Note: for INTERNAL Spans the Dependency Type is always "InProc".

OpenTelemetry attribute key	Application Insights field
`service.version`	Context: Application version (`ai.application.ver`)
`enduser.id`	Context: Authenticated user id (`ai.user.authUserId`)
`service.namespace` + `service.name`	Context: Cloud role (`ai.cloud.role`)
`service.instance.id`	Context: Cloud role instance (`ai.cloud.roleInstance`)
`telemetry.sdk.name` + `telemetry.sdk.version`	Context: Internal SDK version (`ai.internal.sdkVersion`)
`SpanKind::Server` + `http.request.method` + `http.route`	Context: Operation Name (`ai.operation.name`)
`ai.*`	Context: AppInsights Tag (`ai.*`)
`url.full`	Dependency Data
`db.statement`	Dependency Data
`http.request.header.host`	Dependency Target
`server.address` + `server.port`	Dependency Target
`server.socket.address` + `server.socket.port`	Dependency Target
`db.name`	Dependency Target
`http.response.status_code`	Dependency Result code
`db.system`	Dependency Type
`messaging.system`	Dependency Type
`rpc.system`	Dependency Type
`"HTTP"` if any `http.` attribute exists	Dependency Type
`"DB"` if any `db.` attribute exists	Dependency Type
`url.full`	Request Url
`url.scheme` + `http.request.header.host` + `url.path` + `url.query`	Request Url
`url.scheme` + `server.address` + `server.port` + `url.path` + `url.query`	Request Url
`client.address`	Request Source
`client.socket.address`	Request Source
`http.response.status_code`	Request Response code

All other attributes are directly converted to custom properties.

For Requests the attributes http.request.method and http.route override the Name.

§Deprecated attributes

The following deprecated attributes also work:

Attribute	Deprecated attribute
`http.request.method`	`http.method`
`http.request.header.host`	`http.host`
`http.response.status_code`	`http.status_code`
`url.full`	`http.url`
`url.scheme`	`http.scheme`
`url.path` + `url.query`	`http.target`
`client.address`	`http.client_ip`
`client.socket.address`	`net.sock.peer.addr`
`client.socket.address`	`net.peer.ip`
`server.address`	`net.peer.name` (for client spans)
`server.port`	`net.peer.port` (for client spans)
`server.socket.address`	`net.sock.peer.addr` (for client spans)
`server.socket.address`	`net.peer.ip` (for client spans)
`server.socket.port`	`net.sock.peer.port` (for client spans)
`server.address`	`net.host.name` (for server spans)
`server.port`	`net.host.port` (for server spans)

§Events

Events are converted into Exception telemetry if the event name equals "exception" (see OpenTelemetry semantic conventions for exceptions) with the following mapping:

OpenTelemetry attribute key	Application Insights field
`exception.type`	Exception type
`exception.message`	Exception message
`exception.stacktrace`	Exception call stack

Events are converted into Event telemetry if the event name equals "ai.custom" with the following mapping:

OpenTelemetry attribute key	Application Insights field
`ai.customEvent.name`	Event name

All other events are converted into Trace telemetry with the follwing mapping:

OpenTelemetry attribute key	Application Insights field
`level` (`tracing::Level`)	Severity level

All other attributes are directly converted to custom properties.

§Metrics

Metrics get reported to Application Insights as Metric Data. The Aggregation determines how the data is represented.

Aggregator	Data representation
Histogram	aggregation with sum, count, min, and max (buckets are not exported)
Gauge	one measurement
Sum	aggregation with only a value

Modules§

attrs
Attributes for Application Insights context fields

Structs§

Exporter
Application Insights span exporter
PipelineBuilder
Application Insights exporter pipeline builder

Enums§

Error
Errors that occurred during span export.

Traits§

HttpClient
A minimal interface necessary for sending requests over HTTP. Used primarily for exporting telemetry over HTTP. Also used for fetching sampling strategies for JaegerRemoteSampler

Functions§

new_pipelineDeprecated
Create a new Application Insights exporter pipeline builder
new_pipeline_from_connection_string
Create a new Application Insights exporter pipeline builder
new_pipeline_from_env
Create a new Application Insights exporter pipeline builder