client

package
v1.2.3-0...-0f6e6fb Latest Latest
Warning

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

 Go to latest Published: Feb 1, 2018 License: MIT Imports: 15 Imported by: 0

Documentation

Overview

Package client (v2) is the current official Go client for InfluxDB.

Index

Examples

Constants

View Source 
const (
	// UDPPayloadSize is a reasonable default payload size for UDP packets that
	// could be travelling over the internet.
	UDPPayloadSize = 512
)

Variables

This section is empty.

Functions

This section is empty.

Types

type BatchPoints 

type BatchPoints interface {
	// AddPoint adds the given point to the Batch of points.
	AddPoint(p *Point)
	// AddPoints adds the given points to the Batch of points.
	AddPoints(ps []*Point)
	// Points lists the points in the Batch.
	Points() []*Point

	// Precision returns the currently set precision of this Batch.
	Precision() string
	// SetPrecision sets the precision of this batch.
	SetPrecision(s string) error

	// Database returns the currently set database of this Batch.
	Database() string
	// SetDatabase sets the database of this Batch.
	SetDatabase(s string)

	// WriteConsistency returns the currently set write consistency of this Batch.
	WriteConsistency() string
	// SetWriteConsistency sets the write consistency of this Batch.
	SetWriteConsistency(s string)

	// RetentionPolicy returns the currently set retention policy of this Batch.
	RetentionPolicy() string
	// SetRetentionPolicy sets the retention policy of this Batch.
	SetRetentionPolicy(s string)
}

BatchPoints is an interface into a batched grouping of points to write into InfluxDB together. BatchPoints is NOT thread-safe, you must create a separate batch for each goroutine.

Example

Create a batch and add a point 

// Create a new point batch
bp, _ := client.NewBatchPoints(client.BatchPointsConfig{
	Database:  "BumbleBeeTuna",
	Precision: "s",
})

// Create a point and add to batch
tags := map[string]string{"cpu": "cpu-total"}
fields := map[string]interface{}{
	"idle":   10.1,
	"system": 53.3,
	"user":   46.6,
}
pt, err := client.NewPoint("cpu_usage", tags, fields, time.Now())
if err != nil {
	fmt.Println("Error: ", err.Error())
}
bp.AddPoint(pt)

Output:
Example (Setters)

Using the BatchPoints setter functions 

// Create a new point batch
bp, _ := client.NewBatchPoints(client.BatchPointsConfig{})
bp.SetDatabase("BumbleBeeTuna")
bp.SetPrecision("ms")

// Create a point and add to batch
tags := map[string]string{"cpu": "cpu-total"}
fields := map[string]interface{}{
	"idle":   10.1,
	"system": 53.3,
	"user":   46.6,
}
pt, err := client.NewPoint("cpu_usage", tags, fields, time.Now())
if err != nil {
	fmt.Println("Error: ", err.Error())
}
bp.AddPoint(pt)

Output:

func NewBatchPoints 

func NewBatchPoints(conf BatchPointsConfig) (BatchPoints, error)

NewBatchPoints returns a BatchPoints interface based on the given config.

type BatchPointsConfig 

type BatchPointsConfig struct {
	// Precision is the write precision of the points, defaults to "ns".
	Precision string

	// Database is the database to write points to.
	Database string

	// RetentionPolicy is the retention policy of the points.
	RetentionPolicy string

	// Write consistency is the number of servers required to confirm write.
	WriteConsistency string
}

BatchPointsConfig is the config data needed to create an instance of the BatchPoints struct.

type ChunkedResponse 

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

ChunkedResponse represents a response from the server that uses chunking to stream the output.

func NewChunkedResponse 

func NewChunkedResponse(r io.Reader) *ChunkedResponse

NewChunkedResponse reads a stream and produces responses from the stream.

func (*ChunkedResponse) NextResponse 

func (r *ChunkedResponse) NextResponse() (*Response, error)

NextResponse reads the next line of the stream and returns a response.

type Client 

type Client interface {
	// Ping checks that status of cluster, and will always return 0 time and no
	// error for UDP clients.
	Ping(timeout time.Duration) (time.Duration, string, error)

	// Write takes a BatchPoints object and writes all Points to InfluxDB.
	Write(bp BatchPoints) error

	// Query makes an InfluxDB Query on the database. This will fail if using
	// the UDP client.
	Query(q Query) (*Response, error)

	// Close releases any resources a Client may be using.
	Close() error
}

Client is a client interface for writing & querying the database.

Example

Create a new client 

