Analytics for Rust

Our Rust library lets you record analytics data from your Rust code. The requests hit our servers, and then we route your data to any analytics service you enable on your destinations page.

This library is open-source, so you can check it out on GitHub.

All of Segment’s server libraries are built for high-performance, so you can use them in your web server controller code. This library contains the building blocks to batch and efficiently send data to Segment.

Getting Started

Install the Package

Install analytics-rust using cargo to your project:

cargo add analytics

which adds the following to you Cargo.toml file:

[dependencies]
analytics = "0.2"

Then use it with your source’s Write Key. Of course, you’ll want to replace YOUR_WRITE_KEY with your actual Write Key which you can find in Segment under your source settings.

use analytics::http::HttpClient;
use analytics::client::Client;
use analytics::message::{BatchMessage, Track, User};
use analytics::batcher::Batcher;
use serde_json::json;

fn main() {
    let write_key = "YOUR_WRITE_KEY";
    let client = HttpClient::default();
    let mut batcher = Batcher::new(None);

    // Pretend this is reading off of a queue, a file, or some other data
    // source.
    for i in 0..100 {
        let msg = BatchMessage::Track(Track {
            user: User::UserId { user_id: format!("user-{}", i) },
            event: "Example Event".to_owned(),
            properties: json!({
                "foo": format!("bar-{}", i),
            }),
            ..Default::default()
        });

        // An error here indicates a message is too large. In real life, you
        // would probably want to put this message in a deadletter queue or some
        // equivalent.
        if let Some(msg) = batcher.push(msg).unwrap() {
            client.send(write_key, &batcher.into_message()).unwrap();

            batcher = Batcher::new(None);
            batcher.push(msg).unwrap(); // Same error condition as above.
        }
    }
}

This outlines the primitive building blocks used in creating an ETL-like operation you can use to send data to Segment for your source.

The default initialization settings are production-ready.

Identify

identify lets you tie a user to their actions and record traits about them. It includes a unique User ID and any optional traits you know about them.

We recommend calling identify a single time when the user’s account is first created, and only identifying again later when their traits change.

Example identify call:

Identify{
  user: User::UserId { user_id: format!("user-{}", i) },
  traits: json!({
    "name":"Michael Bolton",
    "email":"mbolton@example.com",
    "plan":"Enterprise",
    "friends":"42"
  }),
  ..Default::default()
}

This call is identifying Michael by his unique User ID (the one you know him by in your database) and label him with name, email, plan and friends traits.

The identify call has the following fields:

Find details on the identify method payload in our Spec.

Track

track lets you record the actions your users perform.Every action triggers what we call an “event”, which can also have associated properties.

You’ll want to track events that are indicators of success for your site, like Signed Up, Item Purchased or Article Bookmarked.

To get started, we recommend tracking just a few important events. You can always add more later!

Example track call:

Track {
    user: User::UserId { user_id: "f4ca124298".to_owned() },
    event: "Signed Up".to_owned(),
    properties: json!({
        "plan": "Enterprise",
    }),
    ..Default::default()
}

This example track call tells us that your user just triggered the Signed Up event choosing the “Enterprise” plan.

track event properties can be anything you want to record. In this case, plan type.

The track call has the following fields:

Find details on best practices in event naming as well as the track method payload in our Spec.

Page

The page method lets you record page views on your website, along with optional extra information about the page being viewed.

If you’re using our client-side set up in combination with the Rust library, page calls are already tracked for you by default. However, if you want to record your own page views manually and aren’t using our client-side library, read on!

Example page call:

Page {
    user: User::UserId { user_id: "f4ca124298".to_owned() },
    name: "Rust Library".to_owned(),
    properties: json!({
        "url": "[Enterprise](https://segment.com/libraries/rust/)",
    }),
    ..Default::default()
}

The page call has the following fields:

Find details on the page payload in our Spec.

Group

group lets you associate an identified user with a group. A group could be a company, organization, account, project or team! It also lets you record custom traits about the group, like industry or number of employees.

This is useful for tools like Intercom, Preact and Totango, as it ties the user to a group of other users.

Example group call:

Group {
    user: User::UserId { user_id: "019mr8mf4r".to_owned() },
    group_id: "56".to_owned(),
    traits: json!({
        "name": "Initech",
        "description": "Accounting Software",
    }),
    ..Default::default()
}

The group call has the following fields:

Find more details about group including the group payload in our Spec.

Alias

alias is how you associate one identity with another. This is an advanced method, but it is required to manage user identities successfully in some of our destinations.

