profile

package
v0.9.1 Latest Latest
Warning

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

Go to latest
Published: Sep 9, 2025 License: MIT Imports: 25 Imported by: 0

Documentation

Overview

Package profile contains types responsible for the scraping, uploading & merging of pprof profiles from Go applications.

Index

Constants

View Source
const (
	EventTypeUploaded = "profile.uploaded"
	EventTypeMerged   = "profile.merged"
	EventTypeDeleted  = "profile.deleted"
)

Constants for event types.

Variables

This section is empty.

Functions

func IsApplication added in v0.5.0

func IsApplication(app string) blob.Filter

IsApplication returns a blob.Filter that returns true for any object keys that have the provided application name as a prefix.

func IsMergedProfile added in v0.5.0

func IsMergedProfile() blob.Filter

IsMergedProfile returns a blob.Filter that returns true for any object keys that match those of a merged profile.

func IsValidAppName

func IsValidAppName(app string) bool

IsValidAppName returns false if the application name contains any characters that are not a-z, 0-9 or hyphens.

Types

type BlobRepository

type BlobRepository interface {
	// NewWriter should return an io.WriterCloser implementation that will store data written to it under the
	// provided key.
	NewWriter(ctx context.Context, key string) (io.WriteCloser, error)
	// NewReader should return an io.ReadCloser implementation that will read data from blob storage at the
	// provided key. It should return blob.ErrNotExist if no data exists at the given key.
	NewReader(ctx context.Context, key string) (io.ReadCloser, error)
	// Delete should remove data stored under the given key from the blob store. It should return blob.ErrNotExist
	// if no object exists at the given key.
	Delete(ctx context.Context, key string) error
	// List should return all objects within the repository that match the provided filter.
	List(ctx context.Context, filter blob.Filter) iter.Seq2[blob.Object, error]
	// Exists should return true if an object exists at the given path.
	Exists(ctx context.Context, path string) (bool, error)
}

The BlobRepository interface describes types that can interact with blob storage provides such as S3, GCS etc.

type Client

type Client interface {
	// Upload should write the profile data stored within the io.Reader implementation to the profile server for
	// a specified application.
	Upload(ctx context.Context, app string, r io.Reader) error
	// Download should write the contents of a pprof profile from the profile server to the io.Writer implementation
	// for the specified application.
	Download(ctx context.Context, app string, w io.Writer) error
	// ProfileAndUpload should obtain a profile from the given src URL for the specified duration and upload it
	// to the server for the specified application.
	ProfileAndUpload(ctx context.Context, app, src string, duration time.Duration) error
}

The Client interface describes types that can interact with the profile server and targets for profiling.

type DeleteResponse

type DeleteResponse struct{}

The DeleteResponse type is the response given when a profile has been deleted.

type DeletedEvent added in v0.7.0

type DeletedEvent struct {
	// The application profile that has been deleted.
	App string `json:"app"`
}

The DeletedEvent type is an event.Payload implementation describing a profile that has been deleted.

func (DeletedEvent) Key added in v0.7.0

func (e DeletedEvent) Key() string

Key returns the application name.

func (DeletedEvent) Type added in v0.7.0

func (e DeletedEvent) Type() string

Type returns EventTypeDeleted.

type EventWriter

type EventWriter interface {
	// Write should push the given event payload onto the event bus.
	Write(ctx context.Context, evt event.Payload) error
}

The EventWriter interface describes types that can publish events onto an event bus such as Kafka, NATS, SQS etc.

type HTTPController

type HTTPController struct {
	// contains filtered or unexported fields
}

The HTTPController type is used to handle inbound requests to upload and download application profiles.

func NewHTTPController

func NewHTTPController(blobs BlobRepository, events EventWriter) *HTTPController

NewHTTPController returns a new instance of the HTTPController type that will read and write profiles via the given BlobRepository implementation and publish events via the EventWriter implementation.

func (*HTTPController) Delete

func (h *HTTPController) Delete(w http.ResponseWriter, r *http.Request)

Delete handles an inbound HTTP request to delete the profile for an application. It will also delete any profiles awaiting merge for the application.

func (*HTTPController) Download

func (h *HTTPController) Download(w http.ResponseWriter, r *http.Request)

Download handles an inbound HTTP request to download a pprof profile for the application specified within the URL path.

func (*HTTPController) List

List handles an inbound HTTP request to list all profiles stored by the server.

func (*HTTPController) Register

func (h *HTTPController) Register(m *http.ServeMux)

Register HTTP endpoints onto the http.ServeMux.

func (*HTTPController) Upload

func (h *HTTPController) Upload(w http.ResponseWriter, r *http.Request)