// NOTE: this assumes you've setup a user and have setup shell env variables,
// namely INFLUX_USER/INFLUX_PWD. If not just omit Username/Password below.
_, err := client.NewHTTPClient(client.HTTPConfig{
	Addr:     "http://localhost:8086",
	Username: os.Getenv("INFLUX_USER"),
	Password: os.Getenv("INFLUX_PWD"),
})
if err != nil {
	fmt.Println("Error creating InfluxDB Client: ", err.Error())
}

Output:
Example (CreateDatabase)

Create a Database with a query 

// Make client
c, err := client.NewHTTPClient(client.HTTPConfig{
	Addr: "http://localhost:8086",
})
if err != nil {
	fmt.Println("Error creating InfluxDB Client: ", err.Error())
}
defer c.Close()

q := client.NewQuery("CREATE DATABASE telegraf", "", "")
if response, err := c.Query(q); err == nil && response.Error() == nil {
	fmt.Println(response.Results)
}

Output:
Example (Query)

Make a Query 

// Make client
c, err := client.NewHTTPClient(client.HTTPConfig{
	Addr: "http://localhost:8086",
})
if err != nil {
	fmt.Println("Error creating InfluxDB Client: ", err.Error())
}
defer c.Close()

q := client.NewQuery("SELECT count(value) FROM shapes", "square_holes", "ns")
if response, err := c.Query(q); err == nil && response.Error() == nil {
	fmt.Println(response.Results)
}

Output:
Example (UDP)

Write a point using the UDP client 

// Make client
config := client.UDPConfig{Addr: "localhost:8089"}
c, err := client.NewUDPClient(config)
if err != nil {
	fmt.Println("Error: ", err.Error())
}
defer c.Close()

// Create a new point batch
bp, _ := client.NewBatchPoints(client.BatchPointsConfig{
	Precision: "s",
})

// Create a point and add to batch
tags := map[string]string{"cpu": "cpu-total"}
fields := map[string]interface{}{
	"idle":   10.1,
	"system": 53.3,
	"user":   46.6,
}
pt, err := client.NewPoint("cpu_usage", tags, fields, time.Now())
if err != nil {
	fmt.Println("Error: ", err.Error())
}
bp.AddPoint(pt)

// Write the batch
c.Write(bp)

Output:
Example (Write)

Write a point using the HTTP client 

// Make client
c, err := client.NewHTTPClient(client.HTTPConfig{
	Addr: "http://localhost:8086",
})
if err != nil {
	fmt.Println("Error creating InfluxDB Client: ", err.Error())
}
defer c.Close()

// Create a new point batch
bp, _ := client.NewBatchPoints(client.BatchPointsConfig{
	Database:  "BumbleBeeTuna",
	Precision: "s",
})

// Create a point and add to batch
tags := map[string]string{"cpu": "cpu-total"}
fields := map[string]interface{}{
	"idle":   10.1,
	"system": 53.3,
	"user":   46.6,
}
pt, err := client.NewPoint("cpu_usage", tags, fields, time.Now())
if err != nil {
	fmt.Println("Error: ", err.Error())
}
bp.AddPoint(pt)

// Write the batch
c.Write(bp)

Output:
Example (Write1000)

Write 1000 points 

sampleSize := 1000

// Make client
c, err := client.NewHTTPClient(client.HTTPConfig{
	Addr: "http://localhost:8086",
})
if err != nil {
	fmt.Println("Error creating InfluxDB Client: ", err.Error())
}
defer c.Close()

rand.Seed(42)

bp, _ := client.NewBatchPoints(client.BatchPointsConfig{
	Database:  "systemstats",
	Precision: "us",
})

for i := 0; i < sampleSize; i++ {
	regions := []string{"us-west1", "us-west2", "us-west3", "us-east1"}
	tags := map[string]string{
		"cpu":    "cpu-total",
		"host":   fmt.Sprintf("host%d", rand.Intn(1000)),
		"region": regions[rand.Intn(len(regions))],
	}

	idle := rand.Float64() * 100.0
	fields := map[string]interface{}{
		"idle": idle,
		"busy": 100.0 - idle,
	}

	pt, err := client.NewPoint(
		"cpu_usage",
		tags,
		fields,
		time.Now(),
	)
	if err != nil {
		println("Error:", err.Error())
		continue
	}
	bp.AddPoint(pt)
}

err = c.Write(bp)
if err != nil {
	fmt.Println("Error: ", err.Error())
}

Output:

func NewHTTPClient 

func NewHTTPClient(conf HTTPConfig) (Client, error)

NewHTTPClient returns a new Client from the provided config. Client is safe for concurrent use by multiple goroutines.

func NewUDPClient 

func NewUDPClient(conf UDPConfig) (Client, error)

