pyroscope

package
v0.2.16 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: May 21, 2026 License: Apache-2.0 Imports: 18 Imported by: 0

Documentation

Index

Constants

View Source
const (
	ExemplarTypeIndividual = "EXEMPLAR_TYPE_INDIVIDUAL"
	ExemplarTypeSpan       = "EXEMPLAR_TYPE_SPAN"
)

ExemplarType constants mirror the pyroscope types.v1.ExemplarType enum.

View Source
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

func DefaultTimeRange(start, end time.Time) (time.Time, time.Time)

DefaultTimeRange returns the provided time range, or defaults to the last hour if not set.

func FormatLabelPairs added in v0.2.0

func FormatLabelPairs(labels []LabelPair) string

FormatLabelPairs formats label pairs as {key=val, key=val, ...}.

func FormatLabelsMap added in v0.2.0

func FormatLabelsMap(labels map[string]string) string

FormatLabelsMap formats a map of labels as {key=val, key=val, ...}.

func FormatLabelsTable

func FormatLabelsTable(w io.Writer, labels []string) error

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

func TopCardinalityLabelNames(labelMaps []map[string]string, n int) []string

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

type Annotation struct {
	Key   string `json:"key"`
	Value string `json:"value"`
}

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

func (c *Client) Pprof(ctx context.Context, datasourceUID string, req PprofRequest) ([]byte, error)

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

func (e Exemplar) Int64Value() int64

Int64Value returns the exemplar value as int64.

func (Exemplar) TimestampMs added in v0.2.12

func (e Exemplar) TimestampMs() int64

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

type FunctionSample struct {
	Name       string
	Self       int64
	Total      int64
	Percentage float64
}

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

type LabelNamesRequest struct {
	Matchers []string
	Start    time.Time
	End      time.Time
}

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 LabelPair added in v0.2.0

type LabelPair struct {
	Name  string `json:"name"`
	Value string `json:"value"`
}

LabelPair represents a key-value label pair.

type LabelValuesRequest

type LabelValuesRequest struct {
	Name     string
	Matchers []string
	Start    time.Time
	End      time.Time
}

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

type ProfileTypesRequest struct {
	Start time.Time
	End   time.Time
}

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

func (p TimePoint) FloatValue() float64

FloatValue returns the point value as float64.

func (TimePoint) TimestampMs added in v0.2.0

func (p TimePoint) TimestampMs() int64

TimestampMs returns the timestamp as milliseconds since epoch.

type TimeSeries added in v0.2.0

type TimeSeries struct {
	Labels []LabelPair `json:"labels"`
	Points []TimePoint `json:"points"`
}

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL