---
name: hashintel-rust-tracing-practices
description: "HASH tracing and instrumentation practices for Rust. Use when adding spans, events, or #[tracing::instrument] to Rust code."
license: "NOASSERTION"
metadata:
  decimalai-skill-id: "f36732ce-443b-4e34-847f-94f1a9c44324"
  decimalai-version-id: "891559e3-e304-4263-830d-47d0defe3dad"
  decimalai-version: "2"
  decimalai-body-sha256: "42f37fa3d6dbbda6c231d71a791c74d3b421efca72578e48e405fc8d976375e4"
  decimalai-name: "hashintel/rust-tracing-practices"
  decimalai-format: "1"
  decimalai-invocation: "model"
  decimalai-category: "coding"
  decimalai-source: "https://app.decimal.ai/s/hashintel-rust-tracing-practices@2/SKILL.md"
---
# Rust Tracing Practices

## Event Recording

- Use level-specific macros for appropriate visibility: `info!`, `debug!`, `trace!`, `warn!`, `error!`
- Provide structured data as named arguments to facilitate automated processing and filtering
- Prefer lowercase log-message prose while preserving identifier and acronym spelling
- Record ordinary error values with `Display`, using `%error` or `error = %error`
- Record an `error_stack::Report<Context>` with `Debug`, using `?report` or `error = ?report` on the complete report rather than its `current_context()` alone
- Keep public-response sanitization separate from diagnostic reporting. Debug formatting does not itself redact sensitive data
- Include relevant context through key-value pairs

These fragments assume a local `user`. Their error events are alternatives: `e` is an ordinary error value, and `report` is an `error_stack::Report<_>`.

```rust
tracing::info!(user_id = user.id, action = "login", "user logged in successfully");
tracing::error!(error = %e, user_id = user.id, "failed to authenticate user");
tracing::error!(error = ?report, user_id = user.id, "failed to authenticate user");
```

A report's plain `Display` stops after the first context and omits attachments. Its `Debug` formatter traverses the frames and renders printable attachments or installed hook output.

## Instrumentation

- Apply the `#[tracing::instrument]` attribute to functions to automatically create trace spans
- When an error return merits an automatic event, use `err` for an ordinary error and `err(Debug)` for an `error_stack::Report<Context>`
- Exclude sensitive or large parameters using `skip(password)` or `skip_all`
- Add custom context fields with `fields(request_id = req.id())`

```rust
#[tracing::instrument(level = "debug", err, skip(password), fields(user_id = user.id))]
async fn authenticate_user(user: &User, password: &[u8]) -> Result<AuthToken, AuthError> {
    // Implementation
}
```