NewUDPClient returns a client interface for writing to an InfluxDB UDP service from the given config.

type HTTPConfig 

type HTTPConfig struct {
	// Addr should be of the form "http://host:port"
	// or "http://[ipv6-host%zone]:port".
	Addr string

	// Username is the influxdb username, optional.
	Username string

	// Password is the influxdb password, optional.
	Password string

	// UserAgent is the http User Agent, defaults to "InfluxDBClient".
	UserAgent string

	// Timeout for influxdb writes, defaults to no timeout.
	Timeout time.Duration

	// InsecureSkipVerify gets passed to the http client, if true, it will
	// skip https certificate verification. Defaults to false.
	InsecureSkipVerify bool

	// TLSConfig allows the user to set their own TLS config for the HTTP
	// Client. If set, this option overrides InsecureSkipVerify.
	TLSConfig *tls.Config
}

HTTPConfig is the config data needed to create an HTTP Client.

type Message 

type Message struct {
	Level string
	Text  string
}

Message represents a user message.

type Point 

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

Point represents a single data point.

Example

Create a new point with a timestamp 

tags := map[string]string{"cpu": "cpu-total"}
fields := map[string]interface{}{
	"idle":   10.1,
	"system": 53.3,
	"user":   46.6,
}
pt, err := client.NewPoint("cpu_usage", tags, fields, time.Now())
if err == nil {
	fmt.Println("We created a point: ", pt.String())
}

Output:
Example (WithoutTime)

Create a new point without a timestamp 

tags := map[string]string{"cpu": "cpu-total"}
fields := map[string]interface{}{
	"idle":   10.1,
	"system": 53.3,
	"user":   46.6,
}
pt, err := client.NewPoint("cpu_usage", tags, fields)
if err == nil {
	fmt.Println("We created a point w/o time: ", pt.String())
}

Output:

func NewPoint 

func NewPoint(
	name string,
	tags map[string]string,
	fields map[string]interface{},
	t ...time.Time,
) (*Point, error)

NewPoint returns a point with the given timestamp. If a timestamp is not given, then data is sent to the database without a timestamp, in which case the server will assign local time upon reception. NOTE: it is recommended to send data with a timestamp.

func NewPointFrom 

func NewPointFrom(pt models.Point) *Point

NewPointFrom returns a point from the provided models.Point.

func (*Point) Fields 

func (p *Point) Fields() (map[string]interface{}, error)

Fields returns the fields for the point.

func (*Point) Name 

func (p *Point) Name() string

Name returns the measurement name of the point.

func (*Point) PrecisionString 

func (p *Point) PrecisionString(precision string) string

PrecisionString returns a line-protocol string of the Point, with the timestamp formatted for the given precision.

func (*Point) String 

func (p *Point) String() string

String returns a line-protocol string of the Point.

func (*Point) Tags 

func (p *Point) Tags() map[string]string

Tags returns the tags associated with the point.

func (*Point) Time 

func (p *Point) Time() time.Time

Time return the timestamp for the point.

func (*Point) UnixNano 

func (p *Point) UnixNano() int64

UnixNano returns timestamp of the point in nanoseconds since Unix epoch.

type Query 

type Query struct {
	Command    string
	Database   string
	Precision  string
	Chunked    bool
	ChunkSize  int
	Parameters map[string]interface{}
}

Query defines a query to send to the server.

func NewQuery 

func NewQuery(command, database, precision string) Query

NewQuery returns a query object. The database and precision arguments can be empty strings if they are not needed for the query.

func NewQueryWithParameters 

func NewQueryWithParameters(command, database, precision string, parameters map[string]interface{}) Query

NewQueryWithParameters returns a query object. The database and precision arguments can be empty strings if they are not needed for the query. parameters is a map of the parameter names used in the command to their values.

type Response 

type Response struct {
	Results []Result
	Err     string `json:"error,omitempty"`
}

Response represents a list of statement results.

func (*Response) Error 

func (r *Response) Error() error

Error returns the first error from any statement. It returns nil if no errors occurred on any statements.

type Result 

type Result struct {
	Series   []models.Row
	Messages []*Message
	Err      string `json:"error,omitempty"`
}

Result represents a resultset returned from a single statement.

type UDPConfig 

type UDPConfig struct {
	// Addr should be of the form "host:port"
	// or "[ipv6-host%zone]:port".
	Addr string

	// PayloadSize is the maximum size of a UDP client message, optional
	// Tune this based on your network. Defaults to UDPPayloadSize.
	PayloadSize int
}

UDPConfig is the config data needed to create a UDP Client.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.