jsonreport

Documentation

Overview

Package jsonreport marshals probe results into documents that validate against schema/pingtrace.schema.json. This package is the contract boundary between the Go CLI and the npm library: both implementations must produce documents that validate against the same schema.

Package jsonreport's Writer accumulates probe / MTR results from a running CLI invocation and writes one or more JSON documents that validate against schema/pingtrace.schema.json.

Filenames follow the same `{mode}[_TAG]_UTC<stamp>.json` convention used by csvexport, so a `--export` + `--json` run produces sibling files that are easy to correlate.

Index

• Constants
• func NormalizeSource(s string) string
• type ExportedFile
• type MtrHop
  • func FromMTRResult(r probe.MTRResult) []MtrHop
• type MtrReport
  • func NewMtrReport(version, target string, cyclesPlanned *int, intervalMs int64, command string, ...) MtrReport
• type ProbeReport
  • func NewProbeReport(version string, targets []Target, results []Result, exported []ExportedFile, ...) ProbeReport
• type Result
  • func FromPingResult(target, source string, durationMs int64, p probe.PingResult) Result
  • func FromTraceResult(target, source string, durationMs int64, t probe.TraceResult) Result
• type Row
• type Target
• type Writer
  • func New(dir, version string) (*Writer, error)
  • func (w *Writer) AddTarget(t Target)
  • func (w *Writer) AppendMTR(target string, cyclesPlanned *int, intervalMs int64, command string, ...)
  • func (w *Writer) AppendPing(target, source string, durationMs int64, r probe.PingResult)
  • func (w *Writer) AppendTrace(target, source string, durationMs int64, r probe.TraceResult)
  • func (w *Writer) Close(exported []ExportedFile) ([]string, error)
  • func (w *Writer) SetTag(tag string)

Constants

const SchemaURL = "https://raw.githubusercontent.com/skhell/pingtrace/v1.0.0/schema/pingtrace.schema.json"

SchemaURL points at the published schema in the repo at the matching version tag. Update when bumping the schema.

Functions

func NormalizeSource

func NormalizeSource(s string) string

NormalizeSource maps internal target sources to the schema enum ("argument" | "csv" | "cidr"). The internal value "file" is the CLI's name for what the schema labels "csv".

Types

type ExportedFile

type ExportedFile struct {
	Operation string `json:"operation"`
	Path      string `json:"path"`
	RowCount  int    `json:"rowCount"`
}

ExportedFile mirrors the schema ExportedFile object (one entry per CSV file produced alongside the JSON document).

type MtrHop

type MtrHop struct {
	Hop         int      `json:"hop"`
	IP          *string  `json:"ip"`
	IPs         []string `json:"ips,omitempty"`
	Host        string   `json:"host,omitempty"`
	Sent        int      `json:"sent"`
	Lost        int      `json:"lost"`
	LossPercent float64  `json:"lossPercent"`
	Last        *float64 `json:"last"`
	Best        *float64 `json:"best"`
	Worst       *float64 `json:"worst"`
	Avg         *float64 `json:"avg"`
	StDev       *float64 `json:"stdev"`
	PublicDNS   string   `json:"publicDns,omitempty"`
	PrivateDNS  string   `json:"privateDns,omitempty"`
	Org         string   `json:"org,omitempty"`
	ASN         string   `json:"asn,omitempty"`
	Location    string   `json:"location,omitempty"`
	NetType     string   `json:"netType,omitempty"`
	Policy      string   `json:"policy,omitempty"`
}

MtrHop mirrors the schema MtrHop object.

func FromMTRResult

func FromMTRResult(r probe.MTRResult) []MtrHop

FromMTRResult converts a probe.MTRResult snapshot into schema MtrHops.

type MtrReport

type MtrReport struct {
	Schema           string   `json:"$schema"`
	PingtraceVersion string   `json:"pingtraceVersion"`
	GeneratedAt      string   `json:"generatedAt"`
	Mode             string   `json:"mode"`
	Target           string   `json:"target"`
	CyclesPlanned    *int     `json:"cyclesPlanned"`
	CyclesCompleted  int      `json:"cyclesCompleted"`
	IntervalMs       int64    `json:"intervalMs"`
	Command          string   `json:"command,omitempty"`
	Hops             []MtrHop `json:"hops"`
}

MtrReport is the top-level "mtr" document.

func NewMtrReport

func NewMtrReport(version, target string, cyclesPlanned *int, intervalMs int64, command string, hops []MtrHop, completed int, generatedAt time.Time) MtrReport

NewMtrReport builds an MtrReport.

