mirror of
https://github.com/mailscope/kumomta.git
synced 2026-08-21 20:08:18 +00:00
Wez Furlong
82 lines
2.1 KiB
Markdown
82 lines
2.1 KiB
Markdown
---
|
|
tags:
|
|
- utility
|
|
- logging
|
|
- jsonl
|
|
---
|
|
|
|
# LogBatch
|
|
|
|
{{since('2026.04.09-ea3b2a9b')}}
|
|
|
|
A `LogBatch` is an object yielded by the `:batches()` method of
|
|
[`kumo.jsonl.new_tailer`](new_tailer.md) and
|
|
[`kumo.jsonl.new_multi_tailer`](new_multi_tailer.md).
|
|
It is not constructed directly.
|
|
|
|
Each batch contains a set of parsed JSON records read from one or more log
|
|
segments, along with metadata about which segment files they came from.
|
|
|
|
After processing a batch, call `:commit()` to advance the checkpoint so that
|
|
the records will not be re-read on the next run. If `:commit()` is not called
|
|
the checkpoint remains at its prior position and the batch will be re-read on
|
|
restart.
|
|
|
|
## Methods
|
|
|
|
### batch:records
|
|
|
|
```lua
|
|
local recs = batch:records()
|
|
for i, record in ipairs(recs) do
|
|
print(record.type)
|
|
end
|
|
```
|
|
|
|
Returns a lua table (sequence) containing all parsed JSON records in the batch.
|
|
Returns an empty table if the batch has already been committed.
|
|
|
|
### batch:iter_records
|
|
|
|
```lua
|
|
for record in batch:iter_records() do
|
|
print(record.type)
|
|
end
|
|
```
|
|
|
|
Returns an iterator that yields one parsed JSON record at a time, converting
|
|
each record lazily on demand. Returns an iterator that immediately yields
|
|
`nil` if the batch has already been committed.
|
|
|
|
Prefer this over `:records()` when processing large batches to avoid
|
|
materialising the entire batch into a table at once.
|
|
|
|
### batch:consumer_name
|
|
|
|
```lua
|
|
local name = batch:consumer_name()
|
|
```
|
|
|
|
Returns the name of the consumer this batch belongs to. This is the `name`
|
|
field from the consumer configuration passed to
|
|
[`kumo.jsonl.new_multi_tailer`](new_multi_tailer.md).
|
|
|
|
For batches returned by the single-consumer
|
|
[`kumo.jsonl.new_tailer`](new_tailer.md), this returns `"default"`.
|
|
|
|
Returns an empty string if the batch has already been committed.
|
|
|
|
### batch:commit
|
|
|
|
```lua
|
|
batch:commit()
|
|
```
|
|
|
|
Advances the checkpoint to the end of this batch, confirming that the caller
|
|
has successfully processed all records in it.
|
|
|
|
If the tailer was not configured with a `checkpoint_name` this is a no-op.
|
|
|
|
Calling `:commit()` a second time on the same batch raises an error:
|
|
`"batch has already been committed"`.
|