Upload handles an inbound HTTP request containing a pprof profile for a given application. The profile is parsed uploaded to blob storage and an event is published.

type ListResponse

type ListResponse struct {
	Profiles []Profile `json:"profiles"`
}

The ListResponse type is the response given when listing profiles.

type MergedEvent

type MergedEvent struct {
	// The application the profile relates to.
	App string `json:"app"`
	// The location of the uploaded profile within blob storage.
	ProfileKey string `json:"profileKey"`
	// The location of the base profile that has been merged.
	MergedKey string `json:"mergedKey"`
}

The MergedEvent type is an event.Payload implementation describing a profile that has been successfully merged into the base profile.

func (MergedEvent) Key

func (e MergedEvent) Key() string

Key returns the application name.

func (MergedEvent) Type

func (e MergedEvent) Type() string

Type returns EventTypeMerged.

type Profile

type Profile struct {
	// The location in blob storage of the profile.
	Key string `json:"key"`
	// The profile size in bytes.
	Size int64 `json:"size"`
	// When the profile was last modified.
	LastModified time.Time `json:"lastModified"`
}

The Profile type describes a single profile stored by the server.

type PruneConfig added in v0.6.0

type PruneConfig struct {
	// The application whose profiles should be pruned.
	App string `json:"app"`
	// The pruning rules to apply.
	Rules []PruneRule `json:"rules"`
}

The PruneConfig type represents a collection of pruning rules for a specific application.

func LoadPruneConfig added in v0.6.0

func LoadPruneConfig(ctx context.Context, location string) ([]PruneConfig, error)

LoadPruneConfig attempts to parse the file at the specified location and decode it into an array of profile pruning rules that are applied when the worker merges profiles. The file is expected to be in JSON encoding.

type PruneRule added in v0.6.0

type PruneRule struct {
	// Drop determines the node under which child nodes will be pruned.
	Drop *regexp.Regexp `json:"drop"`
	// Keep determines nodes under Drop that should be kept.
	Keep *regexp.Regexp `json:"keep"`
}

The PruneRule type represents a single pruning action to perform on a profile.

type ScrapeConfig

type ScrapeConfig struct {
	// How many profiles to obtain after the ProfileDuration has passed.
	SampleSize uint
	// How long targets should be profiled for, in seconds.
	ProfileDuration time.Duration
	// How frequently profiles are sampled, in seconds.
	ScrapeFrequency time.Duration
	// The application this scraper instance is collecting profiles for.
	App string
}

The ScrapeConfig type describes the configuration used by the Scraper to sample pprof profiles from specified targets.

type Scraper

type Scraper struct {
	// contains filtered or unexported fields
}

The Scraper type is used to perform periodic sampling of pprof profiles given a selection of valid targets. These profiles are then forwarded to the configured profile server.

func NewScraper

func NewScraper(client Client, config ScrapeConfig) *Scraper

NewScraper returns a new instance of the Scraper type using the provided configuration.

func (*Scraper) Scrape

func (s *Scraper) Scrape(ctx context.Context, source TargetSource) error

Scrape configured targets. This method blocks until the provided context is cancelled.

type TargetSource added in v0.7.0

type TargetSource interface {
	// List should return all targets that are available to be scraped.
	List(ctx context.Context) ([]target.Target, error)
}

The TargetSource interface describes types that can list scraping targets.

type UploadResponse

type UploadResponse struct {
	// The location in blob storage the profile is stored at.
	Key string `json:"key"`
}

The UploadResponse type is the response given when a profile has been uploaded.

type UploadedEvent

type UploadedEvent struct {
	// The application the profile relates to.
	App string `json:"app"`
	// The location of the profile within blob storage.
	ProfileKey string `json:"profileKey"`
}

The UploadedEvent type is an event.Payload implementation describing a single profile that has been uploaded.

func (UploadedEvent) Key

func (e UploadedEvent) Key() string

Key returns the application name.

func (UploadedEvent) Type

func (e UploadedEvent) Type() string

Type returns EventTypeUploaded.

type Worker

type Worker struct {
	// contains filtered or unexported fields
}

The Worker type is used to handle profile events and merge uploaded profiles together into a single base profile.

func NewWorker

func NewWorker(blobs BlobRepository, writer EventWriter, prune []PruneConfig) *Worker

NewWorker returns a new instance of the Worker type that will read and write profile data via the BlobRepository implementation, read events via the EventReader implementation and publish events via the EventWriter implementation.

func (*Worker) HandleEvent

func (w *Worker) HandleEvent(ctx context.Context, evt event.Envelope) error

HandleEvent is an event.Handler implementation that is used to handle inbound profile events and perform profile merge and deletion.

Directories

Path Synopsis

Jump to

Keyboard shortcuts

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