TCIS.Logging.Autofac 1.0.9

TCIS.Logging.Autofac

A module supporting AOP (Aspect-Oriented Programming) for the logging system in TCIS, utilizing the Autofac library.

🌟 Overview

TCIS.Logging.Autofac replaces the default .NET DI Container with Autofac. Specifically, it provides:

• Assembly Scanning: Automatically scans and registers Services by Suffixes.
• AOP Interception: Automatically intercepts function calls to consistently log input parameters, execution time, and exceptions, without requiring repetitive logging code in the Business Logic.

📦 Installation

Install the package via .NET CLI:

dotnet add package TCIS.Logging.Autofac

⚙️ Configuration (appsettings.json)

You can customize AOP configurations (e.g., the list of suffixes to auto-register) in the TLogSettings:AopSettings section (default):

{
  "TLogSettings": {
    "AopSettings": {
      "DiRegistrationSuffixes": [ "Service", "Repository", "Manager" ]
    }
  }
}

Lọc field của data.result

IncludedSuffixes rỗng hoặc * chọn tất cả lớp nghiệp vụ đủ điều kiện trong TargetNamespaces. Ranh giới bảo vệ vẫn áp dụng: không proxy IHostedService/BackgroundService, startup filter, HttpClient builder filter, EventBus serializer/invoker hoặc chính hạ tầng logging/capture. Proxy interface có thể che kiểu BackgroundService, làm host mất giám sát lỗi; các hook còn nhận/trả delegate hoặc metadata vận chuyển không phù hợp để serialize như DTO nghiệp vụ. Kiểm tra này áp dụng cả instance do factory trả về và module Pluggable. Worker vẫn có thể gọi ILogWriter và các service nghiệp vụ được intercept; capture HTTP/queue tiếp tục dùng adapter tại boundary tương ứng.

TLogInterceptor là nơi duy nhất áp bộ lọc field của kết quả (ResultIncludeFields, ResultIncludeFieldsByMethod, ResultFilterMaxItems trong TLogSettings). Ví dụ:

{
  "TLogSettings": {
    "ResultIncludeFields": ["id", "code", "cd"],
    "ResultIncludeFieldsByMethod": { "OrderService.Get": ["id"] }
  }
}

• Rỗng hoặc có "*" = ghi hết; khai báo toàn mục rỗng/gõ nhầm = không ghi result (fail-closed). Khoá ByMethod dùng tên lớp hiện thực (Class hoặc Class.Method, không phân biệt hoa thường).
• Duyệt vét cạn mọi tầng object/list lồng nhau; field khớp được giữ nguyên cả giá trị; phần tử list không có field nào bị bỏ.
• Che dữ liệu nhạy cảm luôn thắng; lọc chạy trước ResponseSize và ResponseSummary.
• Quyết định lọc được cache theo phương thức của lớp hiện thực (chung nơi cache ExcludeClasses/ExcludeMethods).
• Controller (ControllerLoggingFilter), gRPC và TLogWriter chưa lọc — chỉ AOP.

Chi tiết đầy đủ: README của TCIS.Logging.

Chẩn đoán treo (LogInvocationStart, SlowCallThreshold)

Log AOP (TLogInterceptor) chỉ ghi khi Proceed() trả về (trong finally). Một lời gọi treo — chờ DB, lock, HTTP không timeout — vì thế không để lại bản ghi nào. Hai tuỳ chọn trong TLogSettings bù chỗ này:

{
  "TLogSettings": {
    "LogInvocationStart": true,
    "InvocationStartLevel": "INFO",
    "SlowCallThreshold": "00:00:30"
  }
}

Cơ chế và giới hạn:

