logging.md

Logging in Rust

This document explains how to get started with logging in Rust programs on Fuchsia. For general information about recording and viewing logs, see the language-agnostic logging documentation.

Required capabilities {#capabilities}

Ensure that your component requests the appropriate logging capabilities by including the following in your component manifest:

• {.cmx}

{
  "include": [
    "syslog/client.shard.cmx"
  ],
  ...
}

• {.cml}

{
  include: [
    "syslog/client.shard.cml"
  ],
  ...
}

Initialization {#initialization}

You must initialize logging before you can record logs from Rust code. Initialization is handled by the fuchsia crate setup macros.

GN dependencies

Add the following deps to your BUILD.gn file:

deps = [
  "//src/lib/fuchsia",
]

Setup

In your Rust source files, logging is enabled by default for any function initialized using the fuchsia::main or fuchsia::test macros:

#[fuchsia::main]
fn main() {
    // ...
}

#[fuchsia::test]
fn example_test() {
    // ...
}

You can also pass the logging flag to make this explicit:

#[fuchsia::main(logging = true)]
fn main() {
    // ...
}

#[fuchsia::test(logging = true)]
fn example_test() {
    // ...
}

Add tags

Log messages can include one or more tags to provide additional context. To enable log tags for a given scope, pass the logging_tags parameter during initialization:

#[fuchsia::main(logging_tags = ["foo", "bar"])]
fn main() {
    // ...
}

#[fuchsia::test(logging_tags = ["foo", "bar"])]
fn example_test_with_tags() {
    // ...
}

Record logs {#record}

Rust programs on Fuchsia generally use the tracing crate macros to record logs.

GN dependencies

Add the tracing crate to the deps entry of your BUILD.gn file:

deps = [
  "//third_party/rust_crates:tracing",
]

Log events

Call the macros provided by the tracing crate to record logs at the declared severity level:

use tracing;

fn main() {
    tracing::trace!("something happened: {}", 5); // maps to TRACE
    tracing::debug!("something happened: {}", 4); // maps to DEBUG
    tracing::info!("something happened: {}", 3);  // maps to INFO
    tracing::warn!("something happened: {}", 2);  // maps to WARN
    tracing::error!("something happened: {}", 1); // maps to ERROR
}

Standard streams

Rust macros such as println!, eprintln! etc. map to standard out (stdout) and standard error (stderr). Using these streams may require additional setup work for your program.

For more details, see the standard streams section in the language-agnostic logging documentation.