Documentation
¶
Overview ¶
Package otlpstream implements the binary framing Dagger Cloud's OTLP read streams speak — a byte-for-byte mirror of the server's api/otlpstream package (dagger.io#5226, "feat(cloud): stream telemetry over binary OTLP"), kept here because the server repository is not importable.
A stream is a sequence of frames. Each frame is a 16-byte header — 4 bytes of magic naming the frame kind, an 8-byte big-endian cursor, a 4-byte big-endian payload length — followed by the payload:
- a DATA frame carries one binary-protobuf OTLP export request; a data frame with an EMPTY payload is a heartbeat, keeping intermediaries from closing a quiet connection;
- a TERMINAL frame ends the stream: every selected row has been emitted;
- an ERROR frame carries a UTF-8 message and ends the stream in failure.
Cursors increase monotonically, and a connection that ends without a terminal or error frame was TRUNCATED — which is what lets a consumer tell "the trace is fully transferred" from "the edge dropped the connection", a distinction the SSE protocol this replaced could not make.
Index ¶
Constants ¶
const ( // ContentType is the media type of a framed stream; it doubles as the // Accept value a consumer negotiates with. ContentType = "application/vnd.dagger.otlp.stream" // CursorHeader is the resume header the server recognizes (and, today, // refuses for any cursor but 0). CursorHeader = "X-Dagger-Telemetry-Cursor" FrameHeaderLen = 16 MaxPayloadSize = 64 << 20 )
Variables ¶
var ( DataMagic = [4]byte{'D', 'T', 'P', 1} TerminalMagic = [4]byte{'D', 'T', 'E', 1} ErrorMagic = [4]byte{'D', 'T', 'X', 1} )
Functions ¶
func WriteFrame ¶
WriteFrame writes one frame with an explicit cursor. The CLI only ever consumes these streams; the writing half exists for the test fakes that stand in for Cloud (and for tests that need to misbehave, e.g. repeat a cursor).
Types ¶
type FrameWriter ¶
type FrameWriter struct {
// contains filtered or unexported fields
}
FrameWriter emits frames the way the server's live writer does: cursors assigned sequentially from 1, heartbeats as empty data frames.
func NewFrameWriter ¶
func NewFrameWriter(w io.Writer) *FrameWriter
func (*FrameWriter) WriteData ¶
func (fw *FrameWriter) WriteData(payload []byte) error
func (*FrameWriter) WriteError ¶
func (fw *FrameWriter) WriteError(msg string) error
func (*FrameWriter) WriteHeartbeat ¶
func (fw *FrameWriter) WriteHeartbeat() error
func (*FrameWriter) WriteTerminal ¶
func (fw *FrameWriter) WriteTerminal() error
Source Files