Debian Codegraph @

README.md

raw
1 # Enterprise Client [![GoDoc](https://godoc.org/github.com/influxdb/enterprise-client/v1?status.svg)](https://godoc.org/github.com/influxdb/enterprise-client/v1)
2
3 The `enterprise-client` package is used to speak with the Enterprise API in a simple and straight forward way. No muss, no fuss!
4
5 ## V1
6
7 ### Installation
8
9 ```go
10 $ go get github.com/influxdb/enterprise-client/v1
11 ```
12
13 ### An Important Developers Note
14
15 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:
16
17 ```go
18 client.URL = "https://enterprise.staging.influxdata.com"
19 ```
20
21 More info can be found in the documentation [here](https://godoc.org/github.com/influxdb/enterprise-client/v1#pkg-variables).
22
23 __NOTE__: Applications should make this URL configurable.
24
25 ## Registering a Customer
26
27 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.
28
29 Before sending a customer to Enterprise to register you will need to generate a URL to give to that customer.
30
31 ```go
32 c := client.New("")
33 r := client.Registration{
34 ClusterID: "clus1",
35 Product: "chronograf",
36 RedirectURL: "http://example.com",
37 }
38
39 u, err := c.RegistrationURL(r)
40 ```
41
42 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!
43
44 __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.
45
46 ## Registering a Server
47
48 When an app wakes up (influxdb, chronograf, etc…) it attempt to register itself with Enterprise:
49
50
51 ```go
52 c := client.New("token-goes-here")
53
54 s := client.Server{
55 ClusterID: "clus1",
56 Host: "example.com",
57 Product: "influxdb",
58 Version: "1.0",
59 ServerID: "serv1",
60 }
61
62 res, err := c.Save(s)
63 ```
64
65 This should happen every time the application starts.
66
67 ## Posting Product Stats:
68
69 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.
70
71 ```go
72 c := client.New("token-goes-here")
73
74 st := client.Stats{
75 ClusterID: "clus1",
76 ServerID: "serv1",
77 Product: "influxdb",
78 Data: []client.StatsData{
79 client.StatsData{
80 Name: "engine",
81 Tags: client.Tags{
82 "path": "/home/philip/.influxdb/data/_internal/monitor/1",
83 "version": "bz1",
84 },
85 Values: client.Values{
86 "blks_write": 39,
87 "blks_write_bytes": 2421,
88 "blks_write_bytes_c": 2202,
89 "points_write": 39,
90 "points_write_dedupe": 39,
91 },
92 },
93 },
94 }
95
96 res, err := c.Save(st)
97 ```
98
99 ## Posting Usage Stats:
100
101 Usage stats are anonymous stats sent to Enterprise every 12 hours.
102
103 ```go
104 c := client.New("token-goes-here")
105
106 u := client.Usage{
107 Product: "influxdb",
108 Data: []client.UsageData{
109 {
110 Tags: client.Tags{
111 "version": "0.9.5",
112 "arch": "amd64",
113 "os": "linux",
114 },
115 Values: client.Values{
116 "cluster_id": "23423",
117 "server_id": "1",
118 "num_databases": 3,
119 "num_measurements": 2342,
120 "num_series": 87232,
121 },
122 },
123 },
124 }
125
126 res, err := c.Save(u)
127 ```
128
129 ## API Errors
130
131 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!
132
133 The API will return one of two errors back to you if there are any problems:
134
135 * `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)
136 * `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)
137
138 It is recommended to check for these errors and handle them appropriately.