Documentation
¶
Overview ¶
Package o11y is your logs, metrics and traces: ship them in, query them, chart them.
It is the ONE owner of the cloud binary's observability plane — registered as a SINGLE `o11y` subsystem (this file's init) that internally mounts, in the load-bearing order, every part of the concept:
READ/SERVE plane (specific /v1/o11y/* routes, registered BEFORE the
hanzoai/o11y wildcard so Fiber's in-order match gives them precedence):
- tenant-scoped reads /v1/o11y/{logs,metrics,status} (scope.go)
- SuperAdmin VM proxy /v1/o11y/vm/{query,query_range} (vmproxy.go)
- flat builder query /v1/o11y/{query,query_range} (query.go)
- event ingest POST /v1/event/ingestion (event_ingest.go)
- Sentry-wire ingest POST /v1/event/{project}/envelope|store (via cloud.ObsErrorIngest)
RUNTIME handler the hanzoai/o11y wildcard (order 70) delegates to via
o11y.SetHandler — the in-process runtime (embed.go) or a reverse-proxy
fallback (this file).
WRITE plane (order-independent):
- ZAP span+log receivers + opt-in in-process trace sink, all writing
the event plane (planesink.go)
Decomplection (one and one way): these were five separately-registered subsystems (o11yscope 69, o11y-runtime 71, o11y-event-ingest 68, o11y-otlp-ingest 72, o11y-trace-inproc 73) whose names leaked FIVE public concepts into the registry (five config toggles, five /v1/<name>/health routes). The k8s-style ordering was an internal impl detail. They now collapse to ONE registration of the name `o11y` (order 69): mountO11y performs the ordered sub-mounts in-process, so the PUBLIC concept is a single `o11y`. Behavior is preserved EXACTLY — every route registers at the same point relative to the order-70 wildcard as before (all inside the one order-69 mount, so all before 70).
Co-ownership: the upstream github.com/hanzoai/o11y module ALSO registers the name `o11y` (order 70, the wildcard route surface) from its own init. The two entries are co-owners of ONE public concept; this order-69 entry opts out of the generic HIP-0106 health route (cloud.HealthOwner) so /v1/o11y/health is registered EXACTLY once, by the module's order-70 co-entry.
One way, two backings (mountRuntime):
- PRIMARY: the in-process runtime (buildEmbeddedHandler), enabled by O11Y_TELEMETRYSTORE_DATASTORE_DSN. Serves telemetry from cloud itself.
- FALLBACK: a reverse proxy to a still-running o11y Deployment, used only when the embed is disabled (no DSN) or fails to init. Fail-soft, zero downtime.
Path is preserved verbatim: /v1/o11y/* reaches the o11y runtime unchanged, which rewrites /v1/o11y/* -> /api/* internally (see o11y app.createPublicServer). The gateway terminates auth and propagates identity as X-* headers; the runtime (embedded) or the proxy (fallback) sees the same request.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func MountO11y ¶
mountO11y is the ONE mount for the whole observability concept. It performs the ordered sub-mounts in-process so the public registry carries a single `o11y` name. Every cloud-native /v1/o11y/* route is registered here — inside this one order-69 mount, hence BEFORE the hanzoai/o11y wildcard (order 70) — so Fiber's in-order match gives the specific routes precedence over the runtime proxy.
func ShutdownO11y ¶
shutdownO11y tears down the write-plane resources that hold process-lifetime connections, in REVERSE mount order — plane ingest (trace sink + receivers), event-ingest Datastore — so buffered spans/logs/rows flush before exit. Best-effort: the first error is returned but every teardown still runs. Idempotent and nil-safe.
Types ¶
type StatusComponent ¶ added in v1.801.350
type StatusComponent struct {
ID string `json:"id"`
Name string `json:"name"`
// CurrentStatus is this component's own condition: "full_outage" for a
// service that did not answer its health probe at all.
CurrentStatus string `json:"current_status"`
}
StatusComponent is one piece of the platform an incident affects. Name is the service the fleet prober knows it by.
type StatusIncident ¶ added in v1.801.350
type StatusIncident struct {
ID string `json:"id"`
Name string `json:"name"`
Status string `json:"status"`
URL string `json:"url"`
// LastUpdateAt is when the failing measurement this incident reports was
// read, RFC3339 UTC.
LastUpdateAt string `json:"last_update_at"`
LastUpdateMessage string `json:"last_update_message"`
// CurrentWorstImpact is the incident's impact on the PLATFORM, which is not
// the same question as the component's own condition above.
CurrentWorstImpact string `json:"current_worst_impact"`
AffectedComponents []StatusComponent `json:"affected_components"`
}
StatusIncident is one ongoing incident. Every field is measured: an incident exists because a probe failed, and LastUpdateAt is when that measurement was taken.
type StatusMaintenance ¶ added in v1.801.350
type StatusMaintenance struct {
ID string `json:"id"`
Name string `json:"name"`
Status string `json:"status"`
URL string `json:"url"`
LastUpdateAt string `json:"last_update_at"`
LastUpdateMessage string `json:"last_update_message"`
AffectedComponents []StatusComponent `json:"affected_components"`
StartsAt string `json:"starts_at,omitempty"`
EndsAt string `json:"ends_at,omitempty"`
}
StatusMaintenance is one planned maintenance window. Hanzo has no maintenance scheduling plane, so both maintenance lists below are always empty — which is a true statement ("nothing is scheduled"), not a placeholder. The type is part of the published contract because a client reading the document has to know those fields are arrays of objects.
type StatusSummary ¶ added in v1.801.350
type StatusSummary struct {
PageTitle string `json:"page_title"`
// PageURL is the HUMAN status page — an HTML page for people, distinct from
// this JSON endpoint. Every link in this document points there.
PageURL string `json:"page_url"`
OngoingIncidents []StatusIncident `json:"ongoing_incidents"`
InProgressMaintenances []StatusMaintenance `json:"in_progress_maintenances"`
ScheduledMaintenances []StatusMaintenance `json:"scheduled_maintenances"`
// CheckedAt is when the underlying availability read was taken, RFC3339 UTC.
// Not part of the status-page schema the panel parses (which ignores unknown
// fields); it is here because a status document with no timestamp cannot be
// told apart from a stale one.
CheckedAt string `json:"checked_at"`
}
StatusSummary is the public platform status document.
Source Files