Documentation
¶
Index ¶
- Constants
- func DefaultTimeRange(start, end time.Time) (time.Time, time.Time)
- func FormatLabelPairs(labels []LabelPair) string
- func FormatLabelsMap(labels map[string]string) string
- func FormatLabelsTable(w io.Writer, labels []string) error
- func FormatPprofWriteTable(w io.Writer, result *PprofWriteResult) error
- func FormatProfileExemplarsTable(w io.Writer, result *ProfileExemplarsResult, maxLabelCols int) error
- func FormatProfileTypesTable(w io.Writer, resp *ProfileTypesResponse) error
- func FormatQueryTable(w io.Writer, resp *QueryResponse) error
- func FormatSeriesTable(w io.Writer, resp *SelectSeriesResponse) error
- func FormatSeriesTableWide(w io.Writer, resp *SelectSeriesResponse) error
- func FormatSpanExemplarsTable(w io.Writer, result *SpanExemplarsResult, maxLabelCols int) error
- func FormatTopSeriesTable(w io.Writer, resp *TopSeriesResponse) error
- func TopCardinalityLabelNames(labelMaps []map[string]string, n int) []string
- type Annotation
- type Client
- func (c *Client) LabelNames(ctx context.Context, datasourceUID string, req LabelNamesRequest) (*LabelNamesResponse, error)
- func (c *Client) LabelValues(ctx context.Context, datasourceUID string, req LabelValuesRequest) (*LabelValuesResponse, error)
- func (c *Client) Pprof(ctx context.Context, datasourceUID string, req PprofRequest) ([]byte, error)
- func (c *Client) ProfileTypes(ctx context.Context, datasourceUID string, req ProfileTypesRequest) (*ProfileTypesResponse, error)
- func (c *Client) Query(ctx context.Context, datasourceUID string, req QueryRequest) (*QueryResponse, error)
- func (c *Client) SelectHeatmap(ctx context.Context, datasourceUID string, req SelectHeatmapRequest) (*SelectHeatmapResponse, error)
- func (c *Client) SelectSeries(ctx context.Context, datasourceUID string, req SelectSeriesRequest) (*SelectSeriesResponse, error)
- type Exemplar
- type Flamegraph
- type FunctionSample
- type HeatmapSeries
- type HeatmapSlot
- type LabelNamesRequest
- type LabelNamesResponse
- type LabelPair
- type LabelValuesRequest
- type LabelValuesResponse
- type Level
- type Location
- type PprofRequest
- type PprofWriteResult
- type ProfileExemplar
- type ProfileExemplarsResult
- type ProfileType
- type ProfileTypesRequest
- type ProfileTypesResponse
- type QueryRequest
- type QueryResponse
- type SelectHeatmapRequest
- type SelectHeatmapResponse
- type SelectSeriesRequest
- type SelectSeriesResponse
- type SpanExemplar
- type SpanExemplarsResult
- type StackTraceSelector
- type TimePoint
- type TimeSeries
- type TopSeriesEntry
- type TopSeriesResponse
Constants ¶
const ( ExemplarTypeIndividual = "EXEMPLAR_TYPE_INDIVIDUAL" ExemplarTypeSpan = "EXEMPLAR_TYPE_SPAN" )
ExemplarType constants mirror the pyroscope types.v1.ExemplarType enum.
const (
HeatmapQueryTypeSpan = "HEATMAP_QUERY_TYPE_SPAN"
)
HeatmapQueryType constants mirror the pyroscope querier.v1.HeatmapQueryType enum.
Variables ¶
This section is empty.
Functions ¶
func DefaultTimeRange ¶ added in v0.2.0
DefaultTimeRange returns the provided time range, or defaults to the last hour if not set.
func FormatLabelPairs ¶ added in v0.2.0
FormatLabelPairs formats label pairs as {key=val, key=val, ...}.
func FormatLabelsMap ¶ added in v0.2.0
FormatLabelsMap formats a map of labels as {key=val, key=val, ...}.
func FormatLabelsTable ¶
FormatLabelsTable formats label names or values as a table.
func FormatPprofWriteTable ¶ added in v0.2.15
func FormatPprofWriteTable(w io.Writer, result *PprofWriteResult) error
FormatPprofWriteTable formats the result of writing a pprof binary as a single-row table.
func FormatProfileExemplarsTable ¶ added in v0.2.12
func FormatProfileExemplarsTable(w io.Writer, result *ProfileExemplarsResult, maxLabelCols int) error
FormatProfileExemplarsTable renders a ProfileExemplarsResult as a table. maxLabelCols auto-selects the N highest-cardinality label columns to show (0 hides label columns entirely).
func FormatProfileTypesTable ¶
func FormatProfileTypesTable(w io.Writer, resp *ProfileTypesResponse) error
FormatProfileTypesTable formats profile types as a table.
func FormatQueryTable ¶
func FormatQueryTable(w io.Writer, resp *QueryResponse) error
FormatQueryTable formats a Pyroscope query response as a table showing top functions.
func FormatSeriesTable ¶ added in v0.2.0
func FormatSeriesTable(w io.Writer, resp *SelectSeriesResponse) error
FormatSeriesTable formats a SelectSeries response as a table with one row per data point.
func FormatSeriesTableWide ¶ added in v0.2.0
func FormatSeriesTableWide(w io.Writer, resp *SelectSeriesResponse) error
FormatSeriesTableWide formats a SelectSeries response with label pairs exploded into columns.
func FormatSpanExemplarsTable ¶ added in v0.2.12
func FormatSpanExemplarsTable(w io.Writer, result *SpanExemplarsResult, maxLabelCols int) error
FormatSpanExemplarsTable renders a SpanExemplarsResult as a table.
func FormatTopSeriesTable ¶ added in v0.2.0
func FormatTopSeriesTable(w io.Writer, resp *TopSeriesResponse) error
FormatTopSeriesTable formats a TopSeriesResponse as a ranked leaderboard table.
func TopCardinalityLabelNames ¶ added in v0.2.12
TopCardinalityLabelNames returns up to n label names with the highest cardinality across the provided label maps, excluding internal __..__ labels. Ties break alphabetically for stable output.
Types ¶
type Annotation ¶ added in v0.2.0
Annotation represents metadata attached to a time-series point.
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client is a client for executing Pyroscope queries via Grafana's datasource API.
func NewClient ¶
func NewClient(cfg config.NamespacedRESTConfig) (*Client, error)
NewClient creates a new Pyroscope query client.
func (*Client) LabelNames ¶
func (c *Client) LabelNames(ctx context.Context, datasourceUID string, req LabelNamesRequest) (*LabelNamesResponse, error)
LabelNames returns label names from the datasource.
func (*Client) LabelValues ¶
func (c *Client) LabelValues(ctx context.Context, datasourceUID string, req LabelValuesRequest) (*LabelValuesResponse, error)
LabelValues returns values for a specific label.
func (*Client) Pprof ¶ added in v0.2.15
Pprof fetches a merged profile via SelectMergeProfile and returns it as a gzip-compressed pprof binary, compatible with go tool pprof.
func (*Client) ProfileTypes ¶
func (c *Client) ProfileTypes(ctx context.Context, datasourceUID string, req ProfileTypesRequest) (*ProfileTypesResponse, error)
ProfileTypes returns available profile types from the datasource.
func (*Client) Query ¶
func (c *Client) Query(ctx context.Context, datasourceUID string, req QueryRequest) (*QueryResponse, error)
Query executes a Pyroscope profile query against the specified datasource.
func (*Client) SelectHeatmap ¶ added in v0.2.12
func (c *Client) SelectHeatmap(ctx context.Context, datasourceUID string, req SelectHeatmapRequest) (*SelectHeatmapResponse, error)
SelectHeatmap executes a SelectHeatmap query, used for span exemplars.
func (*Client) SelectSeries ¶ added in v0.2.0
func (c *Client) SelectSeries(ctx context.Context, datasourceUID string, req SelectSeriesRequest) (*SelectSeriesResponse, error)
SelectSeries executes a SelectSeries query to get profile time-series data.
type Exemplar ¶ added in v0.2.12
type Exemplar struct {
Timestamp json.Number `json:"timestamp"` // ms since epoch, encoded as string
ProfileID string `json:"profileId,omitempty"`
SpanID string `json:"spanId,omitempty"`
Value json.Number `json:"value"`
Labels []LabelPair `json:"labels,omitempty"`
}
Exemplar is a single profile sample (optionally span-linked) attached to a TimePoint (SelectSeries) or HeatmapSlot (SelectHeatmap).
func (Exemplar) Int64Value ¶ added in v0.2.12
Int64Value returns the exemplar value as int64.
func (Exemplar) TimestampMs ¶ added in v0.2.12
TimestampMs returns the exemplar timestamp as milliseconds since epoch.
type Flamegraph ¶
type Flamegraph struct {
Names []string `json:"names"`
Levels []Level `json:"levels"`
Total int64 `json:"total,string"`
MaxSelf int64 `json:"maxSelf,string"`
}
Flamegraph represents a flame graph structure.
type FunctionSample ¶
FunctionSample represents a function in the flame graph with computed stats.
func ExtractTopFunctions ¶
func ExtractTopFunctions(fg *Flamegraph, limit int) []FunctionSample
ExtractTopFunctions extracts the top N functions by self time from a flame graph.
type HeatmapSeries ¶ added in v0.2.12
type HeatmapSeries struct {
Labels []LabelPair `json:"labels"`
Slots []HeatmapSlot `json:"slots"`
}
HeatmapSeries groups heatmap slots under a set of labels.
type HeatmapSlot ¶ added in v0.2.12
type HeatmapSlot struct {
Timestamp json.Number `json:"timestamp"` // right edge of time bucket, ms since epoch
Exemplars []Exemplar `json:"exemplars,omitempty"`
}
HeatmapSlot is a time×value bucket carrying sampled exemplars.
type LabelNamesRequest ¶
LabelNamesRequest represents a request to list label names.
type LabelNamesResponse ¶
type LabelNamesResponse struct {
Names []string `json:"names"`
}
LabelNamesResponse represents the response from a label names query.
type LabelValuesRequest ¶
LabelValuesRequest represents a request to list label values.
type LabelValuesResponse ¶
type LabelValuesResponse struct {
Names []string `json:"names"` // Pyroscope uses "names" for both labels and values
}
LabelValuesResponse represents the response from a label values query.
type Level ¶
type Level struct {
Values []string `json:"values"` // API returns strings that need to be parsed
}
Level represents a single level in the flame graph.
type Location ¶ added in v0.2.15
type Location struct {
Name string `json:"name"`
}
Location mirrors querier.v1.Location.
type PprofRequest ¶ added in v0.2.15
type PprofRequest struct {
ProfileTypeID string
LabelSelector string
Start time.Time
End time.Time
MaxNodes int64
}
PprofRequest represents a request to fetch a profile in pprof binary format.
type PprofWriteResult ¶ added in v0.2.15
type PprofWriteResult struct {
Path string `json:"path"`
}
PprofWriteResult is the structured output emitted after writing a pprof binary to disk.
type ProfileExemplar ¶ added in v0.2.12
type ProfileExemplar struct {
ProfileID string `json:"profileId"`
Timestamp time.Time `json:"timestamp"`
Value int64 `json:"value"`
SpanID string `json:"spanId,omitempty"`
Labels map[string]string `json:"labels,omitempty"`
}
ProfileExemplar is a single flattened profile-exemplar entry.
type ProfileExemplarsResult ¶ added in v0.2.12
type ProfileExemplarsResult struct {
From time.Time `json:"from"`
To time.Time `json:"to"`
ProfileType string `json:"profileType"`
Exemplars []ProfileExemplar `json:"exemplars"`
}
ProfileExemplarsResult is the processed result of a profile-exemplars query (SelectSeries + EXEMPLAR_TYPE_INDIVIDUAL), flattened and sorted by value desc.
func BuildProfileExemplarsResult ¶ added in v0.2.12
func BuildProfileExemplarsResult(resp *SelectSeriesResponse, from, to time.Time, profileType string, topN int) *ProfileExemplarsResult
BuildProfileExemplarsResult flattens SelectSeriesResponse exemplars into a sorted, truncated ProfileExemplarsResult. Entries are sorted by value descending and truncated to topN (topN<=0 disables truncation).
type ProfileType ¶
type ProfileType struct {
ID string `json:"ID"`
Name string `json:"name"`
SampleType string `json:"sampleType"`
SampleUnit string `json:"sampleUnit"`
PeriodType string `json:"periodType"`
PeriodUnit string `json:"periodUnit"`
}
ProfileType represents a profile type in Pyroscope.
type ProfileTypesRequest ¶
ProfileTypesRequest represents a request to list profile types.
type ProfileTypesResponse ¶
type ProfileTypesResponse struct {
ProfileTypes []ProfileType `json:"profileTypes"`
}
ProfileTypesResponse represents the response from a profile types query.
type QueryRequest ¶
type QueryRequest struct {
LabelSelector string
ProfileTypeID string
Start time.Time
End time.Time
MaxNodes int64
ProfileIDs []string
StackTraceSelector *StackTraceSelector
}
QueryRequest represents a Pyroscope profile query request. Field names mirror querier.v1.SelectMergeStacktracesRequest.
func (QueryRequest) IsRange ¶
func (r QueryRequest) IsRange() bool
IsRange returns true if this is a range query with explicit time bounds.
type QueryResponse ¶
type QueryResponse struct {
Flamegraph *Flamegraph `json:"flamegraph,omitempty"`
}
QueryResponse represents the response from a Pyroscope profile query.
type SelectHeatmapRequest ¶ added in v0.2.12
type SelectHeatmapRequest struct {
ProfileTypeID string
LabelSelector string
Start time.Time
End time.Time
Step float64
QueryType string // e.g. "HEATMAP_QUERY_TYPE_SPAN"
ExemplarType string // e.g. "EXEMPLAR_TYPE_SPAN"
Limit int64 // optional; max number of exemplars per slot
}
SelectHeatmapRequest represents a request to query a heatmap of profile data. Used for span exemplars via QueryType=HEATMAP_QUERY_TYPE_SPAN + ExemplarType=EXEMPLAR_TYPE_SPAN.
type SelectHeatmapResponse ¶ added in v0.2.12
type SelectHeatmapResponse struct {
Series []HeatmapSeries `json:"series"`
}
SelectHeatmapResponse represents the response from a SelectHeatmap query.
type SelectSeriesRequest ¶ added in v0.2.0
type SelectSeriesRequest struct {
ProfileTypeID string
LabelSelector string
Start time.Time
End time.Time
GroupBy []string
Step float64 // resolution step in seconds
Aggregation string // "SUM" or "AVERAGE"
Limit int64 // top-N series by total value
ExemplarType string // "EXEMPLAR_TYPE_INDIVIDUAL" or "EXEMPLAR_TYPE_SPAN"; empty = no exemplars
}
SelectSeriesRequest represents a request to query profile time-series data.
type SelectSeriesResponse ¶ added in v0.2.0
type SelectSeriesResponse struct {
Series []TimeSeries `json:"series"`
}
SelectSeriesResponse represents the response from a SelectSeries query.
type SpanExemplar ¶ added in v0.2.12
type SpanExemplar struct {
SpanID string `json:"spanId"`
Timestamp time.Time `json:"timestamp"`
Value int64 `json:"value"`
Labels map[string]string `json:"labels,omitempty"`
}
SpanExemplar is a single flattened span-exemplar entry.
type SpanExemplarsResult ¶ added in v0.2.12
type SpanExemplarsResult struct {
From time.Time `json:"from"`
To time.Time `json:"to"`
ProfileType string `json:"profileType"`
Exemplars []SpanExemplar `json:"exemplars"`
}
SpanExemplarsResult is the processed result of a span-exemplars query (SelectHeatmap + HEATMAP_QUERY_TYPE_SPAN + EXEMPLAR_TYPE_SPAN).
func BuildSpanExemplarsResult ¶ added in v0.2.12
func BuildSpanExemplarsResult(resp *SelectHeatmapResponse, from, to time.Time, profileType string, topN int) *SpanExemplarsResult
BuildSpanExemplarsResult flattens SelectHeatmapResponse exemplars. Entries without a SpanID are skipped (mirrors profilecli: span exemplars without a span ID aren't actionable).
type StackTraceSelector ¶ added in v0.2.15
type StackTraceSelector struct {
CallSite []Location `json:"callSite,omitempty"`
}
StackTraceSelector mirrors querier.v1.StackTraceSelector. Only the CallSite variant is supported on the SelectMergeStacktraces RPC; GoPGO selection lives on the SelectMergeProfile (pprof export) path.
type TimePoint ¶ added in v0.2.0
type TimePoint struct {
Value json.Number `json:"value"`
Timestamp json.Number `json:"timestamp"` // milliseconds since epoch, encoded as string
Annotations []Annotation `json:"annotations,omitempty"`
Exemplars []Exemplar `json:"exemplars,omitempty"`
}
TimePoint represents a single data point in a time series. Pyroscope's connect-rpc JSON encoding sends timestamp as a string and value as an integer.
func (TimePoint) FloatValue ¶ added in v0.2.0
FloatValue returns the point value as float64.
func (TimePoint) TimestampMs ¶ added in v0.2.0
TimestampMs returns the timestamp as milliseconds since epoch.
type TimeSeries ¶ added in v0.2.0
TimeSeries represents a single time series with labels and data points.
type TopSeriesEntry ¶ added in v0.2.0
type TopSeriesEntry struct {
Rank int `json:"rank"`
Labels map[string]string `json:"labels"`
Total float64 `json:"total"`
}
TopSeriesEntry represents a single ranked entry in a top-series response.
type TopSeriesResponse ¶ added in v0.2.0
type TopSeriesResponse struct {
ProfileType string `json:"profileType"`
GroupBy []string `json:"groupBy"`
Series []TopSeriesEntry `json:"series"`
}
TopSeriesResponse represents an aggregated, ranked view of series data.
func AggregateTopSeries ¶ added in v0.2.0
func AggregateTopSeries(resp *SelectSeriesResponse, profileType string, groupBy []string, limit int) *TopSeriesResponse
AggregateTopSeries converts a SelectSeriesResponse into a ranked TopSeriesResponse by summing all points per series and sorting by total descending.