mirror of
https://github.com/Nanaloveyuki/BitLogger.git
synced 2026-05-30 15:42:25 +00:00
Nanaloveyuki
92 lines
2.5 KiB
Markdown
92 lines
2.5 KiB
Markdown
---
|
|
name: record-new
|
|
group: api
|
|
category: record
|
|
update-time: 20260512
|
|
description: Construct a log record explicitly from level, message, timestamp, target, and fields.
|
|
key-word:
|
|
- record
|
|
- constructor
|
|
- logging
|
|
- public
|
|
---
|
|
|
|
## Record-new
|
|
|
|
Construct a `Record` explicitly from its core fields. This is the low-level record constructor used beneath the logger APIs and is useful when records need to be created directly for formatting, filtering, sink callbacks, or tests.
|
|
|
|
### Interface
|
|
|
|
```moonbit
|
|
pub fn Record::new(
|
|
level : Level,
|
|
message : String,
|
|
timestamp_ms~ : UInt64 = 0UL,
|
|
target~ : String = "",
|
|
fields~ : Array[Field] = [],
|
|
) -> Record {}
|
|
```
|
|
|
|
#### input
|
|
|
|
- `level : Level` - Severity level stored in the record.
|
|
- `message : String` - Log message text.
|
|
- `timestamp_ms : UInt64` - Timestamp in milliseconds, or `0UL` when omitted.
|
|
- `target : String` - Target label for the record.
|
|
- `fields : Array[Field]` - Structured field list attached to the record.
|
|
|
|
#### output
|
|
|
|
- `Record` - Structured log record value.
|
|
|
|
### Explanation
|
|
|
|
Detailed rules explaining key parameters and behaviors
|
|
|
|
- The constructor stores the provided values directly without extra processing.
|
|
- `timestamp_ms` defaults to `0UL`, which is the same no-timestamp convention used by loggers when timestamping is disabled.
|
|
- `target` and `fields` are optional and may be left empty.
|
|
- This API is useful when records need to be created outside the normal `Logger::log(...)` flow.
|
|
|
|
### How to Use
|
|
|
|
Here are some specific examples provided.
|
|
|
|
#### When Create A Record For Formatter Tests
|
|
|
|
When a formatting path should be exercised directly:
|
|
```moonbit
|
|
let rec = Record::new(
|
|
Level::Info,
|
|
"service started",
|
|
target="app",
|
|
fields=[field("region", "cn")],
|
|
)
|
|
```
|
|
|
|
In this example, the record can be passed straight to `format_text(...)` or `format_json(...)`.
|
|
|
|
#### When Feed A Callback Or Predicate Manually
|
|
|
|
When tests or adapters work with records directly:
|
|
```moonbit
|
|
let rec = Record::new(Level::Warn, "retry scheduled")
|
|
let keep = level_at_least(Level::Info)(rec)
|
|
```
|
|
|
|
In this example, the record exists independently of any logger instance.
|
|
|
|
### Error Case
|
|
|
|
e.g.:
|
|
- If `target` is empty, the record remains valid and simply carries no target label.
|
|
|
|
- If `fields` is empty, the record still works normally with formatters, sinks, and predicates.
|
|
|
|
### Notes
|
|
|
|
1. Prefer logger write APIs for normal application logging; use `Record::new(...)` when direct record construction is specifically needed.
|
|
|
|
2. This constructor is especially useful in tests and low-level integrations.
|
|
|