File: README.md

package info (click to toggle)
golang-github-influxdb-enterprise-client 0.0~git20151113.0.25665cb-4
  • links: PTS, VCS
  • area: main
  • in suites: buster
  • size: 112 kB
  • sloc: makefile: 2
file content (138 lines) | stat: -rw-r--r-- 4,490 bytes parent folder | download | duplicates (3)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
# Enterprise Client [![GoDoc](https://godoc.org/github.com/influxdb/enterprise-client/v1?status.svg)](https://godoc.org/github.com/influxdb/enterprise-client/v1)

The `enterprise-client` package is used to speak with the Enterprise API in a simple and straight forward way. No muss, no fuss!

## V1

### Installation

```go
$ go get github.com/influxdb/enterprise-client/v1
```

### An Important Developers Note

When testing and developing your applications to work with Enterprise, please make sure to change the `client.URL` to be something other than it's default, which is production. Might I recommend the following:

```go
client.URL = "https://enterprise.staging.influxdata.com"
```

More info can be found in the documentation [here](https://godoc.org/github.com/influxdb/enterprise-client/v1#pkg-variables).

__NOTE__: Applications should make this URL configurable.

## Registering a Customer

Customer's need to register with Enterprise and will receive a token in return. This token should be saved and sent along on all subsequent requests, more on this in a minute.

Before sending a customer to Enterprise to register you will need to generate a URL to give to that customer.

```go
c := client.New("")
r := client.Registration{
  ClusterID:   "clus1",
  Product:     "chronograf",
  RedirectURL: "http://example.com",
}

u, err := c.RegistrationURL(r)
```

If a `RedirectURL` was specified then the customer will be redirected to that URL after successfully completing their registration. There will also be a `token` query parameter attached to the URL, please retrieve and store this token for future use!

__NOTE__: If there is no token stored locally (it is up to each app to store this token), when the application starts up they user should be prompted to register with Enterprise.

## Registering a Server

When an app wakes up (influxdb, chronograf, etc…) it attempt to register itself with Enterprise:


```go
c := client.New("token-goes-here")

s := client.Server{
  ClusterID: "clus1",
  Host:      "example.com",
  Product:   "influxdb",
  Version:   "1.0",
  ServerID:  "serv1",
}

res, err := c.Save(s)
```

This should happen every time the application starts.

## Posting Product Stats:

Ideally when posting product stats data to Enterprise you will pass the "token". If no token is set then the data will __NOT__ be associated with any organization.

```go
c := client.New("token-goes-here")

st := client.Stats{
  ClusterID: "clus1",
  ServerID:  "serv1",
  Product:   "influxdb",
  Data: []client.StatsData{
    client.StatsData{
      Name: "engine",
      Tags: client.Tags{
        "path":    "/home/philip/.influxdb/data/_internal/monitor/1",
        "version": "bz1",
      },
      Values: client.Values{
        "blks_write":          39,
        "blks_write_bytes":    2421,
        "blks_write_bytes_c":  2202,
        "points_write":        39,
        "points_write_dedupe": 39,
      },
    },
  },
}

res, err := c.Save(st)
```

## Posting Usage Stats:

Usage stats are anonymous stats sent to Enterprise every 12 hours.

```go
c := client.New("token-goes-here")

u := client.Usage{
  Product: "influxdb",
  Data: []client.UsageData{
    {
      Tags: client.Tags{
        "version": "0.9.5",
        "arch":    "amd64",
        "os":      "linux",
      },
      Values: client.Values{
        "cluster_id":       "23423",
        "server_id":        "1",
        "num_databases":    3,
        "num_measurements": 2342,
        "num_series":       87232,
      },
    },
  },
}

res, err := c.Save(u)
```

## API Errors

As you probably know [Go doesn't return error codes for non-2xx HTTP requests](http://metabates.com/2015/10/15/handling-http-request-errors-in-go/), but thankfully the Enterprise Client does!

The API will return one of two errors back to you if there are any problems:

* `SimpleError` - This type of error is common for status codes such as `401`, `404`, and `500`. [https://godoc.org/github.com/influxdb/enterprise-client/v1#SimpleError](https://godoc.org/github.com/influxdb/enterprise-client/v1#SimpleError)
* `ValidationErrors` - Type type of error is common for status codes such as `422` and will return specific errors related to the validity of the payload sent to the API. [https://godoc.org/github.com/influxdb/enterprise-client/v1#ValidationErrors](https://godoc.org/github.com/influxdb/enterprise-client/v1#ValidationErrors)

It is recommended to check for these errors and handle them appropriately.