[−][src]Crate appinsights
Application Insights for Rust
The Application Insights for Rust provides an SDK to instrument your application with telemetry and monitor it using Azure Portal features.
The following Application Insights telemetry items are supported:
- Availability telemetry
- Event telemetry
- Page view telemetry
- Remote dependency telemetry
- Request telemetry
- Trace telemetry
Eventually all telemetry items that Application Insights supports will be implemented.
Requirements
Add appinsights crate to your project
$ cargo add appinsights
Obtain Instrumentation Key by creating a new instance of Application Insights service.
Examples
- Create an new instance of
TelemetryClient
with an Instrumentation Key and default settings. To get more control over client behavior please visitTelemetryConfig
. - Send an event telemetry to the Application Insights service.
use appinsights::TelemetryClient; // configure telemetry client with default settings let client = TelemetryClient::new("<instrumentation key>".to_string()); // send event telemetry to the Application Insights server client.track_event("Application started".to_string());
If you need more control over the client's behavior, you can create a new instance of
TelemetryConfig
and initialize a
TelemetryClient
with it.
use std::time::Duration; use appinsights::{TelemetryClient, TelemetryConfig}; use appinsights::telemetry::SeverityLevel; // configure telemetry config with custom settings let config = TelemetryConfig::builder() // provide an instrumentation key for a client .i_key("<instrumentation key>") // set a new maximum time to wait until data will be sent to the server .interval(Duration::from_secs(5)) // construct a new instance of telemetry configuration .build(); // configure telemetry client with default settings let client = TelemetryClient::from_config(config); // send trace telemetry to the Application Insights server client.track_trace("A database error occurred".to_string(), SeverityLevel::Warning);
Telemetry submission
A TelemetryClient
has several convenient methods to submit telemetry items.
- track_event to log user action with the event name.
- track_trace to log a trace message with severity level.
- track_metric to log a numeric value that is not specified with a specific event.
- track_request to log a HTTP request with the specified method, URL, duration and response code.
- track_remote_dependency to log a dependency with the specified name, type, target, and success status.
- track_availability to log an availability test result with the specified test name, duration, and success status.
But they provide the very basic set of parameters telemetry types can represent. For example all
telemetry items support properties
and
tags
which not accessible via these methods.
More complete versions are available through use of telemetry item struct which can be
submitted through the track
method.
Context tags
All telemetry items have tags
field that can
contain an information about telemetry such as user, session, and device information.
The type of tags
is ContextTags
that contains
convenient methods to store and and retrieve commonly used data.
A TelemetryContext
also have
tags
. These tags will be applied to all telemetry
items submitted to a server. In case when some tags exists in both telemetry client context tags
and telemetry item tags, later will be sent to the server.
use std::time::Duration; use http::Method; use appinsights::TelemetryClient; use appinsights::telemetry::{RequestTelemetry, Telemetry}; // configure telemetry with default settings let mut client = TelemetryClient::new("instrumentation".to_string()); // set role instance name globally. This is usually the name of the service submitting the telemetry client.context_mut().tags_mut().cloud_mut().set_role("rust_server".to_string()); // set the role instance to the host name. Note that this is done automatically by the SDK client.context_mut().tags_mut().cloud_mut().set_role_instance("rust_server".to_string()); let mut telemetry = RequestTelemetry::new( Method::GET, "https://example.com/main.html".parse().unwrap(), Duration::from_secs(2), "200".into(), ); // set the account id context tag telemetry.tags_mut().user_mut().set_account_id("account_id".to_string()); // send telemetry to the Application Insights server client.track(telemetry);
Common properties
All telemetry items have properties
field
and a TelemetryContext
also have properties
.
These properties will be applied to all telemetry items submitted to a server. In case when some properties exists in both telemetry
client properties and telemetry item properties, later will be sent to the server.
use appinsights::TelemetryClient; use appinsights::telemetry::{RequestTelemetry, Telemetry}; // configure telemetry with default settings let mut client = TelemetryClient::new("instrumentation".to_string()); // set custom telemetry item property globally client.context_mut().properties_mut().insert("Resource Group".to_string(), "my-rg".to_string()); // ... send telemetry to the Application Insights server
Shutdown
The telemetry item submission happens asynchronously. The internal channel starts a new worker thread that used to accept and send telemetry to the server. While telemetry is not sent the worker stores it in memory, so when application crashes the data will be lost. Luckily SDK provides several convenient methods to deal with this issue.
flush_channel
will trigger telemetry submission as soon as possible. It returns immediately and telemetry is no guaranteed to be sent.close_channel
will cause the channel to stop accepting any new telemetry items, submit all pending ones, block current thread and wait until data will be sent at most once. If telemetry submission fails, it will not retry. This method consumes the value of client so it makes impossible to use a client with close channel.- Once
TelemetryClient
is out of scopedrop
method for channel will be called. It will trigger termination of submission flow, all pending items discarded, block current thread until all resources freed. It is default "exit" mode for client.
Modules
telemetry | Module for Application Insights telemetry items. |
Macros
tags | Macros to generate well-known context tags. |
Structs
InMemoryChannel | A telemetry channel that stores events exclusively in memory. |
TelemetryClient | Application Insights telemetry client provides an interface to track telemetry items. |
TelemetryConfig | Configuration data used to initialize a new |
TelemetryContext | Encapsulates contextual data common to all telemetry submitted through a telemetry client. |