• Stars
    star
    225
  • Rank 177,187 (Top 4 %)
  • Language
    Rust
  • License
    Other
  • Created almost 6 years ago
  • Updated over 1 year ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Ergonomic Rust bindings for instrumenting Rust apps with high performance probes using SystemTap, DTrace, etc

tracers - Rust instrumentation library

Crates.io Azure Build Status - Linux/macOS/Windows Cirrus CI - FreeBSD

Summary

tracers is intended to be an easy to use and cross-platform Rust crate which makes it easy to add high-performance low-overhead probes to Rust programs. Underneath it will use each platform's native probing mechanism, like System Tap on Linux, DTrace on BSD, and ETW on Windows. Those platforms without a supported probing mechanism will fall back to a no-op implementation.

A key goal of this crate is to be able to drop it in to any Rust project, create and fire probes wherever it makes sense, and leave those probes in place all the time. When probes are disabled at compile time, there should be zero runtime impact, and when probes are compiled in but not enabled at runtime the probe impact should be no more than one or two CPU instructions.

Status

IMPORTANT: tracers is still experimental. The author is using it internally but this crate is still not yet widely used and may contain subtle and critical defects.

Quick start

In your Cargo.toml you need to add:

[dependencies]
...
tracers = "0.1.0"
tracers-macros = "0.1.0"

[build-dependencies]
...
tracers-build = "0.1.0"

It's important not to forget to add tracers-build to your build-dependencies, because you'll need that available at build time for the next step, which is to create a src/build.rs file if you don't have one already, and make sure it contains this:

use tracers_build::build;

fn main() {
build();
}

If you have an existing build.rs you'll need to make sure you add a call to tracers_build::build() somewhere in the main function, preferably early.

At this point you have all you need to define a tracer. Here's a simple example:

use tracers_macros::{probe, tracer};

#[tracer]
trait SimpleProbes {
fn hello(who: &str);
fn greeting(greeting: &str, name: &str);
fn optional_greeting(greeting: &str, name: &Option<&str>);
}

fn main() {
loop {
    probe!(SimpleProbes::hello("world"));
    probe!(SimpleProbes::greeting("hello", "world"));
    let name = Some("world");
    probe!(SimpleProbes::optional_greeting("hello", &name));
    let name: Option<&str> = None;
    probe!(SimpleProbes::optional_greeting("hello", &name));
}
}

You have have defined three probes, hello, greeting, and optional_greeting. By default, tracing is disabled at compile time, so when you run this code all of the probing infrastructure will be optimized away and you'll be left with zero runtime overhead.

To actually enable probing you need to activate one of the corresponding features in the tracers crate. For example, in your Cargo.toml:

