pxapi

README

Pixie Go API

px.dev/pxapi is a API for interacting with Pixie, a no-instrumentation Kubernetes observability platform.

go get px.dev/pxapi

• API Quick Start Documentation
• API Reference Docs

Resources

• Website
• Documentation
• Community Slack
• Youtube

Contributing

Do not open pull requests or file issues directly against this repository, they will be ignored.

Instead, please open pull requests and file issues against our primary repo pixie-io/pixie.

Please follow the same contributing guide you would follow for any other pull request made to pixie-io/pixie.

This repository is published from pixie-io/pixie using google/copybara.

About Us

Pixie was started by a San Francisco based startup, Pixie Labs Inc. Our north star is to build a new generation of intelligent products which empower developers to engineer the future. We were acquired by New Relic in 2020.

New Relic, Inc. open sourced Pixie in April 2021.

License

The Pixie Go API is licensed under Apache License, Version 2.0.

Documentation

Overview

Package pxapi provides the Go client interface for Pixie. WARNING: The API defined in this package is not stable and can change without notice. The same goes for the package path: (github.com/pixie-io/pixie/api/go)

Index

• type Client
  • func NewClient(ctx context.Context, opts ...ClientOption) (*Client, error)
  • func (c *Client) CreateAPIKey(ctx context.Context, desc string) (*cloudpb.APIKey, error)
  • func (c *Client) CreateDeployKey(ctx context.Context, desc string) (*cloudpb.DeploymentKey, error)
  • func (c *Client) DeleteAPIKey(ctx context.Context, id string) error
  • func (c *Client) GetLatestOperatorVersion(ctx context.Context) (string, error)
  • func (c *Client) GetLatestVizierVersion(ctx context.Context) (string, error)
  • func (c *Client) GetVizierInfo(ctx context.Context, clusterID string) (*VizierInfo, error)
  • func (c *Client) ListViziers(ctx context.Context) ([]*VizierInfo, error)
  • func (c *Client) NewVizierClient(ctx context.Context, vizierID string) (*VizierClient, error)
• type ClientOption
  • func WithAPIKey(auth string) ClientOption
  • func WithBearerAuth(auth string) ClientOption
  • func WithCloudAddr(cloudAddr string) ClientOption
  • func WithDirectAddr(directAddr string) ClientOption
  • func WithDirectCredsInsecure() ClientOption
  • func WithDisableTLSVerification(cloudAddr string) ClientOption
  • func WithE2EEncryption(enabled bool) ClientOption
• type ResultsStats
• type ScriptResults
  • func (s *ScriptResults) Close() error
  • func (s *ScriptResults) Stats() *ResultsStats
  • func (s *ScriptResults) Stream() error
• type TableMuxer
• type TableRecordHandler
• type VizierClient
  • func (v *VizierClient) ExecuteScript(ctx context.Context, pxl string, mux TableMuxer) (*ScriptResults, error)
  • func (v *VizierClient) GenerateOTelScript(ctx context.Context, pxl string) (string, error)
• type VizierInfo
• type VizierStatus

Types

type Client

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

Client is the base client to use either pixie cloud + vizier or standalone pem + vizier.

func NewClient

func NewClient(ctx context.Context, opts ...ClientOption) (*Client, error)

NewClient creates a new Pixie API Client.

func (*Client) CreateAPIKey

func (c *Client) CreateAPIKey(ctx context.Context, desc string) (*cloudpb.APIKey, error)

CreateAPIKey creates and API key with the passed in description.

func (*Client) CreateDeployKey

func (c *Client) CreateDeployKey(ctx context.Context, desc string) (*cloudpb.DeploymentKey, error)

CreateDeployKey creates a new deploy key, with an optional description.

func (*Client) DeleteAPIKey

func (c *Client) DeleteAPIKey(ctx context.Context, id string) error

DeleteAPIKey deletes an API key by ID.

func (*Client) GetLatestOperatorVersion

func (c *Client) GetLatestOperatorVersion(ctx context.Context) (string, error)

GetLatestOperatorVersion returns the latest version of the operator available.

func (*Client) GetLatestVizierVersion

func (c *Client) GetLatestVizierVersion(ctx context.Context) (string, error)

GetLatestVizierVersion returns the latest version of vizier available.

func (*Client) GetVizierInfo

func (c *Client) GetVizierInfo(ctx context.Context, clusterID string) (*VizierInfo, error)

GetVizierInfo gets info about the given clusterID.

