Expand description
An Azure Application Insights exporter implementation for OpenTelemetry Rust.
Disclaimer: This is not an official Microsoft product.
§Usage
§Trace
This requires the trace feature (enabled by default).
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| {});
}
§Logs
This requires the logs feature (enabled by default).
use log::{Level, info};
use opentelemetry_appender_log::OpenTelemetryLogBridge;
use opentelemetry_sdk::logs::{LoggerProvider, BatchLogProcessor};
#[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 logger_provider = LoggerProvider::builder()
.with_batch_exporter(exporter, opentelemetry_sdk::runtime::Tokio)
.build();
let otel_log_appender = OpenTelemetryLogBridge::new(&logger_provider);
log::set_boxed_logger(Box::new(otel_log_appender)).unwrap();
log::set_max_level(Level::Info.to_level_filter());
// Log
let fruit = "apple";
let price = 2.99;
info!("{fruit} costs {price}");
// Export remaining logs before exiting
let _ = logger_provider.shutdown();
}
§Metrics
This requires the metrics feature (enabled by default).
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").build();
histogram.record(3.14, &[]);
// Simulate work, during which metrics will periodically be reported.
tokio::time::sleep(Duration::from_secs(300)).await;
}
§Live Metrics
This requires the live-metrics feature and the build_batch
/install_batch
methods.
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.
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();
}
§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:
reqwest
: enable the opentelemetry-http/reqwest feature and configure the exporter with eitherwith_client(reqwest::Client::new())
orwith_client(reqwest::blocking::Client::new())
.- and more…
Alternatively you can bring any other HTTP client by implementing the HttpClient
trait.
§Attribute mapping
OpenTelemetry and Application Insights are using different terminology. This crate tries its best to map OpenTelemetry fields to their correct Application Insights pendant.
§Resource
Resource and instrumentation library attributes map to the following fields for spans, events and metrics (the mapping tries to follow the OpenTelemetry semantic conventions for resource).
OpenTelemetry attribute key | Application Insights field |
---|---|
service.namespace + service.name | Context: Cloud role (ai.cloud.role ) |
k8s.deployment.name | Context: Cloud role (ai.cloud.role ) |
k8s.replicaset.name | Context: Cloud role (ai.cloud.role ) |
k8s.statefulset.name | Context: Cloud role (ai.cloud.role ) |
k8s.job.name | Context: Cloud role (ai.cloud.role ) |
k8s.cronjob.name | Context: Cloud role (ai.cloud.role ) |
k8s.daemonset.name | Context: Cloud role (ai.cloud.role ) |
k8s.pod.name | Context: Cloud role instance (ai.cloud.roleInstance ) |
service.instance.id | Context: Cloud role instance (ai.cloud.roleInstance ) |
device.id | Context: Device id (ai.device.id ) |
device.model.name | Context: Device model (ai.device.model ) |
service.version | Context: Application version (ai.application.ver ) |
telemetry.sdk.name + telemetry.sdk.version | Context: Internal SDK version (ai.internal.sdkVersion ) |
ai.* | Context: AppInsights Tag (ai.* ) |
If service.name
is the default (i.e. starts with “unknown_service:”), the Kubernetes based
values take precedence.
§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).
Note: for INTERNAL
Spans the Dependency Type is always "InProc"
.
OpenTelemetry attribute key | Application Insights field |
---|---|
user.id | Context: Authenticated user id (ai.user.authUserId ) |
SpanKind::Server + http.request.method + http.route | Context: Operation Name (ai.operation.name ) |
ai.* | Context: AppInsights Tag (ai.* ) |
url.full | Dependency Data |
db.query.text | Dependency Data |
http.request.header.host | Dependency Target |
server.address + server.port | Dependency Target |
network.peer.address + network.peer.port | Dependency Target |
db.namespace | 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 |
network.peer.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 |
---|---|
user.id | enduser.id |
db.namespace | db.name |
db.query.text | db.statement |
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 |
network.peer.address | server.socket.address (for client spans) |
network.peer.address | net.sock.peer.addr (for client spans) |
network.peer.address | net.peer.ip (for client spans) |
network.peer.port | server.socket.port (for client spans) |
network.peer.port | net.sock.peer.port (for client spans) |
network.peer.address | client.socket.address (for server spans) |
network.peer.address | net.sock.peer.addr (for server spans) |
network.peer.address | net.peer.ip (for server spans) |
server.address | net.peer.name (for client spans) |
server.port | net.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 following mapping:
OpenTelemetry attribute key | Application Insights field |
---|---|
level (tracing::Level ) | Severity level |
All other attributes are directly converted to custom properties.
§Logs
Logs are reported similar to events:
- If they contain an
exception.type
orexception.message
attribute, they’re converted to Exception telemetry with the same attribute mapping as events. - Otherwise they’re converted to Trace telemetry.
§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) |
ExponentialHistogram | aggregation with sum, count, min, and max (buckets are not exported) |
Gauge | one measurement |
Sum | aggregation with only a value |
Modules§
- Attributes for Application Insights context fields
Structs§
- Application Insights span exporter
- Pipeline
Builder trace
Application Insights exporter pipeline builder
Enums§
- Errors that occurred during span export.
Traits§
- 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_
pipeline Deprecated trace
Create a new Application Insights exporter pipeline builder - Create a new Application Insights exporter pipeline builder
- Create a new Application Insights exporter pipeline builder