type ProbeReport

type ProbeReport struct {
	Schema           string         `json:"$schema"`
	PingtraceVersion string         `json:"pingtraceVersion"`
	GeneratedAt      string         `json:"generatedAt"`
	Mode             string         `json:"mode"`
	Targets          []Target       `json:"targets"`
	Results          []Result       `json:"results"`
	ExportedFiles    []ExportedFile `json:"exportedFiles,omitempty"`
}

ProbeReport is the top-level "probe" document.

func NewProbeReport

func NewProbeReport(version string, targets []Target, results []Result, exported []ExportedFile, generatedAt time.Time) ProbeReport

NewProbeReport builds a ProbeReport with the canonical top-level fields populated. Callers supply the per-target results.

type Result

type Result struct {
	Target     string `json:"target"`
	Source     string `json:"source"`
	Operation  string `json:"operation"`
	Status     string `json:"status"`
	Summary    string `json:"summary"`
	Command    string `json:"command"`
	DurationMs int64  `json:"durationMs"`
	Rows       []Row  `json:"rows"`
}

Result is the per-target outcome in a ProbeReport.

func FromPingResult

func FromPingResult(target, source string, durationMs int64, p probe.PingResult) Result

FromPingResult converts a probe.PingResult into a schema Result. `source` is the target's provenance ("argument" | "file" | "cidr"); it is mapped to the schema enum automatically.

func FromTraceResult

func FromTraceResult(target, source string, durationMs int64, t probe.TraceResult) Result

FromTraceResult converts a probe.TraceResult into a schema Result.

type Row

type Row struct {
	// ping fields
	Seq    *int     `json:"seq,omitempty"`
	Bytes  *int     `json:"bytes,omitempty"`
	TTL    *int     `json:"ttl,omitempty"`
	TimeMs *float64 `json:"timeMs,omitempty"`

	// trace fields
	Hop      *int     `json:"hop,omitempty"`
	Host     string   `json:"host,omitempty"`
	Probe1Ms *float64 `json:"probe1Ms,omitempty"`
	Probe2Ms *float64 `json:"probe2Ms,omitempty"`
	Probe3Ms *float64 `json:"probe3Ms,omitempty"`

	// shared
	IP         string `json:"ip,omitempty"`
	PublicDNS  string `json:"publicDns,omitempty"`
	PrivateDNS string `json:"privateDns,omitempty"`
	Org        string `json:"org,omitempty"`
	ASN        string `json:"asn,omitempty"`
	Location   string `json:"location,omitempty"`
	NetType    string `json:"netType,omitempty"`
	Policy     string `json:"policy,omitempty"`
	Status     string `json:"status"`
}

Row is the row element common to ping and trace results. Fields not applicable to a given operation are omitted via `omitempty` and nullable pointer types.

type Target

type Target struct {
	Value         string `json:"value"`
	Source        string `json:"source"`
	OriginalInput string `json:"originalInput,omitempty"`
}

Target mirrors the JSON Schema Target object.

type Writer

type Writer struct {
	// contains filtered or unexported fields
}

Writer is the JSON sibling of csvexport.Writer. All public methods are safe for concurrent use.

func New

func New(dir, version string) (*Writer, error)

New creates the export directory (if missing) and stamps every filename written through this Writer with the same UTC timestamp.

func (*Writer) AddTarget

func (w *Writer) AddTarget(t Target)

AddTarget records a target in the probe-mode document. Idempotent per value.

func (*Writer) AppendMTR

func (w *Writer) AppendMTR(target string, cyclesPlanned *int, intervalMs int64, command string, snap probe.MTRResult)

AppendMTR records an MtrReport for one MTR target. Callers pass the final snapshot, the planned cycle count (nil for "until Ctrl+C"), and the interval in milliseconds.

func (*Writer) AppendPing

func (w *Writer) AppendPing(target, source string, durationMs int64, r probe.PingResult)

AppendPing accumulates one ping Result into the probe document.

func (*Writer) AppendTrace

func (w *Writer) AppendTrace(target, source string, durationMs int64, r probe.TraceResult)

AppendTrace accumulates one trace Result into the probe document.

func (*Writer) Close

func (w *Writer) Close(exported []ExportedFile) ([]string, error)

Close flushes the accumulated state to disk. `exported` lists the sibling CSV files (if any) for the probe document's `exportedFiles` section. Returns the JSON file paths written.

func (*Writer) SetTag

func (w *Writer) SetTag(tag string)

SetTag adds a sanitized infix between the mode name and the UTC timestamp in produced filenames (e.g. a CIDR scope).