mirror of
https://github.com/Nanaloveyuki/BitLogger.git
synced 2026-07-24 00:42:18 +00:00
📝 document file sink counters and resets
This commit is contained in:
Nanaloveyuki
@@ -0,0 +1,73 @@
|
||||
---
|
||||
name: file-sink-flush-failures
|
||||
group: api
|
||||
category: sink
|
||||
update-time: 20260613
|
||||
description: Read the number of flush failures recorded by a FileSink.
|
||||
key-word:
|
||||
- file
|
||||
- sink
|
||||
- flush
|
||||
- public
|
||||
---
|
||||
|
||||
## File-sink-flush-failures
|
||||
|
||||
Read the number of flush failures recorded by a `FileSink`. This helper is useful for diagnosing durability-path problems on the direct file sink.
|
||||
|
||||
### Interface
|
||||
|
||||
```moonbit
|
||||
pub fn FileSink::flush_failures(self : FileSink) -> Int {
|
||||
```
|
||||
|
||||
#### input
|
||||
|
||||
- `self : FileSink` - File sink whose flush-failure counter should be inspected.
|
||||
|
||||
#### output
|
||||
|
||||
- `Int` - Number of recorded flush failures.
|
||||
|
||||
### Explanation
|
||||
|
||||
Detailed rules explaining key parameters and behaviors
|
||||
|
||||
- The sink reports its recorded flush-failure count directly.
|
||||
- The counter is cumulative until reset.
|
||||
- This helper is observation-only and does not mutate sink state.
|
||||
|
||||
### How to Use
|
||||
|
||||
Here are some specific examples provided.
|
||||
|
||||
#### When Need Durability-path Diagnostics
|
||||
|
||||
When support output should show direct flush-path instability:
|
||||
```moonbit
|
||||
let count = sink.flush_failures()
|
||||
```
|
||||
|
||||
In this example, the direct file sink exposes whether flush attempts have been failing.
|
||||
|
||||
#### When Inspect Effects Of Auto-flush Policy
|
||||
|
||||
When runtime durability tuning should be inspected operationally:
|
||||
```moonbit
|
||||
ignore(sink.flush_failures())
|
||||
```
|
||||
|
||||
In this example, callers can correlate flush failures with direct file policy choices.
|
||||
|
||||
### Error Case
|
||||
|
||||
e.g.:
|
||||
- If callers need current policy and counters together, `state()` is the better API.
|
||||
|
||||
- This counter does not itself say whether the sink is open right now.
|
||||
|
||||
### Notes
|
||||
|
||||
1. Use this helper when direct flush-path reliability matters.
|
||||
|
||||
2. Pair it with `auto_flush_enabled()` and `flush()` when diagnosing durability behavior.
|
||||
@@ -0,0 +1,73 @@
|
||||
---
|
||||
name: file-sink-open-failures
|
||||
group: api
|
||||
category: sink
|
||||
update-time: 20260613
|
||||
description: Read the number of open failures recorded by a FileSink.
|
||||
key-word:
|
||||
- file
|
||||
- sink
|
||||
- open
|
||||
- public
|
||||
---
|
||||
|
||||
## File-sink-open-failures
|
||||
|
||||
Read the number of open failures recorded by a `FileSink`. This helper is useful for diagnosing direct file-availability or reopen problems.
|
||||
|
||||
### Interface
|
||||
|
||||
```moonbit
|
||||
pub fn FileSink::open_failures(self : FileSink) -> Int {
|
||||
```
|
||||
|
||||
#### input
|
||||
|
||||
- `self : FileSink` - File sink whose open-failure counter should be inspected.
|
||||
|
||||
#### output
|
||||
|
||||
- `Int` - Number of recorded open failures.
|
||||
|
||||
### Explanation
|
||||
|
||||
Detailed rules explaining key parameters and behaviors
|
||||
|
||||
- The sink reports its recorded open-failure count directly.
|
||||
- The counter is cumulative until reset.
|
||||
- This helper is observation-only and does not mutate sink state.
|
||||
|
||||
### How to Use
|
||||
|
||||
Here are some specific examples provided.
|
||||
|
||||
#### When Need File Availability Diagnostics
|
||||
|
||||
When operators should see whether file open or reopen failed:
|
||||
```moonbit
|
||||
let count = sink.open_failures()
|
||||
```
|
||||
|
||||
In this example, the direct sink exposes the open-failure metric directly.
|
||||
|
||||
#### When Validate Recovery Logic
|
||||
|
||||
When tests or support code should inspect whether reopen attempts failed:
|
||||
```moonbit
|
||||
ignore(sink.open_failures())
|
||||
```
|
||||
|
||||
In this example, the counter helps confirm whether file-open problems occurred during runtime.
|
||||
|
||||
### Error Case
|
||||
|
||||
e.g.:
|
||||
- If callers need the full file status snapshot rather than one counter, `state()` is the better API.
|
||||
|
||||
- This counter does not tell you which particular reopen attempt failed.
|
||||
|
||||
### Notes
|
||||
|
||||
1. Use this helper for focused direct file-open diagnostics.
|
||||
|
||||
2. Pair it with `reopen(...)` and `is_available()` during recovery analysis.
|
||||
@@ -0,0 +1,70 @@
|
||||
---
|
||||
name: file-sink-reset-failure-counters
|
||||
group: api
|
||||
category: sink
|
||||
update-time: 20260613
|
||||
description: Reset the file failure counters recorded by a FileSink.
|
||||
key-word:
|
||||
- file
|
||||
- sink
|
||||
- reset
|
||||
- public
|
||||
---
|
||||
|
||||
## File-sink-reset-failure-counters
|
||||
|
||||
Reset the file failure counters recorded by a `FileSink`. This helper clears open, write, flush, and rotation failure metrics together on the direct sink.
|
||||
|
||||
### Interface
|
||||
|
||||
```moonbit
|
||||
pub fn FileSink::reset_failure_counters(self : FileSink) -> Unit {
|
||||
```
|
||||
|
||||
#### input
|
||||
|
||||
- `self : FileSink` - File sink whose file failure counters should be cleared.
|
||||
|
||||
### Explanation
|
||||
|
||||
Detailed rules explaining key parameters and behaviors
|
||||
|
||||
- This helper clears open, write, flush, and rotation failure counters together.
|
||||
- It is useful after diagnostics, recovery, or controlled tests.
|
||||
- It does not reopen the sink or change file policy.
|
||||
|
||||
### How to Use
|
||||
|
||||
Here are some specific examples provided.
|
||||
|
||||
#### When Need A Fresh Diagnostics Baseline
|
||||
|
||||
When previous failure history should be cleared before a new observation window:
|
||||
```moonbit
|
||||
sink.reset_failure_counters()
|
||||
```
|
||||
|
||||
In this example, future failures can be measured from a clean baseline.
|
||||
|
||||
#### When Validate Post-recovery Behavior
|
||||
|
||||
When recovery logic should clear old counters before rechecking health:
|
||||
```moonbit
|
||||
sink.reset_failure_counters()
|
||||
ignore(sink.open_failures())
|
||||
```
|
||||
|
||||
In this example, the direct sink starts a new diagnostics window after reset.
|
||||
|
||||
### Error Case
|
||||
|
||||
e.g.:
|
||||
- If callers need the current values before clearing them, they should read the counters or `state()` first.
|
||||
|
||||
- This helper resets metrics only; it does not fix the underlying cause of past failures.
|
||||
|
||||
### Notes
|
||||
|
||||
1. Use this helper after diagnostics or recovery, not before capturing needed evidence.
|
||||
|
||||
2. It is the reset companion for the direct file failure-counter helpers.
|
||||
@@ -0,0 +1,71 @@
|
||||
---
|
||||
name: file-sink-reset-policy
|
||||
group: api
|
||||
category: sink
|
||||
update-time: 20260613
|
||||
description: Reset the runtime file policy of a FileSink back to its original defaults.
|
||||
key-word:
|
||||
- file
|
||||
- sink
|
||||
- reset
|
||||
- public
|
||||
---
|
||||
|
||||
## File-sink-reset-policy
|
||||
|
||||
Reset the runtime file policy of a `FileSink` back to its original defaults. This helper restores append, auto-flush, and rotation policy together on the direct sink.
|
||||
|
||||
### Interface
|
||||
|
||||
```moonbit
|
||||
pub fn FileSink::reset_policy(self : FileSink) -> Unit {
|
||||
```
|
||||
|
||||
#### input
|
||||
|
||||
- `self : FileSink` - File sink whose file policy should be restored.
|
||||
|
||||
### Explanation
|
||||
|
||||
Detailed rules explaining key parameters and behaviors
|
||||
|
||||
- This helper restores the sink's stored default append, auto-flush, and rotation settings.
|
||||
- It is the inverse of runtime policy drift, not a generic reopen or flush action.
|
||||
- It changes policy only and does not reopen the sink automatically.
|
||||
|
||||
### How to Use
|
||||
|
||||
Here are some specific examples provided.
|
||||
|
||||
#### When Need To Undo Runtime Policy Changes
|
||||
|
||||
When direct file policy should return to the original configured defaults:
|
||||
```moonbit
|
||||
sink.reset_policy()
|
||||
```
|
||||
|
||||
In this example, append, auto-flush, and rotation settings are restored together.
|
||||
|
||||
#### When Use Drift-aware Recovery
|
||||
|
||||
When reset should only happen after runtime changes:
|
||||
```moonbit
|
||||
if !sink.policy_matches_default() {
|
||||
sink.reset_policy()
|
||||
}
|
||||
```
|
||||
|
||||
In this example, reset is only applied when runtime policy has diverged.
|
||||
|
||||
### Error Case
|
||||
|
||||
e.g.:
|
||||
- If callers need to restore only one setting, a narrower setter may be more appropriate than a full policy reset.
|
||||
|
||||
- This helper does not reopen the file or prove current availability.
|
||||
|
||||
### Notes
|
||||
|
||||
1. Use this helper when the original bundled file policy should be restored intact.
|
||||
|
||||
2. It pairs naturally with `policy_matches_default()` and `default_policy()`.
|
||||
@@ -0,0 +1,73 @@
|
||||
---
|
||||
name: file-sink-rotation-failures
|
||||
group: api
|
||||
category: sink
|
||||
update-time: 20260613
|
||||
description: Read the number of rotation failures recorded by a FileSink.
|
||||
key-word:
|
||||
- file
|
||||
- sink
|
||||
- rotation
|
||||
- public
|
||||
---
|
||||
|
||||
## File-sink-rotation-failures
|
||||
|
||||
Read the number of rotation failures recorded by a `FileSink`. This helper is useful when direct runtime rotation behavior should be observed operationally.
|
||||
|
||||
### Interface
|
||||
|
||||
```moonbit
|
||||
pub fn FileSink::rotation_failures(self : FileSink) -> Int {
|
||||
```
|
||||
|
||||
#### input
|
||||
|
||||
- `self : FileSink` - File sink whose rotation-failure counter should be inspected.
|
||||
|
||||
#### output
|
||||
|
||||
- `Int` - Number of recorded rotation failures.
|
||||
|
||||
### Explanation
|
||||
|
||||
Detailed rules explaining key parameters and behaviors
|
||||
|
||||
- The sink reports its recorded rotation-failure count directly.
|
||||
- The counter is cumulative until reset.
|
||||
- This helper is observation-only and does not mutate sink state.
|
||||
|
||||
### How to Use
|
||||
|
||||
Here are some specific examples provided.
|
||||
|
||||
#### When Need Rotation-specific Diagnostics
|
||||
|
||||
When support output should reveal whether direct sink rotation is failing:
|
||||
```moonbit
|
||||
let count = sink.rotation_failures()
|
||||
```
|
||||
|
||||
In this example, the concrete file sink exposes a focused metric for rotation-path health.
|
||||
|
||||
#### When Validate Runtime Rotation Tuning
|
||||
|
||||
When changed rotation settings should be checked in operation:
|
||||
```moonbit
|
||||
ignore(sink.rotation_failures())
|
||||
```
|
||||
|
||||
In this example, callers can observe whether runtime rotation changes introduced problems.
|
||||
|
||||
### Error Case
|
||||
|
||||
e.g.:
|
||||
- If callers need both rotation config and failure metrics, they should combine this helper with `rotation_config()` or `state()`.
|
||||
|
||||
- This counter alone does not say whether the sink is currently available.
|
||||
|
||||
### Notes
|
||||
|
||||
1. Use this helper when diagnosing direct file rotation reliability.
|
||||
|
||||
2. It is especially relevant when runtime rotation policy can change after startup.
|
||||
@@ -0,0 +1,73 @@
|
||||
---
|
||||
name: file-sink-write-failures
|
||||
group: api
|
||||
category: sink
|
||||
update-time: 20260613
|
||||
description: Read the number of write failures recorded by a FileSink.
|
||||
key-word:
|
||||
- file
|
||||
- sink
|
||||
- write
|
||||
- public
|
||||
---
|
||||
|
||||
## File-sink-write-failures
|
||||
|
||||
Read the number of write failures recorded by a `FileSink`. This helper is useful for diagnosing direct runtime write-path problems.
|
||||
|
||||
### Interface
|
||||
|
||||
```moonbit
|
||||
pub fn FileSink::write_failures(self : FileSink) -> Int {
|
||||
```
|
||||
|
||||
#### input
|
||||
|
||||
- `self : FileSink` - File sink whose write-failure counter should be inspected.
|
||||
|
||||
#### output
|
||||
|
||||
- `Int` - Number of recorded write failures.
|
||||
|
||||
### Explanation
|
||||
|
||||
Detailed rules explaining key parameters and behaviors
|
||||
|
||||
- The sink reports its recorded write-failure count directly.
|
||||
- The counter is cumulative until reset.
|
||||
- This helper is observation-only and does not mutate sink state.
|
||||
|
||||
### How to Use
|
||||
|
||||
Here are some specific examples provided.
|
||||
|
||||
#### When Need Runtime Write-path Diagnostics
|
||||
|
||||
When support output should show whether direct writes have been failing:
|
||||
```moonbit
|
||||
let count = sink.write_failures()
|
||||
```
|
||||
|
||||
In this example, callers get a focused signal for direct file write-path health.
|
||||
|
||||
#### When Compare Sink Health After Recovery
|
||||
|
||||
When recovery logic should verify whether new failures still occur:
|
||||
```moonbit
|
||||
ignore(sink.write_failures())
|
||||
```
|
||||
|
||||
In this example, the metric helps measure whether runtime writes improved after intervention.
|
||||
|
||||
### Error Case
|
||||
|
||||
e.g.:
|
||||
- If callers need a fuller view of file health, `state()` may be a better API.
|
||||
|
||||
- This counter does not itself distinguish open-path issues from write-path issues.
|
||||
|
||||
### Notes
|
||||
|
||||
1. Use this helper for focused write-failure visibility.
|
||||
|
||||
2. Pair it with `flush_failures()` when diagnosing direct output-path instability.
|
||||
@@ -154,6 +154,12 @@ BitLogger API navigation.
|
||||
- [file-sink-default-policy.md](./file-sink-default-policy.md)
|
||||
- [file-sink-policy-matches-default.md](./file-sink-policy-matches-default.md)
|
||||
- [file-sink-state-method.md](./file-sink-state-method.md)
|
||||
- [file-sink-rotation-failures.md](./file-sink-rotation-failures.md)
|
||||
- [file-sink-open-failures.md](./file-sink-open-failures.md)
|
||||
- [file-sink-write-failures.md](./file-sink-write-failures.md)
|
||||
- [file-sink-flush-failures.md](./file-sink-flush-failures.md)
|
||||
- [file-sink-reset-failure-counters.md](./file-sink-reset-failure-counters.md)
|
||||
- [file-sink-reset-policy.md](./file-sink-reset-policy.md)
|
||||
- [file-sink-reopen.md](./file-sink-reopen.md)
|
||||
- [file-sink-reopen-with-current-policy.md](./file-sink-reopen-with-current-policy.md)
|
||||
- [file-sink-reopen-append.md](./file-sink-reopen-append.md)
|
||||
|
||||
Reference in New Issue
Block a user