Skip to content

Latest commit

 

History

History
128 lines (94 loc) · 4.32 KB

README.md

File metadata and controls

128 lines (94 loc) · 4.32 KB
Raw

New Relic SDK

docs.rs crates.io

An idiomatic Rust wrapper around the New Relic C SDK.

See also the rocket_newrelic crate for example integration with the Rocket web framework.

Note: versions 0.1.0 onwards of this crate are completely incompatible with previous versions as they move away from the deprecated New Relic SDK to the newer New Relic C SDK. This has additional requirements: see https://docs.newrelic.com/docs/agents/c-sdk/get-started/introduction-c-sdk for details.

In particular, the New Relic SDK will not link against musl - see the newrelic-sys crate for more details.

See https://github.com/hjr3/newrelic-rs for the <0.1.0 repository.

Usage

Add this crate to your Cargo.toml:

[dependencies]
newrelic = "0.2"

You can then instrument your code as follows:

use std::{env, thread, time::Duration};

use newrelic::{App, NewRelicConfig};

fn main() {
    let license_key =
        env::var("NEW_RELIC_LICENSE_KEY").unwrap_or_else(|_| "example-license-key".to_string());
    let app = App::new("my app", &license_key).expect("Could not create app");

    // Start a web transaction and a segment
    let _transaction = app
        .web_transaction("Transaction name")
        .expect("Could not start transaction");
    thread::sleep(Duration::from_secs(1));

    // Transaction ends automatically.

    // App is destroyed automatically.
}

See the examples directory of the repository for more complex examples, including segments (custom, datastore and external) and further configuration.

This crate still requires the New Relic daemon to be running as per the documentation for the New Relic C SDK; be sure to read this first.

Functionality

The core functionality from the C SDK is currently implemented. A few extra things are still TODO!

  • Transactions
    • Adding attributes
    • Noticing errors
    • Ignoring transactions
    • Renaming transactions
    • Overriding timings
  • Segments
    • Custom
    • Datastore
    • External
    • Nesting segments
    • Overriding timings
  • Custom events
  • Custom metrics
  • Async segments
  • Distributed tracing
  • Transaction tracing configuration
  • Datastore segment tracing configuration
  • Logging/daemon configuration

Failures

Currently, creating a transaction using this library returns a Result<newrelic::Transaction, newrelic::Error>, making it up to the user to either fail hard, or ignore, when transactions fail to be created.

However, when working with Segments in the library, the failure of the segment is hidden from the user for ergonomic purposes. That is, in the following example, creation of the segment might fail (which will be logged using the log crate), but the argument passed to the custom segment closure is still of type newrelic::Segment. This makes it much simpler to work with nested segments.

This behaviour may be changed in future, if it proves to be unpopular.

use newrelic::{App, NewRelicConfig};

fn main() {
    let app =
        App::new("my app", "my license key").expect("Could not create app");
    let transaction = app
        .web_transaction("Transaction name")
        .expect("Could not start transaction");
    let expensive_value = transaction.custom_segment("Segment name", "Segment category", |seg| {
        do_something_expensive()
    });
}

Async

The Segmented extension trait adds the ability to run a future inside of a segment. The feature async is required.

Distributed Tracing

Distributed tracing is available wiith the feature distributed_tracing. Notably, this feature requires the libc crate.