func (*Client) ListViziers

func (c *Client) ListViziers(ctx context.Context) ([]*VizierInfo, error)

ListViziers gets a list of Viziers registered with Pixie.

func (*Client) NewVizierClient

func (c *Client) NewVizierClient(ctx context.Context, vizierID string) (*VizierClient, error)

NewVizierClient creates a new vizier client, for the passed in vizierID.

type ClientOption

type ClientOption func(client *Client)

ClientOption configures options on the client.

func WithAPIKey

func WithAPIKey(auth string) ClientOption

WithAPIKey is the option to specify the API key to use.

func WithBearerAuth

func WithBearerAuth(auth string) ClientOption

WithBearerAuth is the option to specify bearer auth to use.

func WithCloudAddr

func WithCloudAddr(cloudAddr string) ClientOption

WithCloudAddr is the option to specify cloud address to use.

func WithDirectAddr

func WithDirectAddr(directAddr string) ClientOption

WithDirectAddr is the option to specify direct address to use for data from standalone pem.

func WithDirectCredsInsecure

func WithDirectCredsInsecure() ClientOption

WithDirectCredsInsecure is the option to setup insecure credentials for direct connections.

func WithDisableTLSVerification

func WithDisableTLSVerification(cloudAddr string) ClientOption

Allows disabling TLS verification if the `PX_DISABLE_TLS` env var is set and the cloud address is a cluster domain (cluster.local).

func WithE2EEncryption

func WithE2EEncryption(enabled bool) ClientOption

WithE2EEncryption is the option to enable E2E ecnryption for table data.

type ResultsStats

type ResultsStats struct {
	AcceptedBytes int64
	TotalBytes    int64

	ExecutionTime    time.Duration
	CompilationTime  time.Duration
	BytesProcessed   int64
	RecordsProcessed int64
}

ResultsStats stores statistics about the data.

type ScriptResults

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

ScriptResults tracks the results of a script, and provides mechanisms to cancel, etc.

func (*ScriptResults) Close

func (s *ScriptResults) Close() error

Close will terminate the call.

func (*ScriptResults) Stats

func (s *ScriptResults) Stats() *ResultsStats

Stats returns the execution and script stats.

func (*ScriptResults) Stream

func (s *ScriptResults) Stream() error

Stream will start streaming the results. Since the API is streaming fist, even a non streaming script requires this to be called to get all the results.

type TableMuxer

type TableMuxer interface {
	// AcceptTable is passed the table information, if nil is returned then the table stream is ignored.
	AcceptTable(ctx context.Context, metadata types.TableMetadata) (TableRecordHandler, error)
}

TableMuxer is an interface to route tables to the correct handler.

type TableRecordHandler

type TableRecordHandler interface {
	// HandleInit is called to initialize the table handler interface.
	HandleInit(ctx context.Context, metadata types.TableMetadata) error
	// HandleRecord is called whenever a new row of the data is available.
	HandleRecord(ctx context.Context, record *types.Record) error
	// HandleDone is called when the table streaming has been completed.
	HandleDone(ctx context.Context) error
}

TableRecordHandler is an interface that processes a table record-wise.

type VizierClient

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

VizierClient is the client for a single vizier.

func (*VizierClient) ExecuteScript

func (v *VizierClient) ExecuteScript(ctx context.Context, pxl string, mux TableMuxer) (*ScriptResults, error)

ExecuteScript runs the script on vizier.

func (*VizierClient) GenerateOTelScript

func (v *VizierClient) GenerateOTelScript(ctx context.Context, pxl string) (string, error)

GenerateOTelScript generates an otel export script for a given pxl script that has px.display calls.

type VizierInfo

type VizierInfo struct {
	// Name of the vizier.
	Name string
	// ID of the Vizier (uuid as a string).
	ID string
	// Status of the Vizier.
	Status VizierStatus
	// Version of the installed vizier.
	Version string
}

VizierInfo has information of a single Vizier.

type VizierStatus

type VizierStatus string

VizierStatus stores the enumeration of all vizier statuses.

const (
	VizierStatusUnknown      VizierStatus = "Unknown"
	VizierStatusHealthy      VizierStatus = "Healthy"
	VizierStatusUnhealthy    VizierStatus = "Unhealthy"
	VizierStatusDisconnected VizierStatus = "Disconnected"
	VizierStatusDegraded     VizierStatus = "Degraded"
)

Vizier Statuses.