TCIS.Logging 1.0.8-rc.2

TCIS.Logging

The core library providing foundational abstractions and infrastructure for the Logging system across all TCIS applications.

🌟 Overview

TCIS.Logging serves as the standard logging framework, integrated with IWorkContext to capture user and trace information, while utilizing a Channel mechanism for high-performance, asynchronous (non-blocking) logging.

📦 Installation

Install the package via NuGet or .NET CLI:

dotnet add package TCIS.Logging

⚙️ Configuration (appsettings.json)

You can configure the queue limit for the Background Logging Process:

{
  "TLogSettings": {
    "MaxQueueSize": 10000,
    "SiteCode": "HP9"
  }
}

SiteCode (tuỳ chọn) là nhãn application.site_code dự phòng cho bản ghi không có WorkContext — consumer Kafka/Wolverine, hosted service, log của framework. Nó không nạp vào WorkContext và không ảnh hưởng cách ly dữ liệu; WorkContext.Tenant.SiteCode luôn thắng khi có giá trị. Pod chạy nhiều site thì không đặt. Biến môi trường tương ứng: TLogSettings__SiteCode.

Giới hạn dung lượng data.parameters / data.result

{
  "TLogSettings": {
    "ParameterSize": 2048,
    "ResponseSize": 1000
  }
}

Hai ngưỡng này độc lập nhau; hạ ParameterSize không ảnh hưởng ResponseSize.

Chỉ ghi một số field của data.result (whitelist)

Mặc định data.result ghi cả đối tượng trả về. Muốn chỉ giữ vài field:

{
  "TLogSettings": {
    "ResultIncludeFields": ["id", "code", "cd"],
    "ResultIncludeFieldsByMethod": {
      "OrderService": ["id", "status"],
      "OrderService.Get": ["id"],
      "Repo`1.Get": ["*"]
    },
    "ResultFilterMaxItems": 1000
  }
}

Quy tắc khớp:

• Duyệt vét cạn mọi tầng object/list lồng nhau tới tận lá (object → list → object → list…), với N phần tử bất kỳ; không dừng ở tầng 1 hay ở phần tử đầu.
• Tên field so qua chuẩn hoá: user_id, userId, UserId tương đương, không phân biệt hoa thường.
• Field khớp được giữ nguyên cả giá trị: nếu nó là object/list thì giữ nguyên cả cây bên trong.
• Field không khớp mà chứa object/list thì đi sâu tiếp; nhánh không còn field nào bị bỏ. Phần tử list không có field nào khớp bị bỏ khỏi list; phần tử scalar trong list bị bỏ.
• Che dữ liệu nhạy cảm luôn thắng: password/token… vẫn thành *** kể cả khi nằm trong field được giữ.
• Lọc chạy trước ResponseSize và trước ResponseSummary (whitelist chạy trước; ResponseSummary.ExcludedFields là blacklist chạy sau, áp trên phần đã giữ). Không còn field nào khớp thì data.result bỏ trống.
• Chỉ áp cho TLogInterceptor (AOP, package TCIS.Logging.Autofac). TLogWriter, ControllerLoggingFilter, TGrpcClientInterceptor/TGrpcServerInterceptor chưa lọc.
• Kết quả được cache theo phương thức của lớp hiện thực lúc gọi lần đầu; đổi cấu hình lúc đang chạy không có hiệu lực với phương thức đã gọi.

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, add the Logging service to the DI container:

using TCIS.Logging.Extensions;

var builder = WebApplication.CreateBuilder(args);

// Method 1: Read from IConfiguration (default section: "TLogSettings")
builder.Services.AddTLogging(builder.Configuration);

// Method 2: Configure via Action
builder.Services.AddTLogging(options => 
{
    options.MaxQueueSize = 5000;
});

// (Optional) Add Console Sink to display formatted logs in Development
if (builder.Environment.IsDevelopment())
{
    builder.Services.AddTCISConsoleSink();
}

💡 Basic Example

Use ILogWriter (do not use ILogger directly from Microsoft Logging to comply with TCIS rules) in your services:

using TCIS.Logging.Abstractions.Abstractions;

public class MyService
{
    private readonly ILogWriter _logger;
    private const string Provider = "my-service";

    public MyService(ILogWriter logger)
    {
        _logger = logger;
    }

    public async Task DoWorkAsync()
    {
        _logger.LogInformation(
            $"[{Provider}] DoWorkAsync: Processing data...", 
            nameof(DoWorkAsync), 
            new { Step = 1, Data = "Sample" }
        );
    }
}