blob: 850d946c378a00e40ff00349f306a76a29e02423 [file] [view] [edit]
# Driver Logging
You can have a driver send log messages to the
[syslog](/docs/development/diagnostics/logs/recording.md) using the Driver
Framework logging libraries.
## How to write logs
### Add dependencies
* {C++}
To use the logging library in a C++ driver, add the following dependency to
your `BUILD.gn`:
```gn
fuchsia_cc_driver("my_driver") {
deps = [
"//sdk/lib/driver/logging/cpp",
]
}
```
If your driver uses Bazel, add the dependency to `BUILD.bazel`:
```bazel
fuchsia_cc_driver(
name = "my_driver",
deps = [
"@fuchsia_sdk//pkg/driver_logging_cpp",
],
)
```
* {Rust}
To use logging in a Rust driver, add the `log` crate dependency to your
`BUILD.gn`:
```gn
fuchsia_rust_driver("my_driver") {
deps = [
"//third_party/rust_crates:log",
]
}
```
If your driver uses Bazel, add the dependency to `BUILD.bazel`:
```bazel
fuchsia_rust_driver(
name = "my_driver",
deps = [
"@crate_index//:log",
],
)
```
### Write log messages
* {C++}
In your C++ driver source code, include the logger header:
```cpp
#include <lib/driver/logging/cpp/logger.h>
```
The Driver Framework provides logging functions in the `fdf` namespace
corresponding to each severity level:
* `fdf::trace(...)`
* `fdf::debug(...)`
* `fdf::info(...)`
* `fdf::warn(...)`
* `fdf::error(...)`
* `fdf::fatal(...)`
These functions use `std::format`-style string formatting (`{}`):
```cpp
// Basic message
fdf::info("Initializing driver");
// Formatted arguments
fdf::info("Configured device with {} endpoints and {} buffers",
num_endpoints, num_buffers);
// Formatting hex or padded values
fdf::debug("Register address: {:#x}, value: {:02x}", reg_addr, val);
```
**Formatting `zx::result` and `zx::status`**
Fuchsia provides specialized `std::formatter` implementations for `zx::result`
and `zx::status`. You can pass these types directly to the format string
without calling `.status_string()`:
```cpp
zx::result<uint32_t> result = ReadRegister();
if (result.is_error()) {
fdf::error("Failed to read register: {}", result);
return result.take_error();
}
```
* {Rust}
In your Rust driver source code, import the logging macros from the `log`
crate:
```rust
use log::{debug, error, info, trace, warn};
```
The Driver Framework initializes the standard `log` facade for the driver
component, routing logs to `LogSink`. You can use the standard logging macros:
* `trace!(...)`
* `debug!(...)`
* `info!(...)`
* `warn!(...)`
* `error!(...)`
These macros use standard Rust format strings:
```rust
// Basic message
info!("Initializing driver");
// Formatted arguments
info!("Configured device with {num_endpoints} endpoints and {num_buffers} buffers");
// Formatting hex or padded values
debug!("Register address: {reg_addr:#x}, value: {val:02x}");
// Formatting errors or Zircon status
if let Err(status) = result {
error!("Failed to read register: {status:?}");
}
```
## How to read logs
### View driver logs
Fuchsia tags driver logs with the driver's moniker and name. You can filter and
view them using `ffx log`:
```posix-terminal
ffx log --filter <driver_name>
```
For more details about filtering, streaming, and querying logs, see
[Viewing logs](/docs/development/diagnostics/logs/viewing.md).
### Log severity levels
The log severities are, in order from most to least severe:
* `FATAL` (C++ only)
* `ERROR`
* `WARN`
* `INFO`
* `DEBUG`
* `TRACE`
By default, the system sends log messages with `INFO` severity and higher to the
[syslog](/docs/development/diagnostics/logs/recording.md#logsinksyslog). The
system suppresses `DEBUG` and `TRACE` severities by default at the producer side
to avoid unnecessary overhead.
### Control log severity
To enable lower severity logs (such as `DEBUG` and `TRACE`), you can adjust the
driver's minimum log level at runtime or at build time.
#### Runtime configuration with `ffx log`
You can dynamically set the minimum log severity for a running driver using
`ffx log --set-severity`:
```posix-terminal
ffx log --set-severity <component_selector>#<SEVERITY>
```
For example, to enable `DEBUG` logs for a driver by moniker:
```posix-terminal
ffx log --set-severity bootstrap/boot-drivers:dev.sys.pci#DEBUG
```
This sends an update request to the component's `LogSettings`, which persists
until you restart the component or update its severity setting again.
#### Build-time configuration with product assembly
To set the initial log level in product assembly, specify
`component_log_initial_interests` in the
[platform configuration][diagnosticsConfig-ref] or through
[developer overrides for product assembly][dev-overrides-docs].
To configure this through developer overrides, add the following to
`//local/BUILD.gn`:
```gn
# //local/BUILD.gn:
import("//build/assembly/developer_overrides.gni")
assembly_developer_overrides("sdhci-debug-logs") {
platform = {
diagnostics = {
component_log_initial_interests = [
{
component = "fuchsia-boot:///sdhci#meta/sdhci.cm"
log_severity = "debug"
},
]
}
}
}
```
Then run `fx set` with the `--assembly-override` flag:
```posix-terminal
fx set <product.board> --assembly-override=//local:sdhci-debug-logs
```
This sets the minimum log level to `DEBUG`, enabling both `DEBUG` and higher
severity logs.
[diagnosticsConfig-ref]: /reference/assembly/DiagnosticsConfig
[dev-overrides-docs]: /docs/development/build/software_assembly/developer_overrides.md