mirror of
https://github.com/Nanaloveyuki/BitLogger.git
synced 2026-07-24 00:42:18 +00:00
📝 document runtime sink failure counters
This commit is contained in:
Nanaloveyuki
@@ -377,6 +377,11 @@ BitLogger API navigation.
|
||||
- [runtime-sink-file-clear-rotation.md](./runtime-sink-file-clear-rotation.md)
|
||||
- [runtime-sink-file-flush.md](./runtime-sink-file-flush.md)
|
||||
- [runtime-sink-file-close.md](./runtime-sink-file-close.md)
|
||||
- [runtime-sink-file-open-failures.md](./runtime-sink-file-open-failures.md)
|
||||
- [runtime-sink-file-write-failures.md](./runtime-sink-file-write-failures.md)
|
||||
- [runtime-sink-file-flush-failures.md](./runtime-sink-file-flush-failures.md)
|
||||
- [runtime-sink-file-rotation-failures.md](./runtime-sink-file-rotation-failures.md)
|
||||
- [runtime-sink-file-reset-failure-counters.md](./runtime-sink-file-reset-failure-counters.md)
|
||||
- [configured-logger.md](./configured-logger.md)
|
||||
- [configured-logger-flush.md](./configured-logger-flush.md)
|
||||
- [configured-logger-drain.md](./configured-logger-drain.md)
|
||||
|
||||
@@ -0,0 +1,74 @@
|
||||
---
|
||||
name: runtime-sink-file-flush-failures
|
||||
group: api
|
||||
category: runtime
|
||||
update-time: 20260613
|
||||
description: Read the number of flush failures recorded by a file-backed RuntimeSink.
|
||||
key-word:
|
||||
- runtime
|
||||
- sink
|
||||
- file
|
||||
- public
|
||||
---
|
||||
|
||||
## Runtime-sink-file-flush-failures
|
||||
|
||||
Read the number of flush failures recorded by a file-backed `RuntimeSink`. This helper is useful for direct runtime diagnostics around durability-path problems.
|
||||
|
||||
### Interface
|
||||
|
||||
```moonbit
|
||||
pub fn RuntimeSink::file_flush_failures(self : RuntimeSink) -> Int {
|
||||
```
|
||||
|
||||
#### input
|
||||
|
||||
- `self : RuntimeSink` - Runtime sink whose flush-failure counter should be inspected.
|
||||
|
||||
#### output
|
||||
|
||||
- `Int` - Number of recorded flush failures.
|
||||
|
||||
### Explanation
|
||||
|
||||
Detailed rules explaining key parameters and behaviors
|
||||
|
||||
- Plain `File` runtime variants report the wrapped `FileSink` flush-failure count.
|
||||
- `QueuedFile` runtime variants forward the metric from the wrapped inner `FileSink`.
|
||||
- Non-file runtime variants return `0`.
|
||||
- The counter is cumulative until `file_reset_failure_counters()` clears it.
|
||||
|
||||
### How to Use
|
||||
|
||||
Here are some specific examples provided.
|
||||
|
||||
#### When Need Durability-path Diagnostics
|
||||
|
||||
When support output should show flush-path instability:
|
||||
```moonbit
|
||||
let count = sink.file_flush_failures()
|
||||
```
|
||||
|
||||
In this example, the runtime sink exposes whether file flush attempts have been failing.
|
||||
|
||||
#### When Inspect Effects Of Auto-flush Policy
|
||||
|
||||
When runtime durability tuning should be inspected operationally:
|
||||
```moonbit
|
||||
ignore(sink.file_flush_failures())
|
||||
```
|
||||
|
||||
In this example, callers can correlate flush failures with direct runtime file policy choices.
|
||||
|
||||
### Error Case
|
||||
|
||||
e.g.:
|
||||
- If the runtime sink is not file-backed, the method returns `0`.
|
||||
|
||||
- If callers need current policy and counters together, `file_state()` is the better API.
|
||||
|
||||
### Notes
|
||||
|
||||
1. Use this helper when direct runtime flush-path reliability matters.
|
||||
|
||||
2. Pair it with `file_auto_flush()` and `file_flush()` when diagnosing durability behavior.
|
||||
@@ -0,0 +1,74 @@
|
||||
---
|
||||
name: runtime-sink-file-open-failures
|
||||
group: api
|
||||
category: runtime
|
||||
update-time: 20260613
|
||||
description: Read the number of open failures recorded by a file-backed RuntimeSink.
|
||||
key-word:
|
||||
- runtime
|
||||
- sink
|
||||
- file
|
||||
- public
|
||||
---
|
||||
|
||||
## Runtime-sink-file-open-failures
|
||||
|
||||
Read the number of open failures recorded by a file-backed `RuntimeSink`. This helper is useful for direct runtime diagnostics around file availability and reopen behavior.
|
||||
|
||||
### Interface
|
||||
|
||||
```moonbit
|
||||
pub fn RuntimeSink::file_open_failures(self : RuntimeSink) -> Int {
|
||||
```
|
||||
|
||||
#### input
|
||||
|
||||
- `self : RuntimeSink` - Runtime sink whose open-failure counter should be inspected.
|
||||
|
||||
#### output
|
||||
|
||||
- `Int` - Number of recorded open failures.
|
||||
|
||||
### Explanation
|
||||
|
||||
Detailed rules explaining key parameters and behaviors
|
||||
|
||||
- Plain `File` runtime variants report the wrapped `FileSink` open-failure count.
|
||||
- `QueuedFile` runtime variants forward the metric from the wrapped inner `FileSink`.
|
||||
- Non-file runtime variants return `0`.
|
||||
- The counter is cumulative until `file_reset_failure_counters()` clears it.
|
||||
|
||||
### How to Use
|
||||
|
||||
Here are some specific examples provided.
|
||||
|
||||
#### When Need File Availability Diagnostics
|
||||
|
||||
When direct runtime support output should show whether file open or reopen failed:
|
||||
```moonbit
|
||||
let count = sink.file_open_failures()
|
||||
```
|
||||
|
||||
In this example, the runtime sink exposes the open-failure metric directly.
|
||||
|
||||
#### When Validate Recovery Logic
|
||||
|
||||
When recovery code should inspect whether reopen attempts failed:
|
||||
```moonbit
|
||||
ignore(sink.file_open_failures())
|
||||
```
|
||||
|
||||
In this example, the counter helps confirm whether file-open problems occurred during runtime.
|
||||
|
||||
### Error Case
|
||||
|
||||
e.g.:
|
||||
- If the runtime sink is not file-backed, the method returns `0`.
|
||||
|
||||
- If callers need the full file status snapshot rather than one counter, `file_state()` is the better API.
|
||||
|
||||
### Notes
|
||||
|
||||
1. Use this helper for focused direct runtime file-open diagnostics.
|
||||
|
||||
2. Pair it with `file_reopen(...)` and `file_available()` during recovery analysis.
|
||||
@@ -0,0 +1,75 @@
|
||||
---
|
||||
name: runtime-sink-file-reset-failure-counters
|
||||
group: api
|
||||
category: runtime
|
||||
update-time: 20260613
|
||||
description: Reset the file failure counters recorded by a file-backed RuntimeSink.
|
||||
key-word:
|
||||
- runtime
|
||||
- sink
|
||||
- file
|
||||
- public
|
||||
---
|
||||
|
||||
## Runtime-sink-file-reset-failure-counters
|
||||
|
||||
Reset the file failure counters recorded by a file-backed `RuntimeSink`. This helper clears open, write, flush, and rotation failure metrics together.
|
||||
|
||||
### Interface
|
||||
|
||||
```moonbit
|
||||
pub fn RuntimeSink::file_reset_failure_counters(self : RuntimeSink) -> Bool {
|
||||
```
|
||||
|
||||
#### input
|
||||
|
||||
- `self : RuntimeSink` - Runtime sink whose file failure counters should be cleared.
|
||||
|
||||
#### output
|
||||
|
||||
- `Bool` - Whether the reset was applied.
|
||||
|
||||
### Explanation
|
||||
|
||||
Detailed rules explaining key parameters and behaviors
|
||||
|
||||
- Plain `File` runtime variants clear all file failure counters together and return `true`.
|
||||
- `QueuedFile` runtime variants forward the reset behavior to the wrapped inner `FileSink` and return `true`.
|
||||
- Non-file runtime variants return `false`.
|
||||
- This helper is useful after diagnostics, recovery, or controlled tests.
|
||||
|
||||
### 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
|
||||
ignore(sink.file_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
|
||||
ignore(sink.file_reset_failure_counters())
|
||||
ignore(sink.file_open_failures())
|
||||
```
|
||||
|
||||
In this example, the runtime sink starts a new diagnostics window after reset.
|
||||
|
||||
### Error Case
|
||||
|
||||
e.g.:
|
||||
- If the runtime sink is not file-backed, the method returns `false`.
|
||||
|
||||
- If callers need the current values before clearing them, they should read the counters or `file_state()` first.
|
||||
|
||||
### Notes
|
||||
|
||||
1. Use this helper after diagnostics or recovery, not before capturing needed evidence.
|
||||
|
||||
2. It is the reset companion for the direct runtime file failure-counter helpers.
|
||||
@@ -0,0 +1,74 @@
|
||||
---
|
||||
name: runtime-sink-file-rotation-failures
|
||||
group: api
|
||||
category: runtime
|
||||
update-time: 20260613
|
||||
description: Read the number of rotation failures recorded by a file-backed RuntimeSink.
|
||||
key-word:
|
||||
- runtime
|
||||
- sink
|
||||
- file
|
||||
- public
|
||||
---
|
||||
|
||||
## Runtime-sink-file-rotation-failures
|
||||
|
||||
Read the number of rotation failures recorded by a file-backed `RuntimeSink`. This helper is useful when direct runtime rotation behavior should be observed operationally.
|
||||
|
||||
### Interface
|
||||
|
||||
```moonbit
|
||||
pub fn RuntimeSink::file_rotation_failures(self : RuntimeSink) -> Int {
|
||||
```
|
||||
|
||||
#### input
|
||||
|
||||
- `self : RuntimeSink` - Runtime sink whose rotation-failure counter should be inspected.
|
||||
|
||||
#### output
|
||||
|
||||
- `Int` - Number of recorded rotation failures.
|
||||
|
||||
### Explanation
|
||||
|
||||
Detailed rules explaining key parameters and behaviors
|
||||
|
||||
- Plain `File` runtime variants report the wrapped `FileSink` rotation-failure count.
|
||||
- `QueuedFile` runtime variants forward the metric from the wrapped inner `FileSink`.
|
||||
- Non-file runtime variants return `0`.
|
||||
- The counter is cumulative until `file_reset_failure_counters()` clears it.
|
||||
|
||||
### How to Use
|
||||
|
||||
Here are some specific examples provided.
|
||||
|
||||
#### When Need Rotation-specific Diagnostics
|
||||
|
||||
When support output should reveal whether rotation is failing:
|
||||
```moonbit
|
||||
let count = sink.file_rotation_failures()
|
||||
```
|
||||
|
||||
In this example, the runtime sink exposes a focused metric for direct rotation-path health.
|
||||
|
||||
#### When Validate Runtime Rotation Tuning
|
||||
|
||||
When changed rotation settings should be checked in operation:
|
||||
```moonbit
|
||||
ignore(sink.file_rotation_failures())
|
||||
```
|
||||
|
||||
In this example, callers can observe whether runtime rotation changes introduced problems.
|
||||
|
||||
### Error Case
|
||||
|
||||
e.g.:
|
||||
- If the runtime sink is not file-backed, the method returns `0`.
|
||||
|
||||
- If callers need both rotation config and failure metrics, they should combine this helper with `file_rotation_config()` or `file_state()`.
|
||||
|
||||
### Notes
|
||||
|
||||
1. Use this helper when diagnosing direct runtime file rotation reliability.
|
||||
|
||||
2. It is especially relevant when runtime rotation policy can change after startup.
|
||||
@@ -0,0 +1,74 @@
|
||||
---
|
||||
name: runtime-sink-file-write-failures
|
||||
group: api
|
||||
category: runtime
|
||||
update-time: 20260613
|
||||
description: Read the number of write failures recorded by a file-backed RuntimeSink.
|
||||
key-word:
|
||||
- runtime
|
||||
- sink
|
||||
- file
|
||||
- public
|
||||
---
|
||||
|
||||
## Runtime-sink-file-write-failures
|
||||
|
||||
Read the number of write failures recorded by a file-backed `RuntimeSink`. This helper is useful for direct runtime diagnostics around the file write path.
|
||||
|
||||
### Interface
|
||||
|
||||
```moonbit
|
||||
pub fn RuntimeSink::file_write_failures(self : RuntimeSink) -> Int {
|
||||
```
|
||||
|
||||
#### input
|
||||
|
||||
- `self : RuntimeSink` - Runtime sink whose write-failure counter should be inspected.
|
||||
|
||||
#### output
|
||||
|
||||
- `Int` - Number of recorded write failures.
|
||||
|
||||
### Explanation
|
||||
|
||||
Detailed rules explaining key parameters and behaviors
|
||||
|
||||
- Plain `File` runtime variants report the wrapped `FileSink` write-failure count.
|
||||
- `QueuedFile` runtime variants forward the metric from the wrapped inner `FileSink`.
|
||||
- Non-file runtime variants return `0`.
|
||||
- The counter is cumulative until `file_reset_failure_counters()` clears it.
|
||||
|
||||
### How to Use
|
||||
|
||||
Here are some specific examples provided.
|
||||
|
||||
#### When Need Runtime Write-path Diagnostics
|
||||
|
||||
When support output should show whether file writes have been failing:
|
||||
```moonbit
|
||||
let count = sink.file_write_failures()
|
||||
```
|
||||
|
||||
In this example, callers get a focused signal for direct runtime file write-path health.
|
||||
|
||||
#### When Compare Sink Health After Recovery
|
||||
|
||||
When recovery logic should verify whether new failures still occur:
|
||||
```moonbit
|
||||
ignore(sink.file_write_failures())
|
||||
```
|
||||
|
||||
In this example, the metric helps measure whether runtime writes improved after intervention.
|
||||
|
||||
### Error Case
|
||||
|
||||
e.g.:
|
||||
- If the runtime sink is not file-backed, the method returns `0`.
|
||||
|
||||
- If callers need a fuller view of file health, `file_state()` or `file_runtime_state()` may be better APIs.
|
||||
|
||||
### Notes
|
||||
|
||||
1. Use this helper for focused direct runtime write-failure visibility.
|
||||
|
||||
2. Pair it with `file_flush_failures()` when diagnosing output-path instability.
|
||||
Reference in New Issue
Block a user