Documentation
¶
Overview ¶
Package apiclient is the OpenObserve API surface used by the CLI. It builds org-scoped requests, decodes normalized models, and converts non-2xx responses into structured *errors.CLIError values.
This package backs the openobserve-cli command layer and is also importable as a standalone client library (e.g. by a GUI); see the repository README. Its exported surface — the Client interface, the normalized models, and the read-only / dry-run semantics — is a contract the CLI and its companion Skill depend on. Extend it additively and keep existing shapes and behavior stable; do not reshape the public API to suit a single local call site.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func NormalizeBaseURL ¶
NormalizeBaseURL trims a trailing slash and supplies a scheme when the user gave a bare host:port (the common self-hosted case).
Types ¶
type BuildParams ¶
type BuildParams struct {
BaseURL string
Org string
// AuthDecorator authenticates every request. Required.
AuthDecorator transport.Decorator
Timeout time.Duration
MaxRetries int
}
BuildParams configures Build.
type Client ¶
type Client interface {
BaseURL() string
// DefaultOrg returns the organization identifier the client was built with.
DefaultOrg() string
// Ping verifies connectivity and credentials by listing organizations.
Ping(ctx context.Context) ([]Org, error)
// ListOrgs returns the organizations the credential can see.
ListOrgs(ctx context.Context) ([]Org, error)
// ListStreams returns the streams in org. streamType ("logs"/"metrics"/
// "traces") narrows the result; "" returns all types. fetchSchema includes
// each stream's field schema.
ListStreams(ctx context.Context, org, streamType string, fetchSchema bool) ([]Stream, error)
// GetStream returns a single stream by name, including its schema.
GetStream(ctx context.Context, org, name, streamType string) (*Stream, error)
// Search runs a SQL query against org and returns matching hits.
Search(ctx context.Context, org string, req SearchRequest) (*SearchResponse, error)
// QueryMetricsInstant runs an instant PromQL query at a point in time.
QueryMetricsInstant(ctx context.Context, org, promql string, timeSec float64) (*PromQLResponse, error)
// QueryMetricsRange runs a PromQL query over a [start,end] window at step
// resolution. start/end are Unix seconds; step is a Prometheus duration.
QueryMetricsRange(ctx context.Context, org, promql string, startSec, endSec float64, step string) (*PromQLResponse, error)
// LatestTraces returns recent traces in a trace stream, newest first.
LatestTraces(ctx context.Context, org, stream string, startMicros, endMicros int64, from, size int, filter string) (*TraceSearchResponse, error)
}
Client is the OpenObserve API surface used by the CLI.
func Build ¶
func Build(p BuildParams) (Client, error)
Build assembles a ready-to-use Client: it normalizes the base URL and constructs the retrying HTTP transport carrying the auth decorator.
type Org ¶
Org is one OpenObserve organization. Identifier is the value used in the /api/{org}/… path; Name is the human label.
The org object OpenObserve returns varies across versions and editions — fields appear, disappear, and even change JSON type (e.g. `plan` is a string in some builds and a number in others). To stay robust we decode the whole object into a raw map (which can never fail on a type mismatch) and pull the two fields we rely on out of it. Output is a lean, curated projection so an agent isn't flooded with thresholds and user objects it doesn't need.
func (Org) MarshalJSON ¶
MarshalJSON emits the curated subset of the raw object (falling back to the extracted fields when the org was constructed without a raw map).
func (*Org) UnmarshalJSON ¶
UnmarshalJSON decodes an org leniently: everything lands in a map, and the fields used for path scoping and display are extracted from it.
type PromQLResponse ¶
type PromQLResponse struct {
Status string `json:"status"`
Data json.RawMessage `json:"data,omitempty"`
ErrorType string `json:"errorType,omitempty"`
Error string `json:"error,omitempty"`
}
PromQLResponse is the Prometheus-compatible reply from OpenObserve's PromQL endpoints (/api/{org}/prometheus/api/v1/query{,_range}). The envelope is stable but `data` is kept raw: its shape depends on the result type (matrix / vector / scalar / string), so decoding it eagerly would couple the client to a shape it doesn't need to understand. On a query error the API usually replies with a non-2xx status (handled by the client's httpError); the Status/Error fields cover the rarer 200-with-error case.
type SchemaField ¶
SchemaField is one column of a stream's schema.
type SearchQuery ¶
type SearchQuery struct {
SQL string `json:"sql"`
StartTime int64 `json:"start_time"`
EndTime int64 `json:"end_time"`
From int `json:"from"`
Size int `json:"size"`
}
SearchQuery is the inner query block of a search request. Times are Unix microseconds, as OpenObserve requires.
type SearchRequest ¶
type SearchRequest struct {
Query SearchQuery `json:"query"`
SearchType string `json:"search_type,omitempty"`
}
SearchRequest is the body POSTed to /api/{org}/_search.
type SearchResponse ¶
type SearchResponse struct {
Took int `json:"took"`
From int `json:"from"`
Size int `json:"size"`
ScanSize float64 `json:"scan_size"`
Total int64 `json:"total"`
Hits []map[string]any `json:"hits"`
}
SearchResponse is the search API's reply.
type Stream ¶
type Stream struct {
Name string `json:"name"`
StorageType string `json:"storage_type,omitempty"`
StreamType string `json:"stream_type"`
Stats *StreamStats `json:"stats,omitempty"`
Schema []SchemaField `json:"schema,omitempty"`
Settings *StreamSettings `json:"settings,omitempty"`
}
Stream is a logs / metrics / traces stream within an organization.
type StreamSettings ¶
type StreamSettings struct {
PartitionKeys any `json:"partition_keys,omitempty"`
FullTextSearchKeys []string `json:"full_text_search_keys,omitempty"`
BloomFilterFields []string `json:"bloom_filter_fields,omitempty"`
}
StreamSettings holds the query-relevant configuration of a stream.
type StreamStats ¶
type StreamStats struct {
DocTimeMin int64 `json:"doc_time_min,omitempty"`
DocTimeMax int64 `json:"doc_time_max,omitempty"`
DocNum int64 `json:"doc_num,omitempty"`
FileNum int64 `json:"file_num,omitempty"`
StorageSize float64 `json:"storage_size,omitempty"`
CompressedSize float64 `json:"compressed_size,omitempty"`
}
StreamStats summarizes a stream's stored data.
type TraceSearchResponse ¶
type TraceSearchResponse struct {
Total int64 `json:"total"`
Hits []TraceSummary `json:"hits"`
}
TraceSearchResponse is the reply from the latest-traces endpoint.
type TraceSummary ¶
type TraceSummary struct {
TraceID string `json:"trace_id"`
Duration json.RawMessage `json:"duration,omitempty"`
StartTime int64 `json:"start_time,omitempty"`
EndTime int64 `json:"end_time,omitempty"`
FirstEvent map[string]any `json:"first_event,omitempty"`
ServiceName []map[string]any `json:"service_name,omitempty"`
Spans json.RawMessage `json:"spans,omitempty"`
}
TraceSummary is one trace returned by GET /api/{org}/{stream}/traces/latest. Fields are kept loose (raw maps / slices) because the trace payload carries OpenTelemetry-derived attributes that vary by instrumentation.
Source Files