In Mixpanel it’s used to associate an anonymous user with an identified user once they sign up. For Kissmetrics, if your user switches IDs, you can use ‘alias’ to rename the ‘userId’.

Example alias call:

Alias {
    user: User::Both { user_id: "019mr8mf4r".to_owned(), anonymous_id: "anonymousUser".to_owned() },
    ..Default::default()
}

The alias call has the following fields:

Here’s a full example of how we might use the alias call:

// the anonymous user does actions ...
Track {
    user: User::AnonymousId { anonymous_id: "anonymousUser".to_owned() },
    event: "Anonymous Event".to_owned(),
    ..Default::default()
}

// the anonymous user signs up and is aliased
Alias {
    user: User::Both { user_id: "019mr8mf4r".to_owned(), anonymous_id: "anonymousUser".to_owned() },
    ..Default::default()
}

// the identified user is identified
Identify{
  user: User::UserId { user_id: "019mr8mf4r".to_owned() },
  traits: json!({
    "name":"Michael Bolton",
    "email":"mbolton@example.com",
    "plan":"Enterprise",
    "friends":"42"
  }),
  ..Default::default()
}

// the identified user does actions ...
Track {
    user: User::UserId { user_id: "019mr8mf4r".to_owned() },
    event: "Item Viewed".to_owned(),
    properties: json!({
        "item": "lamp",
    }),
    ..Default::default()
}

For more details about alias, including the alias call payload, check out our Spec.

Selecting Destinations

The alias, group, identify, page and track calls can all be passed an object of context.integrations that lets you turn certain integrations on or off. By default all destinations are enabled.

Here’s an example track call with the context.integrations object shown.

Track {
    user: User::UserId { user_id: "019mr8mf4r".to_owned() },
    event: "Membership Upgraded".to_owned(),
    integrations: Some(json!({
        "All": "false",
        "Mixpanel": true,
    })),
    ..Default::default()
}

In this case, we’re specifying that we want this Track to only go to Vero. All: false says that no destination should be enabled unless otherwise specified. Vero: true turns on Vero, etc.

Destination flags are case sensitive and match the destination’s name in the docs (i.e. “AdLearn Open Platform”, “awe.sm”, “MailChimp”, etc.).

Note:

• Available at the business level, filtering track calls can be done right from the Segment UI on your source schema page. We recommend using the UI if possible since it’s a much simpler way of managing your filters and can be updated with no code changes on your side.

• If you are on a grandfathered plan, events sent server-side that are filtered through the Segment dashboard will still count towards your API usage.

Historical Import

You can import historical data by adding the timestamp argument to any of your method calls. This can be helpful if you’ve just switched to Segment.

Historical imports can only be done into destinations that can accept historical timestamped data. Most analytics tools like Mixpanel, Amplitude, Kissmetrics, etc. can handle that type of data just fine. One common destination that does not accept historical data is Google Analytics since their API cannot accept historical data.

Note: If you’re tracking things that are happening right now, leave out the timestamp and our servers will timestamp the requests for you.

Context

You can send Context fields in two ways with the Rust library.

Firstly, you can set a global context field that will be set on all messages from the client.

let context = json!({
  "app":{
    "name":    "myapp",
    "version": "myappversion"
  }
});
Track {
    user: User::UserId { user_id: "019mr8mf4r".to_owned() },
    event: "Membership Upgraded".to_owned(),
    integrations: Some(json!({
        "All": "false",
        "Mixpanel": true,
    })),
    context: Some(context),
    ..Default::default()
}

Secondly, you can set a context field on specific events.

Identify{
  user: User::UserId { user_id: "019mr8mf4r".to_owned() },
  traits: json!({
    "friends":"42"
  }),
  context: Some(json!({
    "active":true
  })),
  ..Default::default()
}

Batching

Our libraries are built to support high performance environments using Batch Message. Until Rust’s async IO story matures we’re leaving the flushing of Messages up to you to implement.

There is a maximum of 500KB per batch request and 32KB per call.

Troubleshooting

If you’re having trouble we have a few tips that help common problems.

No events in my debugger

1. Double check that you’ve followed all the steps in the Quickstart.

2. Make sure that you’re calling one of our API methods once the library is successfully installed—identify, track, etc.

No events in my end tools

1. Double check your credentials for that destination.

2. Make sure that the destination you are troubleshooting can accept server-side API calls. Compatibility is shown on the destination docs pages and on the sheets on your Segment source Destinations page.

3. Check out the destination’s documentation to see if there are other requirements for using the method and destination you’re trying to get working.