• Một sweeper dùng chung (một Timer, chu kỳ 1 giây, tạo lười) quét các lời gọi đang chạy — độ phân giải ~1 giây, không phải mili giây; không tạo Timer cho từng lời gọi. WARN bắn đúng một lần, không lặp theo bội số ngưỡng.
• Ngữ cảnh (WorkContext, Activity) được chụp trên thread gọi lúc bắt đầu nên WARN vẫn mang đúng transaction/user dù sweeper chạy ở thread khác. WARN không bắn sau khi hàm đã hoàn tất; hàm xong trước ngưỡng thì không có WARN.
• Hàm chạy lâu một cách hợp lệ (job, export) sẽ sinh WARN: loại chúng bằng ExcludeClasses/ExcludeMethods (đường bị loại không đăng ký sổ đang chạy). Khuyến nghị bật SlowCallThreshold cho API đồng bộ, không bật toàn cục mù quáng.
• Cách đọc log: thấy WARN ... still running mà chưa có bản ghi kết thúc cùng event.id ⇒ lời gọi đã vào hàm và đang treo. Phạm vi: cả ba đường — hàm đồng bộ, Task, Task<T>; chỉ TLogInterceptor (controller/gRPC không có).
• Giới hạn khi thread pool cạn: sweeper chạy trên thread pool. Đúng lúc thread pool bị bão hoà (thường đi kèm treo) callback có thể bị trễ hoặc không chạy, khi đó không có WARN — không có WARN chưa chứng minh là không treo.
• event.id dùng chung cho started/WARN/kết thúc. Nếu pipeline phía sau (Filebeat/Logstash/ES ingest) đặt _id hoặc dedupe theo event.id, bản ghi kết thúc sẽ đè bản ghi treo. Thư viện không dùng event.id làm khoá chống trùng (dùng RecordId riêng cho spool/biên nhận). Đã kiểm trên Kibana UAT ngày 21/10/2026 (data view tcis-logs*, gồm các service eBerth): _id khác event.id ở mọi bản ghi lấy mẫu, nên ở đó không bị đè. Kết quả này phụ thuộc cấu hình pipeline của từng môi trường — môi trường khác (production, cụm khác) thì kiểm lại bằng cách so _id với event.id của một bản ghi trong Discover (tab JSON), hoặc bật thử một service rồi tìm theo event.id: thấy 2 bản ghi (started + kết thúc) là không bị đè.

Điều tra nhanh một service nghi bị treo ở Proceed()

Cấu hình đọc lúc khởi động (IOptions): đổi xong phải restart service đó. Mỗi service có appsettings riêng nên chỉ bật cho service đang nghi ngờ.

{
  "TLogSettings": {
    "SlowCallThreshold": "00:00:10"
  }
}

1. Bước 1 — chỉ cần SlowCallThreshold (ghi WARN nên không phải hạ min level, chi phí thấp). Thấy WARN ... still running mà chưa có bản ghi kết thúc cùng event.id ⇒ lời gọi đã vào hàm và đang treo; kết luận "API chưa được gọi" là sai. Hàm chạy lâu hợp lệ gây ồn thì thêm vào ExcludeMethods/ExcludeClasses.
2. Bước 2 — nếu cần biết mọi lời gọi có vào hàm hay không, thêm "LogInvocationStart": true và "InvocationStartLevel": "INFO" (hoặc giữ DEBUG và hạ min level bằng Dynamic Log Level). Nặng hơn: mỗi lời gọi được log thêm một bản ghi, chỉ bật trong lúc điều tra rồi tắt.
3. Điều tra xong: bỏ hai khoá trên và restart.

🚀 Usage

In Program.cs, configure the IHostBuilder to use UseTAutofacLogging:

using Microsoft.Extensions.Hosting;
using System.Reflection;

var builder = WebApplication.CreateBuilder(args);

// Configure Autofac as the main DI Container and configure AOP Logging
builder.Host.UseTAutofacLogging(
    scanAssemblies: new[] { Assembly.GetExecutingAssembly() }, // Scan the current Assembly
    configSection: "TLogSettings:AopSettings",                 // Configuration section
    configureOptions: options => 
    {
        // Can be configured via code instead of appsettings
        options.DiRegistrationSuffixes.Add("Facade");
    }
);

var app = builder.Build();
app.Run();

💡 Basic Example

When you have an Interface and an implementation Class with a name ending in Service (e.g., IUserService and UserService):

public interface IUserService 
{
    Task<User> GetUserAsync(int id);
}

// This class will be automatically registered by Autofac (due to the 'Service' suffix)
// and automatically intercepted to log Input, Output, and Exceptions.
public class UserService : IUserService
{
    public async Task<User> GetUserAsync(int id)
    {
        return await _db.Users.FindAsync(id);
    }
}

By simply configuring UseTAutofacLogging(), you no longer need to manually register builder.Services.AddScoped<IUserService, UserService>().