日志、链路追踪与审计日志指南

flowchart TD
    subgraph Client["客户端请求"]
        Req["HTTP 请求 /api/v1/..."]
    end

    subgraph Layer1["1. HTTP 中间件追踪层 (TraceLayer)"]
        TL["tower_http::TraceLayer\n记录 Method、Path、Status、处理耗时"]
    end

    subgraph Layer2["2. 业务操作审计日志层 (Audit Interceptor)"]
        AI["audit_interceptor 中间件\n识别写操作 (POST/PUT/PATCH/DELETE) 与登录"]
        Redact["敏感信息脱敏 (Authorization: [REDACTED])"]
        AsyncWrite["Tokio 异步非阻塞持久化"]
        AuditTable[("数据库 audit_logs 表")]

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

    subgraph Layer3["3. 应用业务与领域日志层 (Tracing Framework)"]
        Controller["控制器 / 路由 Handler"]
        Logic["业务领域服务 (Service / Logic)"]
        Hooks["生命周期突变钩子 (Mutation Hooks)"]
        Storage["数据库与存储引擎 (Storage Engine)"]

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

        LogMacros["tracing 宏: info! / warn! / error! / debug! / trace!\n结构化 KV 字段与 #[instrument] 链路追踪"]
        Controller -.-> LogMacros
        Logic -.-> LogMacros
        Hooks -.-> LogMacros
        Storage -.-> LogMacros
    end

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

// 方式 1: 推荐方式，通过 prelude 一站式导入
use foundry::prelude::*;

// 方式 2: 通过专用命名空间导入
use foundry::log::{info, warn, error, debug, trace};

// 普通文本日志
info!("Foundry 业务子系统初始化完成");

// 格式化输出 (标准 print 格式语法)
warn!("租户 [{}] 当前配额占用已达 {}%", tenant_slug, usage_pct);

// 错误日志输出 (配合 thiserror 或 anyhow 错误)
if let Err(err) = sync_data().await {
    error!("数据同步异常失败: {:?}", err);
}

// 调试日志 (开发排查使用，生产级别可过滤)
debug!("解析到的原始报文长度: {} 字节", payload.len());

// 追踪详细过程 (深入微循环、锁与细节)
trace!("正在遍历用户标签集合: index = {}", idx);

use foundry::prelude::*;

pub async fn process_order(ctx: &SystemContext, order_id: &str, amount: f64) {
    // 1. 基础键值对：字段名 = 变量值
    info!(
        order_id = order_id,
        amount = amount,
        "正在处理用户下单结算"
    );

    // 2. 缩写语法：使用 % 强制采用 Display 特征格式化
    info!(
        %order_id,
        tenant = %ctx.system_slug,
        client_ip = ?ctx.client_ip, // 使用 ? 采用 Debug 特征格式化
        "结算前风控检查通过"
    );

    // 3. 错误捕获与结构化输出
    if amount < 0.0 {
        error!(
            %order_id,
            invalid_amount = amount,
            tenant = %ctx.system_slug,
            "订单金额非法，终止执行"
        );
    }
}

{
  "timestamp": "2026-10-14T10:15:30.123Z",
  "level": "INFO",
  "message": "结算前风控检查通过",
  "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;

// 自动捕获函数入参（可针对敏感参数如密码进行跳过）
#[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!("开始计算会员优惠折扣梯度");

    // 模拟复杂耗时计算
    let result = execute_discount_rules(user_id, items_count).await?;

    info!(discount_rate = result.rate, "折扣计算完成");
    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>,          // 操作管理员 ID（未登录操作为 None）
    pub admin_username: Option<String>,  // 管理员用户名
    pub system_slug: Option<String>,     // 关联的业务子系统标识
    pub method: String,                  // HTTP 动词 (POST, PUT, DELETE 等)
    pub path: String,                    // 请求完整路径 (/api/v1/s/shop/orders)
    pub action_name: Option<String>,     // 人类可读的操作描述 (如 "创建业务记录", "管理员登录")
    pub headers: serde_json::Value,      // 脱敏后的请求头 JSON
    pub query_params: Option<String>,    // Query 查询字符串
    pub body_params: Option<String>,     // 提交的请求载荷 (JSON 字符串)
    pub ip_address: Option<String>,      // 客户端真实 IP
    pub user_agent: Option<String>,      // 客户端浏览器 / API 标识
    pub status_code: Option<i16>,        // 响应 HTTP 状态码 (如 200, 422)
    pub duration_ms: Option<i32>,        // 请求执行耗时 (毫秒)
    pub created_at: DateTime<Utc>,       // 操作触发时间
}

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. 在构建应用之前，初始化你自定义的 tracing-subscriber
    setup_custom_logging()?;

    // 2. 传入 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_logging() -> anyhow::Result<()> {
    let filter = EnvFilter::try_from_default_env()
        .unwrap_or_else(|_| "info,foundry=info".into());

    // 使用 json 格式化输出到标准输出 (stdout)
    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_logging() -> anyhow::Result<()> {
    // 每天自动切割日志文件，存储在 ./logs/app.2026-10-14.log
    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()?;

    // 注意：_guard 需要保留在 main 函数的生命周期内以确保存储缓冲区平稳 flush
    Ok(())
}