Add guide to exporting metrics to Graphite (#9285)
* Init guide, add links * Grammar and typo pass * Fixes for Thiago * Fix for Vlad
Joel Hans committed
Jun 9, 2020 at 10:20 UTC
4456e300befe1f1c70f50ca39a921e03b8dfbc58
3 files changed
+192
-5
docs/export/README.md
+4
-4
@@ -90,12 +90,12 @@ For details on all the configuration options, see the [exporting reference](/exp
90
Restart your Agent to begin exporting to the destination of your choice. Because the Agent exports metrics as they're
91
collected, you should start seeing data in your external database after only a few seconds.
92
93
-## Exporting reference and related features
93
+## Exporting reference, guides, and related features
94
95
- [Exporting reference guide](/exporting/README.md)
96
+- [Guide: Export and visualize Netdata metrics in Graphite](/docs/guides/export/export-netdata-metrics-graphite.md)
97
+- [Guide: Use host labels to organize systems, metrics, and alarms](/docs/guides/using-host-labels.md)
98
+- [Guide: Change how long Netdata stores metrics (long-term storage)](/docs/guides/longer-metrics-storage.md)
99
- [Backends (deprecated)](/backends/README.md)
97
-- [Use host labels to organize systems, metrics, and alarms](/docs/guides/using-host-labels.md)
98
-- [Database engine](/database/engine/README.md)
99
-- [Change how long Netdata stores metrics (long-term storage)](/docs/guides/longer-metrics-storage.md)
100
101
[](<>)
docs/guides/export/export-netdata-metrics-graphite.md
new
+184
@@ -0,0 +1,184 @@
1
+<!--
2
+title: Export and visualize Netdata metrics in Graphite
3
+description: Use Netdata to collect and export thousands of metrics to Graphite for long-term storage or further analysis.
4
+image: /img/seo/guides/export/export-netdata-metrics-graphite.png
5
+-->
6
+
7
+# Export and visualize Netdata metrics in Graphite
8
+
9
+Collecting metrics is an essential part of monitoring any application, service, or infrastructure, but it's not the
10
+final step for any developer, sysadmin, SRE, or DevOps engineer who's keeping an eye on things. To take meaningful
11
+action on these metrics, you may need to develop a stack of monitoring tools that work in parallel to help you diagnose
12
+anomalies and discover root causes faster.
13
+
14
+We designed Netdata with interoperability in mind. The Agent collects thousands of metrics every second, and then what
15
+you do with them is up to you. You can [store metrics in the database engine](/docs/guides/longer-metrics-storage.md),
16
+or send them to another time series database for long-term storage or further analysis using Netdata's [exporting
17
+engine](/docs/export/README.md).
18
+
19
+In this guide, we'll show you how to export Netdata metrics to [Graphite](https://graphiteapp.org/) for long-term
20
+storage and further analysis. Graphite is a free open-source software (FOSS) tool that collects graphs numeric
21
+time-series data, such as all the metrics collected by the Netdata Agent itself. Using Netdata and Graphite together,
22
+you get more visibility into the health and performance of your entire infrastructure.
23
+
24
+
26
+
27
+Let's get started.
28
+
29
+## Install the Netdata Agent
30
+
31
+If you don't have the Netdata Agent installed already, visit the [installation guide](/packaging/installer/README.md)
32
+for the recommended instructions for your system. In most cases, you can use the one-line installation script:
33
+
34
+```bash
35
+bash <(curl -Ss https://my-netdata.io/kickstart.sh)
36
+```
37
+
38
+Once installation finishes, open your browser and navigate to `http://NODE:19999`, replacing `NODE` with the IP address
39
+or hostname of your system, to find the Agent dashboard.
40
+
41
+## Install Graphite via Docker
42
+
43
+For this guide, we'll install Graphite using Docker. See the [Docker documentation](https://docs.docker.com/get-docker/)
44
+for details if you don't yet have it installed on your system.
45
+
46
+> If you already have Graphite installed, skip this step. If you want to install via a different method, see the
47
+> [Graphite installation docs](https://graphite.readthedocs.io/en/latest/install.html), with the caveat that some
48
+> configuration settings may be different.
49
+
50
+Start up the Graphite image with `docker run`.
51
+
52
+```bash
53
+docker run -d \
54
+ --name graphite \
55
+ --restart=always \
56
+ -p 80:80 \
57
+ -p 2003-2004:2003-2004 \
58
+ -p 2023-2024:2023-2024 \
59
+ -p 8125:8125/udp \
60
+ -p 8126:8126 \
61
+ graphiteapp/graphite-statsd
62
+```
63
+
64
+Open your browser and navigate to `http://NODE`, to see the Graphite interface. Nothing yet, but we'll fix that soon
65
+enough.
66
+
67
+
69
+
70
+## Enable the Graphite exporting connector
71
+
72
+You're now ready to begin exporting Netdata metrics to Graphite.
73
+
74
+Begin by using `edit-config` to open the `exporting.conf` file.
75
+
76
+```bash
77
+cd /etc/netdata # Replace this path with your Netdata config directory
78
+sudo ./edit-config exporting.conf
79
+```
80
+
81
+If you haven't already, enable the exporting engine by setting `enabled` to `yes` in the `[exporting:global]` section.
82
+
83
+```conf
84
+[exporting:global]
85
+ enabled = yes
86
+```
87
+
88
+Next, configure the connector. Find the `[graphite:my_graphite_instance]` example section and uncomment the line.
89
+Replace `my_graphite_instance` with a name of your choice. Let's go with `[graphite:netdata]`. Set `enabled` to `yes`
90
+and uncomment the line. Your configuration should now look like this:
91
+
92
+```conf
93
+[graphite:netdata]
94
+ enabled = yes
95
+ # destination = localhost
96
+ # data source = average
97
+ # prefix = netdata
98
+ # hostname = my_hostname
99
+ # update every = 10
100
+ # buffer on failures = 10
101
+ # timeout ms = 20000
102
+ # send names instead of ids = yes
103
+ # send charts matching = *
104
+ # send hosts matching = localhost *
105
+```
106
+
107
+Set the `destination` setting to `localhost:2003`. By default, the Docker image for Graphite listens on port `2003` for
108
+incoming metrics. If you installed Graphite a different way, or tweaked the `docker run` command, you may need to change
109
+the port accordingly.
110
+
111
+```conf
112
+[graphite:netdata]
113
+ enabled = yes
114
+ destination = localhost:2003
115
+ ...
116
+```
117
+
118
+We'll not worry about the rest of the settings for now. Restart the Agent using `sudo service netdata restart`, or the
119
+appropriate method for your system, to spin up the exporting engine.
120
+
121
+## See and organize Netdata metrics in Graphite
122
+
123
+Head back to the Graphite interface again, then click on the **Dashboard** link to get started with Netdata's exported
124
+metrics. You can also navigate directly to `http://NODE/dashboard`.
125
+
126
+Let's switch the interface to help you understand which metrics Netdata is exporting to Graphite. Click on **Dashboard**
127
+and **Configure UI**, then choose the **Tree** option. Refresh your browser to change the UI.
128
+
129
+
131
+
132
+You should now see a tree of available contexts, including one that matches the hostname of the Agent exporting metrics.
133
+In this example, the Agent's hostname is `arcturus`.
134
+
135
+Let's add some system CPU charts so you can monitor the long-term health of your system. Click through the tree to find
136
+**hostname → system → cpu** metrics, then click on the **user** context. A chart with metrics from that context appears
137
+in the dashboard. Add a few other system CPU charts to flesh things out.
138
+
139
+Next, let's combine one or two of these charts. Click and drag one chart onto the other, and wait until the green **Drop
140
+to merge** dialog appears. Release to merge the charts.
141
+
142
+
144
+
145
+Finally, save your dashboard. Click **Dashboard**, then **Save As**, then choose a name. Your dashboard is now saved.
146
+
147
+Of course, this is just the beginning of the customization you can do with Graphite. You can change the time range,
148
+share your dashboard with others, or use the composer to customize the size and appearance of specific charts. Learn
149
+more about adding, modifying, and combining graphs in the [Graphite
150
+docs](https://graphite.readthedocs.io/en/latest/dashboard.html).
151
+
152
+## Monitor the exporting engine
153
+
154
+As soon as the exporting engine begins, Netdata begins reporting metrics about the system's health and performance.
155
+
156
+
158
+
159
+You can use these charts to verify that Netdata is properly exporting metrics to Graphite. You can even add these
160
+exporting charts to your Graphite dashboard!
161
+
162
+### Add exporting charts to Netdata Cloud
163
+
164
+You can also show these exporting engine metrics on Netdata Cloud. If you don't have an account already, go [sign
165
+in](https://app.netdata.cloud) and get started for free. If you need some help along the way, read the [get started with
166
+Cloud guide](https://learn.netdata.cloud/docs/cloud/get-started).
167
+
168
+Add more metrics to the Nodes view by clicking on the **Add metric** button, then typing `exporting` into the context
169
+field. Choose the exporting contexts you want to add, then click **Add**. You'll see these charts alongside any others
170
+you've customized in Netdata Cloud.
171
+
172
+
174
+
175
+## What's next?
176
+
177
+What you do with your exported metrics is entirely up to you, but as you might have seen in the Graphite connector
178
+configuration block, there are many other ways to tweak and customize which metrics you export to Graphite and how
179
+often.
180
+
181
+For full details about each configuration option and what it does, see the [exporting reference
182
+guide](/exporting/README.md).
183
+
184
+[](<>)
exporting/README.md
+4
-1
@@ -38,9 +38,12 @@ X seconds (though, it can send them per second if you need it to).
38
- **graphite** (`plaintext interface`, used by **Graphite**, **InfluxDB**, **KairosDB**, **Blueflood**,
39
**ElasticSearch** via logstash tcp input and the graphite codec, etc)
40
41
- metrics are sent to the database server as `prefix.hostname.chart.dimension`. `prefix` is configured below,
41
+ Metrics are sent to the database server as `prefix.hostname.chart.dimension`. `prefix` is configured below,
42
`hostname` is the hostname of the machine (can also be configured).
43
44
+ Learn more in our guide to [export and visualize Netdata metrics in
45
+ Graphite](/docs/guides/export/export-netdata-metrics-graphite.md).
46
+
47
- **opentsdb** (`telnet or HTTP interfaces`, used by **OpenTSDB**, **InfluxDB**, **KairosDB**, etc)
48
49
metrics are sent to OpenTSDB as `prefix.chart.dimension` with tag `host=hostname`.