coverage

Documentation

Overview

Package coverage computes "what fraction of an API surface has any instrumentation?" — see issue #18. The actual math is pure; the HTTP-facing wrapper lives in internal/api.

Index

• type ManifestRoute
• type Manifests
  • func LoadManifest(path string) (*Manifests, error)
• type Overall
• type Report
  • func Compute(spans []*storage.Span, m *Manifests) Report
• type Route
• type ServiceCoverage

Types

type ManifestRoute

type ManifestRoute struct {
	Method string
	Path   string
}

ManifestRoute is one declared route from an imported spec.

type Manifests

type Manifests struct {
	// per-service routes, plus the spec filename it came from for UI display.
	Spec   string
	Routes map[string][]ManifestRoute
}

Manifests maps service name → declared routes from a spec.

func LoadManifest

func LoadManifest(path string) (*Manifests, error)

LoadManifest parses an OpenAPI 3.x spec file (JSON or YAML) and returns every (method, path) it declares. The service the spec belongs to is taken from the spec's `info.title` if present, otherwise from the bare filename.

We don't try to enforce strict OpenAPI compliance — just walk paths and pull out the HTTP-method keys. Anything we don't recognize is ignored.

type Overall

type Overall struct {
	ObservedOps int     `json:"observed_operations"`
	TotalRoutes int     `json:"total_routes"`
	DarkCount   int     `json:"dark_count"`
	CoveragePct float64 `json:"coverage_pct"`
}

Overall is the rolled-up across-all-services summary.

type Report

type Report struct {
	Services []ServiceCoverage `json:"services"`
	Overall  Overall           `json:"overall"`
}

Report is the top-level response for GET /api/coverage.

func Compute

func Compute(spans []*storage.Span, m *Manifests) Report

Compute walks the given spans, extracts observed (service, method, path) triples, joins them against any declared manifests, and returns the report. It is pure — no DB, no HTTP, easy to test.

type Route

type Route struct {
	Method string `json:"method"`
	Path   string `json:"path"`
	Hits   int    `json:"hits"`
	P95Ns  int64  `json:"p95_ns,omitempty"`
}

Route is one entry on a service's operation list. Method is uppercase HTTP verb ("GET", "POST", ...) or "RPC" for non-HTTP operations.

type ServiceCoverage

type ServiceCoverage struct {
	Name           string  `json:"name"`
	Source         string  `json:"source"`         // "openapi" | "observed"
	Spec           string  `json:"spec,omitempty"` // filename when source=openapi
	ObservedOps    int     `json:"observed_operations"`
	TotalRoutes    int     `json:"total_routes"`
	CoveragePct    float64 `json:"coverage_pct"`
	DarkRoutes     []Route `json:"dark_routes"`
	ObservedRoutes []Route `json:"observed_routes"`
}

ServiceCoverage is the per-service section of the report.