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

type BatchPoints ¶

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.

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)
}

▹ Example

▾ Example

Create a batch and add a point

Code:

// 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)

▹ Example (Setters)

▾ Example (Setters)

Using the BatchPoints setter functions

Code:

// 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)

func NewBatchPoints ¶

func NewBatchPoints(conf BatchPointsConfig) (BatchPoints, error)

NewBatchPoints returns a BatchPoints interface based on the given config.

type BatchPointsConfig ¶

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

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
}

type Client ¶

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

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
}

▹ Example

▾ Example

Create a new client

Code:

// 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())
}

▹ Example (CreateDatabase)

▾ Example (CreateDatabase)

Create a Database with a query

Code:

// 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)
}

▹ Example (Query)

▾ Example (Query)

Make a Query

Code:

// 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)
}

▹ Example (UDP)

▾ Example (UDP)

Write a point using the UDP client

Code:

// 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)

▹ Example (Write)

▾ Example (Write)

Write a point using the HTTP client

Code:

// 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)

▹ Example (Write1000)

▾ Example (Write1000)

Write 1000 points

Code:

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())
}

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 ¶

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

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
}

type Message ¶

Message represents a user message.

type Message struct {
    Level string
    Text  string
}

type Point ¶

Point represents a single data point.

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

▹ Example

▾ Example

Create a new point with a timestamp

Code:

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())
}

▹ Example (WithoutTime)

▾ Example (WithoutTime)

Create a new point without a timestamp

Code:

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())
}

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(precison 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 ¶

Query defines a query to send to the server.

type Query struct {
    Command    string
    Database   string
    Precision  string
    Parameters map[string]interface{}
}

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 ¶

Response represents a list of statement results.

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

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 ¶

Result represents a resultset returned from a single statement.

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

type UDPConfig ¶

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

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
}

Package client

Overview ▹

Overview ▾

Index ▹

Index ▾

Examples

Package files

Internal call graph ▹

Internal call graph ▾

Constants

type BatchPoints ¶

func NewBatchPoints ¶

type BatchPointsConfig ¶

type Client ¶

func NewHTTPClient ¶

func NewUDPClient ¶

type HTTPConfig ¶

type Message ¶

type Point ¶

func NewPoint ¶

func NewPointFrom ¶

func (*Point) Fields ¶

func (*Point) Name ¶

func (*Point) PrecisionString ¶

func (*Point) String ¶

func (*Point) Tags ¶

func (*Point) Time ¶

func (*Point) UnixNano ¶

type Query ¶

func NewQuery ¶

func NewQueryWithParameters ¶

type Response ¶

func (*Response) Error ¶

type Result ¶

type UDPConfig ¶