[dependencies]
...
tracers = { version = "0.1.0", features = [ "force_static_stap"]

will enable SystemTap tracing. If you rebuild again and use a tool like tplist from BCC you should be able to see the probes in the binary.

Note also that the #[tracers] macro generates some useful documentation on your trait. Try cargo doc and find your trait in the docs for additional hints on how to use each probe.

The examples/ directory has some simple examples.

Platforms

The tracers crate and runtime components should compile and run on any supported Rust platform (although no_std is not yet supported). Adding tracers as a dependency shouldn't break your project on any platform; if it does that's a bug and you're encouraged to open a GitHub issue.

That said, the tracers crate by default doesn't actually trace anything; it compiles away to nothing. To actually enable tracing you need a supported platform. As of this writing that means:

  • Linux with System Tap (the force_static_stap feature)
  • Linux with LTT-ng (the force_static_lttng) feature

There is work being done to support:

  • Windows (with the Event Tracing for Windows system API)
  • FreeBSD and macOS (with DTrace)

License

Except where otherwise indicated, this project is licensed under either of

at your option.

However, the following -sys crates have the license corresponding to the third-party code which they wrap:

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in tracers by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Releasing

This section applies to maintainers only.

To release a new version, dependent crates must be released first. The bin/publish.sh script helps to automate the process but it's still quite manual.

Release process:

  1. Update the version property of all crates and of all crates' dependencies on other tracers crates to the new target version.

  2. Ensure all dependencies have both a path dependency for local development, and a version dependency for publishing. These must be consistent with the new version being published.

  3. Update the documentation link to reflect the current version.

Crates must be published in this order:

  • tracers-core
  • tracers-libelf-sys
  • tracers-libstapsdt-sys
  • tracers-codegen
  • tracers-macros-hack
  • tracers-macros
  • tracers-dyn-stap
  • tracers-dyn-noop
  • tracers-build
  • tracers

More Repositories

1

mapi_to_maildir

Project I wrote which uses MAPI33 managed MAPI wrapper to migrate my Outlook PST to Maildir format
C#
3
star
2

dotfiles

Various config files for shell and related tools
Python
2
star
3

asynciotest

A test project which exercises performance characteristics of various asynchronous I/O strategies under Windows
C++
2
star
4

panoply

A suite of tools in C# which display DirectShow filters, analyze media files to display contents, and render the DirectShow pipeline visually. Useful back in the days when the codec experience on Windows was a disaster
C++
2
star
5

rcapdissector

A cool little Ruby library and C extension that wrap the Wireshark libraries and support detailed packet dissection of any protocol for which Wireshark has a dissector, all within Ruby and at a surprisingly high speed
C++
2
star
6

rmarkov

A Ruby implementation of text analysis and generation using Markov chains
Ruby
2
star
7

rspice

Ruby
1
star
8

rubyxmltest

A test bench I used to evaluate the performance of Ruby XML parsers in handling large streams of XML from the tshark PDML output mode
Ruby
1
star
9

byedrupal

A quick and dirty Ruby script which I used to migrate my Drupal blog over to WordPress
Ruby
1
star
10

mortcalc.net

A loan amortization calculator written in C# and using the decimal type to avoid floating point errors
C#
1
star
11

bz2fb

A Ruby script I wrote to migrate our Bugzilla bug database to FogBugz
Ruby
1
star
12

awspend

Ruby
1
star
13

mercury_test

Yet another attempt at cracking the catalog building/abbreviation matching problem
C
1
star
14

vimrc

My .vim folder
1
star
15

cap2sql

cap2sql is a simple Ruby script that uses rcapdissector to dissect a libpcap packet capture file and store the results in a MySQL database
Ruby
1
star
16

mungecap

Quick and dirty C++ console app that reads one or more pcap capture files, applies a filter, and writes all matching frames out to a single pcap output file
C
1
star
17

new_mercury

Attempt number 1,487 at a general-purpose info management system/cognitive prosthesis. I think I got as far as a logo this time
C#
1
star
18

multitask

A custom Nant task that supports running multiple tasks in parallel
C#
1
star
19

exocortex

A prototypical attempt at a general-purpose cognitive prosthetic, which never went anywhere
C#
1
star
20

mercury_sandbox

An experimental Ruby implementation of my information management idea. This one focused on building a catalog of items and doing abbreviation matching against it
JavaScript
1
star
21

mercury

Another information management tool false start
C
1
star
22

intelmultithread3

My attempt at the TopCoder Intel Multithreaded Challenge #3 (unsuccessful)
C#
1
star
23

blockhammer

JavaScript
1
star
24

boltfacelogo

1
star
25

qdb

Quick and Dirty Backup (qdb) implements backups using rsync and hard links. Written in Perl of all things
Perl
1
star
26

infohub

Another one of my attempts at a general-purpose information management tool. Came to nothing
C#
1
star
27

haddock

Exploratory Ruby script to quantify the strength of passwords generated by the Haddock password generation algorithm
Ruby
1
star
28

cryptoperftest

A throwaway Visual C++ project I wrote to get a rough sense of the encryption performance of the LibTomCrypt crypto library on modern hardware
C
1
star
29

rubyhttp

A test bench I used to compare the performance of various HTTP client implementations available in Ruby
Ruby
1
star
30

soundgen

A Java application to generate ringtones that sound like variations on the AT&T PBX phone ringtone from the early seasons of 24. Got it working but couldn't find what parameters to vary to make pleasing-sounding tones
Java
1
star
31

gloving

Explore the wonderful world of word vector models, particularly GloVe but also word2vec
Scala
1
star
32

overwatch

An attempt at a Ruby project which built a data warehouse from Wireshark captures and provided analytics tools to see who was doing what, when, on the network. Never got very far due to performance problems
Ruby
1
star
33

sqlite3_schema_provider

A SQLite 3 schema provider for CodeSmith
C#
1
star