trace

Documentation

Overview

Package trace decodes httplog NDJSON trace logs and normalizes them into paired, grouped exchanges that output exporters consume.

Index

• type Body
• type Event
  • func Decode(ctx context.Context, inputs []ResolvedInput, stdin io.Reader, strict bool) ([]Event, []string, error)
• type Exchange
  • func BuildExchanges(events []Event) ([]Exchange, []string)
• type FilenameMetadata
• type InputType
• type RawEvent
• type RequestData
• type ResolvedInput
  • func ResolveSources(args []string) ([]ResolvedInput, error)
• type ResponseData
• type SourceInfo

Types

type Body

type Body struct {
	Present     bool
	Data        []byte
	MimeType    string
	Truncated   bool
	SourceBytes *int64
	// Decompressed names the content encoding that was removed from
	// the logged bytes ("gzip" or "deflate"), or is empty when Data
	// holds the bytes exactly as logged.
	Decompressed string
}

Body is a logged request or response payload after normalization. Data holds the bytes to present, decompressed when a plain decoding was recognized.

type Event

type Event struct {
	GlobalIndex int
	Timestamp   time.Time
	Raw         RawEvent
	Source      SourceInfo
	RunKey      string
}

Event is one decoded request or response record with provenance.

func Decode

func Decode(ctx context.Context, inputs []ResolvedInput, stdin io.Reader, strict bool) ([]Event, []string, error)

Decode reads every resolved input and returns the request/response events found, with per-line warnings for undecodable content. In strict mode the first malformed line is a fatal error.

type Exchange

type Exchange struct {
	TransactionID string
	RunKey        string

	// SourceTraceID and SourceSpanID are OTel IDs recorded by newer
	// producers. They mark one poll cycle (level 3, request sequence)
	// and are provenance only: output trace/span IDs are always
	// synthesized so the grouping model is not fragmented per cycle.
	SourceTraceID string
	SourceSpanID  string

	Request  *RequestData
	Response *ResponseData

	FirstIndex int
	// FilenameMeta identifies the input policy (level 1); its
	// InputInstanceID drives per-policy output partitioning.
	FilenameMeta FilenameMetadata

	// Notes are pairing anomalies such as duplicate sides.
	Notes []string
}

Exchange is one recovered HTTP request/response pair, the canonical format-neutral model that all exporters consume. Either side may be missing when the source logs are incomplete.

func BuildExchanges

func BuildExchanges(events []Event) ([]Exchange, []string)

BuildExchanges pairs request and response events by transaction ID and returns exchanges in chronological order, plus pairing warnings.

type FilenameMetadata

type FilenameMetadata struct {
	FullName           string
	InputInstanceID    string
	Integration        string
	DataStream         string
	InstanceUUIDSuffix string
}

FilenameMetadata is provenance derived from a CEL trace filename. It identifies the input policy (level 1 of the grouping model) but never affects pairing or run grouping.

type InputType

type InputType string

const (
	InputTypeFile  InputType = "file"
	InputTypeDir   InputType = "directory"
	InputTypeStdin InputType = "stdin"
)

type RawEvent

type RawEvent struct {
	Timestamp             string              `json:"@timestamp"`
	Message               string              `json:"message"`
	TransactionID         string              `json:"transaction.id"`
	TraceID               string              `json:"trace.id"`
	SpanID                string              `json:"span.id"`
	URLOriginal           string              `json:"url.original"`
	URLScheme             string              `json:"url.scheme"`
	URLPath               string              `json:"url.path"`
	URLDomain             string              `json:"url.domain"`
	URLPort               string              `json:"url.port"`
	URLQuery              string              `json:"url.query"`
	RequestMethod         string              `json:"http.request.method"`
	RequestHeader         map[string][]string `json:"http.request.header"`
	UserAgent             string              `json:"user_agent.original"`
	RequestBodyContent    string              `json:"http.request.body.content"`
	RequestBodyTruncated  bool                `json:"http.request.body.truncated"`
	RequestBodyBytes      *int64              `json:"http.request.body.bytes"`
	RequestMimeType       string              `json:"http.request.mime_type"`
	ResponseStatusCode    *int                `json:"http.response.status_code"`
	ResponseHeader        map[string][]string `json:"http.response.header"`
	ResponseBodyContent   string              `json:"http.response.body.content"`
	ResponseBodyTruncated bool                `json:"http.response.body.truncated"`
	ResponseBodyBytes     *int64              `json:"http.response.body.bytes"`
	ResponseMimeType      string              `json:"http.response.mime_type"`
	ErrorMessage          string              `json:"error.message"`
}

RawEvent is one NDJSON line as logged by httplog.LoggingRoundTripper.

type RequestData

type RequestData struct {
	Timestamp    time.Time
	Method       string
	URL          string
	Scheme       string
	Path         string
	Domain       string
	Port         string
	Query        string
	Headers      map[string][]string
	UserAgent    string
	Body         Body
	ErrorMessage string
	Source       SourceInfo
}

type ResolvedInput

type ResolvedInput struct {
	Type         InputType
	ConcretePath string
	DisplayName  string
}

func ResolveSources

func ResolveSources(args []string) ([]ResolvedInput, error)

ResolveSources expands source arguments (directories, files, and "-" for stdin) into concrete inputs. Directories contribute their top-level *.ndjson files in sorted order.

type ResponseData

type ResponseData struct {
	Timestamp    time.Time
	StatusCode   *int
	Headers      map[string][]string
	Body         Body
	ErrorMessage string
	Source       SourceInfo
}

type SourceInfo

type SourceInfo struct {
	Line      int
	InputName string
	Filename  FilenameMetadata
}