hashicorp / hashicorp/nomad

Client Stream Logs endpoint makes it hard to track the offset

Open
#11,655 0 comments 1 reaction 0 assignees View on GitHub
theme/allocation API type/enhancement
Dominant language
Go
Stars
17k
Forks
2.1k
Avg merge
1d 9h
Merged PRs (30d)
105

Description

[Stream Logs](https://www.nomadproject.io/api-docs/client#stream-logs) endpoint returns a stream created from task's log files. The offset specifies where to start the streaming from. A log shipper uses this parameter to remember the last offset it was reading from to ensure all log lines are sent. When a log shipper is restarted it should resume from the last known position.

Unfortunately, this endpoint makes it hard to resume log shipping from a client's perspective because the offset is not guaranteed to be stable over the lifetime of an allocation. For example, it changes when a log file is deleted (due to log rotation). Things are fine if you stay connected but the moment you need to reconnect (log shipper redeployed or VM rebooted) you have no guarantees that some external event did not cause a change in the streams position. In other words, if you send a request twice you might get a different outcome (kind of unexpected for a GET method).

I understand this is by design and I think I can recalculate the offset based on the file system state using [List Files](https://www.nomadproject.io/api-docs/client#list-files) endpoint. Stream Logs endpoint also offers file events, but they are only emitted for the log file that is *currently being streamed* which is not documented. My first thought was that events are emitted for all files. Also, I know how to handle `file deleted` event, but I do not know how does `file truncated` event impact the offset and the documentation does not go into details here as well. Even if I recalculate the offset there is still a small amount of time between recalculating the offset and opening a logs stream, where a log file could have been rotated which changes the streams position. You end up with the wrong data being streamed. Load balancers can easily generate log files with gigabytes of data.

### Proposal

Allocations are stateful already, so an offset that remains stable over the lifetime of an allocation could be introduced. This would greatly simplify the client code as offset recalculation would no longer be required and no change in the streams position could occur when opening a logs stream.

### Use-cases

Log shipping, especially with semantic logging where you use, for example, JSON-style rendering for any embedded structured data.

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.