Logging, Distributed Tracing & Audit Guide

flowchart TD
    subgraph Client["Client Traffic"]
        Req["HTTP Request /api/v1/..."]
    end

    subgraph Layer1["1. HTTP Middleware Telemetry Layer (TraceLayer)"]
        TL["tower_http::TraceLayer\nRecords Method, Path, Status & Latency"]
    end

    subgraph Layer2["2. Business Audit Logging Layer (Audit Interceptor)"]
        AI["audit_interceptor Middleware\nDetects Mutations (POST/PUT/PATCH/DELETE) & Auth"]
        Redact["Sensitive Header Redaction (Authorization: [REDACTED])"]
        AsyncWrite["Tokio Asynchronous Non-blocking Persistence"]
        AuditTable[("Database audit_logs Table")]

        AI --> Redact --> AsyncWrite --> AuditTable
    end

    subgraph Layer3["3. Domain & Application Logging Layer (Tracing Framework)"]
        Controller["Controllers / Route Handlers"]
        Logic["Domain Logic Services (Service / Logic)"]
        Hooks["Mutation Hooks Pipeline"]
        Storage["Storage Engines (Database SPI)"]

        Controller --> Logic --> Storage
        Controller --> Hooks

        LogMacros["tracing Macros: info! / warn! / error! / debug! / trace!\nStructured KV fields & #[instrument] spans"]
        Controller -.-> LogMacros
        Logic -.-> LogMacros
        Hooks -.-> LogMacros
        Storage -.-> LogMacros
    end

    Req --> TL --> AI --> Controller

// Approach 1: Recommended, all-in-one import via prelude
use foundry::prelude::*;

// Approach 2: Dedicated namespace import
use foundry::log::{info, warn, error, debug, trace};

// Standard informational message
info!("Foundry business subsystem initialized successfully");

// Formatted message (standard print format syntax)
warn!("Tenant [{}] quota usage reached {}%", tenant_slug, usage_pct);

// Error logging with detailed diagnostics
if let Err(err) = sync_data().await {
    error!("Data synchronization failed: {:?}", err);
}

// Debug logging for troubleshooting
debug!("Parsed raw payload length: {} bytes", payload.len());

// Fine-grained tracing for locks and low-level loops
trace!("Traversing tag collection: index = {}", idx);

use foundry::prelude::*;

pub async fn process_order(ctx: &SystemContext, order_id: &str, amount: f64) {
    // 1. Basic Key-Value: key = value
    info!(
        order_id = order_id,
        amount = amount,
        "Processing customer order checkout"
    );

    // 2. Shorthand with % (Display formatting) and ? (Debug formatting)
    info!(
        %order_id,
        tenant = %ctx.system_slug,
        client_ip = ?ctx.client_ip,
        "Risk evaluation check passed"
    );

    // 3. Error diagnostics with structured context
    if amount < 0.0 {
        error!(
            %order_id,
            invalid_amount = amount,
            tenant = %ctx.system_slug,
            "Illegal negative order amount, aborting"
        );
    }
}

{
  "timestamp": "2026-10-14T10:15:30.123Z",
  "level": "INFO",
  "message": "Risk evaluation check passed",
  "target": "my_app::systems::shop::logic",
  "order_id": "ORD-20261014-001",
  "tenant": "mall",
  "client_ip": "192.168.1.108"
}

use foundry::prelude::*;
use tracing::instrument;

// Automatically records input parameters and function latency
#[instrument(skip(db), fields(tenant = %ctx.system_slug))]
pub async fn calculate_user_discounts(
    ctx: &SystemContext,
    db: &Database,
    user_id: i64,
    items_count: usize,
) -> AppResult<DiscountResult> {
    info!("Calculating tiered promotional discounts");

    let result = execute_discount_rules(user_id, items_count).await?;

    info!(discount_rate = result.rate, "Discount calculation completed");
    Ok(result)
}

info,foundry=debug,foundry_engine=debug

2026-10-14T10:20:00.102Z  INFO tower_http::trace::on_request: started processing request method=GET uri=/api/v1/s/blog/posts version=HTTP/1.1
2026-10-14T10:20:00.115Z  INFO tower_http::trace::on_response: finished processing request latency=13ms status=200

pub struct AuditLogEntity {
    pub id: i64,
    pub admin_id: Option<i64>,          // Operator admin ID (None for unauthenticated actions)
    pub admin_username: Option<String>,  // Operator username
    pub system_slug: Option<String>,     // Target subsystem slug
    pub method: String,                  // HTTP verb (POST, PUT, DELETE, etc.)
    pub path: String,                    // Request path (/api/v1/s/shop/orders)
    pub action_name: Option<String>,     // Human-readable description (e.g. "Create business record")
    pub headers: serde_json::Value,      // Redacted request headers as JSON
    pub query_params: Option<String>,    // Query string parameters
    pub body_params: Option<String>,     // Request body payload string
    pub ip_address: Option<String>,      // Client IP address
    pub user_agent: Option<String>,      // Client User-Agent string
    pub status_code: Option<i16>,        // HTTP response status code
    pub duration_ms: Option<i32>,        // Request processing latency in milliseconds
    pub created_at: DateTime<Utc>,       // Audit event timestamp
}

GET /api/v1/admin/audit-logs?page=1&page_size=20&system_slug=shop&admin_username=admin
Authorization: Bearer <ADMIN_JWT_TOKEN>

{
  "code": 0,
  "message": "success",
  "data": {
    "items": [
      {
        "id": 1024,
        "admin_username": "superadmin",
        "system_slug": "shop",
        "method": "POST",
        "path": "/api/v1/s/shop/goods",
        "action_name": "新增业务数据记录",
        "ip_address": "127.0.0.1",
        "status_code": 200,
        "duration_ms": 12,
        "created_at": "2026-10-14T10:30:00Z"
      }
    ],
    "total": 1,
    "page": 1,
    "page_size": 20,
    "total_pages": 1
  }
}

use foundry::prelude::*;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // 1. Initialize your custom tracing subscriber before building the app
    setup_custom_subscriber()?;

    // 2. Build the app with init_tracing(false)
    let app = FoundryApp::builder()
        .init_tracing(false)
        .build()
        .await?;

    app.run().await?;
    Ok(())
}

use tracing_subscriber::{layer::SubscriberExt, util::SubscriberInitExt, EnvFilter};

fn setup_custom_subscriber() -> anyhow::Result<()> {
    let filter = EnvFilter::try_from_default_env()
        .unwrap_or_else(|_| "info,foundry=info".into());

    tracing_subscriber::registry()
        .with(filter)
        .with(tracing_subscriber::fmt::layer().json())
        .try_init()?;

    Ok(())
}

use tracing_appender::rolling::{RollingFileAppender, Rotation};
use tracing_subscriber::{layer::SubscriberExt, util::SubscriberInitExt, EnvFilter};

fn setup_custom_subscriber() -> anyhow::Result<()> {
    let file_appender = RollingFileAppender::new(Rotation::DAILY, "./logs", "app.log");
    let (non_blocking, _guard) = tracing_appender::non_blocking(file_appender);

    let filter = EnvFilter::try_from_default_env()
        .unwrap_or_else(|_| "info,foundry=info".into());

    tracing_subscriber::registry()
        .with(filter)
        .with(tracing_subscriber::fmt::layer().with_writer(non_blocking))
        .try_init()?;

    Ok(())
}