Influxdata
/
docs-v2
mirror of https://github.com/influxdata/docs-v2.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

ported chronograf 1.8

pull/1387/head
Scott Anderson 2020-07-30 11:31:32 -06:00
parent 926c515c53
commit dc6fc2f771
49 changed files with 7125 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

51
content/chronograf/v1.8/_index.md Normal file
View File

@ -0,0 +1,51 @@
---
title: Chronograf 1.8 documentation
menu:
chronograf:
name: v1.8
identifier: chronograf_1_8
weight: 1
---
Chronograf is InfluxData's open source web application.
Use Chronograf with the other components of the [TICK stack](https://www.influxdata.com/products/) to visualize your monitoring data and easily create alerting and automation rules.
![Chronograf Collage](/img/chronograf/v1.8/chronograf-collage.png)
## Key features
### Infrastructure monitoring
* View all hosts and their statuses in your infrastructure
* View the configured applications on each host
* Monitor your applications with Chronograf's [pre-created dashboards](/chronograf/v1.8/guides/using-precreated-dashboards/)
### Alert management
Chronograf offers a UI for [Kapacitor](https://github.com/influxdata/kapacitor), InfluxData's data processing framework for creating alerts, running ETL jobs, and detecting anomalies in your data.
* Generate threshold, relative, and deadman alerts on your data
* Easily enable and disable existing alert rules
* View all active alerts on an alert dashboard
* Send alerts to the supported event handlers, including Slack, PagerDuty, HipChat, and [more](/chronograf/v1.8/guides/configuring-alert-endpoints/)
### Data visualization
* Monitor your application data with Chronograf's [pre-created dashboards](/chronograf/v1.8/guides/using-precreated-dashboards/)
* Create your own customized dashboards complete with various graph types and [template variables](/chronograf/v1.8/guides/dashboard-template-variables/)
* Investigate your data with Chronograf's data explorer and query templates
### Database management
* Create and delete databases and retention policies
* View currently-running queries and stop inefficient queries from overloading your system
* Create, delete, and assign permissions to users (Chronograf supports [InfluxDB OSS](/influxdb/latest/administration/authentication_and_authorization/#authorization) and InfluxEnterprise user management)
### Multi-organization and multi-user support
>**Note:** To use this feature, OAuth 2.0 authentication must be configured. Once configured, the Chronograf Admin tab on the Admin menu is visible. For details, see [Managing Chronograf security](/chronograf/v1.8/administration/managing-security/).
* Create organizations and assign users to those organizations
* Restrict access to administrative functions
* Allow users to set up and maintain unique dashboards for their organizations

59
content/chronograf/v1.8/about_the_project/_index.md Normal file
View File

@ -0,0 +1,59 @@
---
title: About the Chronograf project
description: Chronograf is the UI component of the InfluxData time series platform. This section includes documentation about the Chronograf project, release notes and changelogs, what's new, contributing, and licenses.
menu:
chronograf_1_8:
name: About the project
weight: 10
---
Chronograf is the user interface component of the [InfluxData time series platform](https://www.influxdata.com/time-series-platform/). It makes the monitoring and alerting for your infrastructure easy to setup and maintain. It is simple to use and includes templates and libraries to allow you to rapidly build dashboards with realtime visualizations of your data.
Follow the links below for more information.
## [Chronograf 1.8 release notes](/chronograf/v1.8/about_the_project/release-notes-changelog/)
The [Chronograf 1.8 release notes](/chronograf/v1.8/about_the_project/release-notes-changelog/) includes details about features, bug fixes, and breaking changes for current and earlier Chronograf OSS releases.
## [Contributing to Chronograf](https://github.com/influxdata/chronograf/blob/master/CONTRIBUTING.md)
See [Contributing to InfluxDB OSS](https://github.com/influxdata/chronograf/blob/master/CONTRIBUTING.md) for information about how you can contribute to the InfluxDB OSS GitHub project.
### [InfluxData Contributor License Agreement (CLA)](https://influxdata.com/community/cla/)
In order to begin contributing to InfluxDB OSS project, you need to complete and sign the [InfluxData Contributor License Agreement (CLA)](https://influxdata.com/community/cla/).
## [Open source license for Chronograf](https://github.com/influxdata/chronograf/blob/master/LICENSE/)
See the [open source license for Chronograf](https://github.com/influxdata/chronograf/blob/master/LICENSE/) for conditions and restrictions for the use of the Chronograf source code.
Chronograf is released under the GNU Affero General Public License. This Free Software Foundation license is fairly new,
and differs from the more widely known and understood GPL.
Our goal with using AGPL is to preserve the concept of copyleft with Chronograf.
With traditional GPL, copyleft was associated with the concept of distribution of software.
The problem is that nowadays, distribution of software is rare: things tend to run in the cloud. AGPL fixes this “loophole”
in GPL by saying that if you use the software over a network, you are bound by the copyleft. Other than that,
the license is virtually the same as GPL v3.
To say this another way: if you modify the core source code of Chronograf, the goal is that you have to contribute
those modifications back to the community.
Note however that it is NOT required that your dashboards and alerts created by using Chronograf be published.
The copyleft applies only to the source code of Chronograf itself.
If this explanation isn't good enough for you and your use case, we dual license Chronograf under our
[standard commercial license](https://www.influxdata.com/legal/slsa/).
[Contact sales for more information](https://www.influxdata.com/contact-sales/).
## Third Party Software
InfluxData products contain third party software, which means the copyrighted, patented, or otherwise legally protected
software of third parties that is incorporated in InfluxData products.
Third party suppliers make no representation nor warranty with respect to such third party software or any portion thereof.
Third party suppliers assume no liability for any claim that might arise with respect to such third party software,
nor for a customer’s use of or inability to use the third party software.
The [list of third party software components, including references to associated license and other materials](https://github.com/influxdata/chronograf/blob/master/LICENSE_OF_DEPENDENCIES.md),
is maintained on a version by version basis.

11
content/chronograf/v1.8/about_the_project/cla.md Normal file
View File

@ -0,0 +1,11 @@
---
title: InfluxData Contributor License Agreement (CLA)
description: Before contributing to the Chronograf project, you need to submit the InfluxData Contributor License Agreement.
menu:
chronograf_1_8:
weight: 30
parent: About the project
url: https://www.influxdata.com/legal/cla/
---
Before you can contribute to the Chronograf project, you need to submit the [InfluxData Contributor License Agreement (CLA)](https://www.influxdata.com/legal/cla/) available on the InfluxData main site.

11
content/chronograf/v1.8/about_the_project/contributing.md Normal file
View File

@ -0,0 +1,11 @@
---
title: Contributing to Chronograf
menu:
chronograf_1_8:
name: Contributing
weight: 20
parent: About the project
url: https://github.com/influxdata/chronograf/blob/master/CONTRIBUTING.md
---
See [Contributing to Chronograf](https://github.com/influxdata/chronograf/blob/master/CONTRIBUTING.md) in the Chronograf GitHub project to learn how you can contribute to the Chronograf project.

11
content/chronograf/v1.8/about_the_project/licenses.md Normal file
View File

@ -0,0 +1,11 @@
---
title: Open source license for Chronograf
menu:
chronograf_1_8:
Name: Open source license
weight: 40
parent: About the project
url: https://github.com/influxdata/chronograf/blob/master/LICENSE
---
The [open source license for Chronograf](https://github.com/influxdata/chronograf/blob/master/LICENSE) is available in the Chronograf GitHub project.

1021
content/chronograf/v1.8/about_the_project/release-notes-changelog.md Normal file
View File

File diff suppressed because it is too large Load Diff

52
content/chronograf/v1.8/administration/_index.md Normal file
View File

@ -0,0 +1,52 @@
---
title: Administering Chronograf
description: This section documents Chronograf administration, including configuration, InfluxDB Enterprise clusters, Kapacitor and InfluxDB connections, user and organization management, security, and upgrading.
menu:
chronograf_1_8:
name: Administration
weight: 40
---
Follow the links below for more information.
## [Upgrading to Chronograf 1.8](/chronograf/v1.8/administration/upgrading/)
See [Upgrading to Chronograf 1.8](/chronograf/v1.8/administration/upgrading/) for details on upgrading to the latest Chronograf release.
## [Configuring Chronograf 1.8](/chronograf/v1.8/administration/configuration/)
See [Configuring Chronograf 1.8](/chronograf/v1.8/administration/configuration/) to information on starting Chronograf, configuring Chronograf, setting custom default Chronograf configuration options, and enabling security, multi-organization, and multi-user support.
## [Configuration options](/chronograf/v1.8/administration/config-options/)
[Configuration options](/chronograf/v1.8/administration/config-options/) includes details on Chronograf configuration options, including command line settings and environment variables, for the Chronograf service, connections for Kapacitor and InfluxDB, and OAuth 2.0 authentication options.
## [Connecting Chronograf to InfluxDB Enterprise clusters](/chronograf/v1.8/administration/chrono-on-clusters/)
[Connecting Chronograf to InfluxDB Enterprise clusters](/chronograf/v1.8/administration/chrono-on-clusters/) covers details on configuring and using Chronograf to monitor and manage your InfluxDB Enterprise clusters.
## [Creating InfluxDB and Kapacitor connections](/chronograf/v1.8/administration/creating-connections/)
[Creating InfluxDB and Kapacitor connections](/chronograf/v1.8/administration/creating-connections/) includes steps for creating InfluxDB and Kapacitor connections for use with Chronograf.
## [Managing InfluxDB users in Chronograf](/chronograf/v1.8/administration/managing-influxdb-users/)
[Managing InfluxDB users in Chronograf](/chronograf/v1.8/administration/managing-influxdb-users/) covers how to use Chronograf to create and manage InfluxDB users, roles, and permissions.
## [Managing Chronograf security](/chronograf/v1.8/administration/managing-security/)
See [Managing Chronograf security](/chronograf/v1.8/administration/managing-security/) for details on configuring OAuth 2.0 authentication providers, authentication duration, and configuring TLS and HTTPS support.
## [Managing Chronograf organizations](/chronograf/v1.8/administration/managing-organizations/)
[Managing Chronograf organizations](/chronograf/v1.8/administration/managing-organizations/) covers use of the Default organization and creating, managing, and removing Chronograf organizations.
## [Managing Chronograf users](/chronograf/v1.8/administration/managing-chronograf-users/)
See [Managing Chronograf users](/chronograf/v1.8/administration/managing-chronograf-users/) for details on managing Chronograf users and roles, organization-bound users, cross-organization SuperAdmin status, and navigating organizations in the Chronograf user interface.
## [Transitioning from InfluxDB's Web Admin Interface](/chronograf/v1.8/guides/transition-web-admin-interface/)
Versions 1.3+ of InfluxDB OSS and InfluxDB Enterprise no longer support the web admin interface, the built-in user interface for writing and querying data in InfluxDB.
Learn how to use Chronograf as a replacement for the web admin interface.

22
content/chronograf/v1.8/administration/chrono-on-clusters.md Normal file
View File

@ -0,0 +1,22 @@
---
title: Connecting Chronograf to InfluxDB Enterprise clusters
description: Configuration steps for connecting Chronograf to InfluxDB Enterprise clusters and the InfluxData time series platform.
menu:
chronograf_1_8:
name: Connecting Chronograf to InfluxDB Enterprise
weight: 40
parent: Administration
---
The connection details form requires additional information when connecting Chronograf to an [InfluxDB Enterprise cluster](https://docs.influxdata.com/enterprise_influxdb/latest/).
When you enter the InfluxDB HTTP bind address in the `Connection String` input, Chronograf automatically checks if that InfluxDB instance is a data node.
If it is a data node, Chronograf automatically adds the `Meta Service Connection URL` input to the connection details form.
Enter the HTTP bind address of one of your cluster's meta nodes into that input and Chronograf takes care of the rest.
![Cluster connection details](/img/chronograf/v1.8/faq-cluster-connection.png)
Note that the example above assumes that you do not have authentication enabled.
If you have authentication enabled, the form requires username and password information.
For details about monitoring InfluxEnterprise clusters, see [Monitoring InfluxDB Enterprise clusters](/chronograf/latest/guides/monitoring-influxenterprise-clusters).

458
content/chronograf/v1.8/administration/config-options.md Normal file
View File

@ -0,0 +1,458 @@
---
title: Chronograf configuration options
description: Details on configuration settings (command line options and environment variables) for Chronograf services, Kapacitor and InfluxDB connections, and OAuth 2.0 authentication providers.
menu:
chronograf_1_8:
name: Configuration options
weight: 30
parent: Administration
---
Chronograf is configured using the configuration file (/etc/default/chronograf) and environment variables. If you do not uncomment a configuration option, the system uses its default setting. The configuration settings in this document are set to their default settings. For more information, see [Configuration Chronograf](/chronograf/v1.8/administration/configuration/).
* [Usage](#usage)
* [Chronograf service options](#chronograf-service-options)
- [InfluxDB connection options](#influxdb-connection-options)
- [Kapacitor connection options](#kapacitor-connection-options)
- [TLS (Transport Layer Security) options](#tls-transport-layer-security-options)
- [etcd options](#etcd-options)
- [Other service options](#other-service-options)
* [Authentication options](#authentication-options)
* [General authentication options](#general-authentication-options)
* [GitHub-specific OAuth 2.0 authentication options](#github-specific-oauth-2-0-authentication-options)
* [Google-specific OAuth 2.0 authentication options](#google-specific-oauth-2-0-authentication-options)
* [Auth0-specific OAuth 2.0 authentication options](#auth0-specific-oauth-2-0-authentication-options)
* [Heroku-specific OAuth 2.0 authentication options](#heroku-specific-oauth-2-0-authentication-options)
* [Generic OAuth 2.0 authentication options](#generic-oauth-2-0-authentication-options)
## Usage
Start the Chronograf service, and include any options after `chronograf`, where `[OPTIONS]` are options separated by spaces:
```sh
chronograf [OPTIONS]
```
**Linux examples**
- To start `chronograf` without options:
```sh
sudo systemctl start chronograf
```
- To start `chronograf` and set options for develop mode and to disable reporting:
```sh
sudo systemctl start chronograf --develop --reporting-disabled
```
**MacOS X examples**
- To start `chronograf` without options:
```sh
chronograf
```
- To start `chronograf` and add shortcut options for develop mode and to disable reporting:
```sh
chronograf -d -r
```
> ***Note:*** Command line options take precedence over corresponding environment variables.
## Chronograf service options
#### `--host=`
The IP that the `chronograf` service listens on.
Default value: `0.0.0.0`
Example: `--host=0.0.0.0`
Environment variable: `$HOST`
#### `--port=`
The port that the `chronograf` service listens on for insecure connections.
Default: `8888`
Environment variable: `$PORT`
#### `--bolt-path=` | `-b`
The file path to the BoltDB file.
Default value: `./chronograf-v1.db`
Environment variable: `$BOLT_PATH`
#### `--canned-path=` | `-c`
The path to the directory of [canned dashboards](/chronograf/latest/guides/using-precreated-dashboards) files.
Default value: `/usr/share/chronograf/canned`
Environment variable: `$CANNED_PATH`
#### `--resources-path=`
Path to directory of canned dashboards, sources, Kapacitor connections, and organizations.
Default value: `/usr/share/chronograf/resources`
Environment variable: `$RESOURCES_PATH`
#### `--basepath=` | `-p`
The URL path prefix under which all `chronograf` routes will be mounted.
Environment variable: `$BASE_PATH`
#### `--status-feed-url=`
URL of JSON feed to display as a news feed on the client Status page.
Default value: `https://www.influxdata.com/feed/json`
Environment variable: `$STATUS_FEED_URL`
#### `--version` | `-v`
Displays the version of the Chronograf service.
Example:
```sh
$ chronograf -v
2018/01/03 14:11:19 Chronograf 1.4.0.0-rc1-26-gb74ae387 (git: b74ae387)
```
## InfluxDB connection options
> InfluxDB connection details specified via command line when starting Chronograf do not persist when Chronograf is shut down.
> To persist connection details, [include them in a `.src` file](/chronograf/v1.8/administration/creating-connections/#managing-influxdb-connections-using-src-files) located in your [`--resources-path`](#resources-path).
### `--influxdb-url=`
The location of your InfluxDB instance, including `http://`, IP address, and port.
Example: `--influxdb-url=http:///0.0.0.0:8086`
Environment variable: `$INFLUXDB_URL`
### `--influxdb-username=`
The [username] for your InfluxDB instance.
Environment variable: `$INFLUXDB_USERNAME`
### `--influxdb-password=`
The [password] for your InfluxDB instance.
Environment variable: `$INFLUXDB_PASSWORD`
## Kapacitor connection options
> Kapacitor connection details specified via command line when starting Chronograf do not persist when Chronograf is shut down.
> To persist connection details, [include them in a `.kap` file](/chronograf/v1.8/administration/creating-connections/#managing-kapacitor-connections-using-kap-files) located in your [`--resources-path`](#resources-path).
### `--kapacitor-url=`
The location of your Kapacitor instance, including `http://`, IP address, and port.
Example: `--kapacitor-url=http://0.0.0.0:9092`.
Environment variable: `$KAPACITOR_URL`
### `--kapacitor-username=`
The username for your Kapacitor instance.
Environment variable: `$KAPACITOR_USERNAME`
### `--kapacitor-password=`
The password for your Kapacitor instance.
Environment variable: `$KAPACITOR_PASSWORD`
### TLS (Transport Layer Security) options
See [Configuring TLS (Transport Layer Security) and HTTPS](/chronograf/v1.8/administration/managing-security/#configure-tls-transport-layer-security-and-https) for more information.
#### `--cert=`
The file path to PEM-encoded public key certificate.
Environment variable: `$TLS_CERTIFICATE`
#### `--key=`
The file path to private key associated with given certificate.
Environment variable: `$TLS_PRIVATE_KEY`
### etcd options
#### `--etcd-endpoints=` | `-e`
List of etcd endpoints.
Environment variable: `$ETCD_ENDPOINTS`
#### `--etcd-username=`
Username to log into etcd.
Environment variable: `$ETCD_USERNAME`
#### `--etcd-password=`
Password to log into etcd.
Environment variable: `$ETCD_PASSWORD`
#### `--etcd-dial-timeout=`
Total time to wait before timing out while connecting to etcd endpoints.
0 means no timeout.
The default is 1s.
Environment variable: `$ETCD_DIAL_TIMEOUT`
#### `--etcd-request-timeout=`
Total time to wait before timing out an etcd view or update request.
0 means no timeout.
The default is 1s.
Environment variable: `$ETCD_REQUEST_TIMEOUT`
### Other service options
#### `--custom-link <display_name>:<link_address>`
Custom link added to Chronograf User menu options. Useful for providing links to internal company resources for your Chronograf users. Can be used when any OAuth 2.0 authentication is enabled. To add another custom link, repeat the custom link option.
Example: `--custom-link InfluxData:http://www.influxdata.com/`
#### `--reporting-disabled` | `-r`
Disables reporting of usage statistics.
Usage statistics reported once every 24 hours include: `OS`, `arch`, `version`, `cluster_id`, and `uptime`.
Environment variable: `$REPORTING_DISABLED`
#### `--log-level=` | `-l`
Set the logging level.
Valid values: `debug` | `info` | `error`
Default value: `info`
Example: `--log-level=debug`
Environment variable: `$LOG_LEVEL`
#### `--develop` | `-d`
Run the `chronograf` service in developer mode.
#### `--help` | `-h`
Displays the command line help for `chronograf`.
#### `--host-page-disabled` | `-H`
Disables rendering and serving of the Hosts List page (/sources/$sourceId/hosts).
Environment variable: `$HOST_PAGE_DISABLED=true`
## Authentication options
### General authentication options
#### `--token-secret=` | `-t`
The secret for signing tokens.
Environment variable: `$TOKEN_SECRET`
#### `--auth-duration=`
The total duration (in hours) of cookie life for authentication.
Default value: `720h`
Authentication expires on browser close when `--auth-duration=0`.
Environment variable: `$AUTH_DURATION`
#### `--public-url=`
The public URL required to access Chronograf using a web browser. For example, if you access Chronograf using the default URL, the public URL value would be `http://localhost:8888`.
Required for Google OAuth 2.0 authentication. Used for Auth0 and some generic OAuth 2.0 authentication providers.
Environment variable: `$PUBLIC_URL`
### GitHub-specific OAuth 2.0 authentication options
See [Configuring GitHub authentication](/chronograf/v1.8/administration/managing-security/#configure-github-authentication) for more information.
#### `--github-client-id=` | `-i`
The GitHub client ID value for OAuth 2.0 support.
Environment variable: `$GH_CLIENT_ID`
#### `--github-client-secret=` | `-s`
The GitHub Client Secret value for OAuth 2.0 support.
Environment variable: `$GH_CLIENT_SECRET`
#### `--github-organization=` | `-o`
[Optional] Specify a GitHub organization membership required for a user.
Environment variable: `$GH_ORGS`
### Google-specific OAuth 2.0 authentication options
See [Configuring Google authentication](/chronograf/v1.8/administration/managing-security/#configure-google-authentication) for more information.
#### `--google-client-id=`
The Google Client ID value required for OAuth 2.0 support.
Environment variable: `$GOOGLE_CLIENT_ID`
#### `--google-client-secret=`
The Google Client Secret value required for OAuth 2.0 support.
Environment variable: `$GOOGLE_CLIENT_SECRET`
#### `--google-domains=`
[Optional] Restricts authorization to users from specified Google email domains.
Environment variable: `$GOOGLE_DOMAINS`
### Auth0-specific OAuth 2.0 authentication options
See [Configuring Auth0 authentication](/chronograf/v1.8/administration/managing-security/#configure-auth0-authentication) for more information.
#### `--auth0-domain=`
The subdomain of your Auth0 client; available on the configuration page for your Auth0 client.
Example: https://myauth0client.auth0.com
Environment variable: `$AUTH0_DOMAIN`
#### `--auth0-client-id=`
The Auth0 Client ID value required for OAuth 2.0 support.
Environment variable: `$AUTH0_CLIENT_ID`
#### `--auth0-client-secret=`
The Auth0 Client Secret value required for OAuth 2.0 support.
Environment variable: `$AUTH0_CLIENT_SECRET`
#### `--auth0-organizations=`
[Optional] The Auth0 organization membership required to access Chronograf.
Organizations are set using an "organization" key in the user's `app_metadata`.
Lists are comma-separated and are only available when using environment variables.
Environment variable: `$AUTH0_ORGS`
### Heroku-specific OAuth 2.0 authentication options
See [Configuring Heroku authentication](/chronograf/v1.8/administration/managing-security/#configure-heroku-authentication) for more information.
### `--heroku-client-id=`
The Heroku Client ID for OAuth 2.0 support.
**Environment variable:** `$HEROKU_CLIENT_ID`
### `--heroku-secret=`
The Heroku Secret for OAuth 2.0 support.
**Environment variable:** `$HEROKU_SECRET`
### `--heroku-organization=`
The Heroku organization memberships required for access to Chronograf.
Lists are comma-separated.
**Environment variable:** `$HEROKU_ORGS`
### Generic OAuth 2.0 authentication options
See [Configuring Generic authentication](/chronograf/v1.8/administration/managing-security/#configure-generic-authentication) for more information.
#### `--generic-name=`
The generic OAuth 2.0 name presented on the login page.
Environment variable: `$GENERIC_NAME`
#### `--generic-client-id=`
The generic OAuth 2.0 Client ID value.
Can be used for a custom OAuth 2.0 service.
Environment variable: `$GENERIC_CLIENT_ID`
#### `--generic-client-secret=`
The generic OAuth 2.0 Client Secret value.
Environment variable: `$GENERIC_CLIENT_SECRET`
#### `--generic-scopes=`
The scopes requested by provider of web client.
Default value: `user:email`
Environment variable: `$GENERIC_SCOPES`
#### `--generic-domains=`
The email domain required for user email addresses.
Example: `--generic-domains=example.com`
Environment variable: `$GENERIC_DOMAINS`
#### `--generic-auth-url=`
The authorization endpoint URL for the OAuth 2.0 provider.
Environment variable: `$GENERIC_AUTH_URL`
#### `--generic-token-url=`
The token endpoint URL for the OAuth 2.0 provider.
Environment variable: `$GENERIC_TOKEN_URL`
#### `--generic-api-url=`
The URL that returns OpenID UserInfo-compatible information.
Environment variable: `$GENERIC_API_URL`

67
content/chronograf/v1.8/administration/configuration.md Normal file
View File

@ -0,0 +1,67 @@
---
title: Configuring Chronograf
description: Configuration of Chronograf, including custom default settings, security, multiple users, and multiple organizations.
menu:
chronograf_1_8:
name: Configuring
weight: 20
parent: Administration
---
Configure Chronograf by passing command line options when starting the Chronograf service. Or set custom default configuration options in the filesystem so they don’t have to be passed in when starting Chronograf.
- [Start the Chronograf service](#start-the-chronograf-service)
- [Set custom default Chronograf configuration options](#set-custom-default-chronograf-configuration-options)
- [Set up security, organizations, and users](#set-up-security-organizations-and-users)
## Start the Chronograf service
Use one of the following commands to start Chronograf:
- **If you installed Chronograf using an official Debian or RPM package and are running a distro with `systemd`. For example, Ubuntu 15 or later.**
```sh
systemctl start chronograf
```
- **If you installed Chronograf using an official Debian or RPM package:**
```sh
service chronograf start
```
- **mIf you built Chronograf from source:**
```bash
$GOPATH/bin/chronograf
```
## Set custom default Chronograf configuration options
Custom default Chronograf configuration settings can be defined in `/etc/default/chronograf`.
This file consists of key-value pairs. See keys (environment variables) for [Chronograf configuration options](https://docs.influxdata.com/chronograf/v1.8/administration/config-options), and set values for the keys you want to configure.
```conf
HOST=0.0.0.0
PORT=8888
TLS_CERTIFICATE=/path/to/cert.pem
TOKEN_SECRET=MySup3rS3cretT0k3n
LOG_LEVEL=info
```
> **Note:** `/etc/default/chronograf` is only created when installing the `.deb or `.rpm` package.
## Set up security, organizations, and users
To set up security for Chronograf, configure:
* [OAuth 2.0 authentication](/chronograf/v1.8/administration/managing-security/#configure-oauth-2-0)
* [TLS (Transport Layer Security) for HTTPS](/chronograf/v1.8/administration/managing-security/#configure-tls-transport-layer-security-and-https)
After you configure OAuth 2.0 authentication, you can set up multiple organizations, roles, and users. For details, check out the following topics:
* [Managing organizations](/chronograf/v1.8/administration/managing-organizations/)
* [Managing Chronograf users](/chronograf/v1.8/administration/managing-chronograf-users/)
<!-- TODO ## Configuring Chronograf for InfluxDB Enterprise clusters) -->

41
content/chronograf/v1.8/administration/create-high-availability.md Normal file
View File

@ -0,0 +1,41 @@
---
title: Create a Chronograf HA configuration
description: Create a Chronograf high-availability (HA) cluster using etcd.
menu:
chronograf_1_8:
weight: 10
parent: Administration
---
To create a Chronograf high-availability (HA) configuration using an etcd cluster as a shared data store, do the following:
1. [Install and start etcd](#install-and-start-etcd)
2. Set up a load balancer for Chronograf
3. [Start Chronograf](#start-chronograf)
Have an existing Chronograf configuration store that you want to use with a Chronograf HA configuration? Learn how to [migrate your Chrongraf configuration](/chronograf/v1.8/administration/migrate-to-high-availability/) to a shared data store.
## Architecture
<img src="/img/svgs/chronograf-ha-architecture.svg" alt="Chronograf high-availability architecture" style="width:100%;max-width:500px"/>
## Install and start etcd
1. Download the latest etcd release [from GitHub](https://github.com/etcd-io/etcd/releases/).
(For detailed installation instructions specific to your operating system, see [Install and deploy etcd](http://play.etcd.io/install).)
2. Extract the `etcd` binary and place it in your system PATH.
3. Start etcd.
## Start Chronograf
Run the following command to start Chronograf using etcd as the storage layer:
```sh
# Sytnax
chronograf --etcd-endpoints=<etcd-host>
# Example
chronograf --etcd-endpoints=localhost:2379
```
For more information, see [Chronograf etcd configuration options](/chronograf/v1.8/administration/config-options#etcd-options).

238
content/chronograf/v1.8/administration/creating-connections.md Normal file
View File

@ -0,0 +1,238 @@
---
title: Creating InfluxDB and Kapacitor connections
description: Creating and managing InfluxDB and Kapacitor connections for use with Chronograf.
menu:
chronograf_1_8:
name: Creating InfluxDB and Kapacitor connections
weight: 50
parent: Administration
---
Connections to InfluxDB and Kapacitor can be configured through the Chronograf user interface (UI) or with JSON configuration files:
- [Manage InfluxDB connections using the Chronograf UI](#manage-influxdb-connections-using-the-chronograf-ui)
- [Manage InfluxDB connections using .src files](#manage-influxdb-connections-using-src-files)
- [Manage Kapacitor connections using the Chronograf UI](#manage-kapacitor-connections-using-the-chronograf-ui)
- [Manage Kapacitor connections using .kap files](#manage-kapacitor-connections-using-kap-files)
> **Note:** Connection details are stored in Chronograf’s internal database `chronograf-v1.db`. You may administer the internal database when [restoring a Chronograf database](/chronograf/v1.8/administration/restoring-chronograf-db/) or when [migrating a Chronograf configuration from BoltDB to etcd](/chronograf/v1.8/administration/migrate-to-high-availability-etcd/).
## Manage InfluxDB connections using the Chronograf UI
To create an InfluxDB connection in the Chronograf UI:
1. Open Chronograf and click **Configuration** (wrench icon) in the navigation menu.
2. Click **Add Connection**.
![Chronograf connections landing page](/img/chronograf/v1.8/connection-landing-page.png)
3. Enter values for the following fields:
<img src="/img/chronograf/v1.8/influxdb-connection-config.png" style="width:100%; max-width:600px;">
* **Connection URL**: Enter the hostname or IP address of the InfluxDB instance and the port. The field is prefilled with `http://localhost:8086`.
* **Connection Name**: Enter the name for this connection.
* **Username**: Enter the username that will be shared for this connection.
*Required only if [authorization is enabled](/influxdb/latest/administration/authentication_and_authorization/) on the InfluxDB instance to which you're connecting.*
* **Password**: Enter the password.
*Required only if [authorization is enabled](/influxdb/latest/administration/authentication_and_authorization/) on the InfluxDB instance to which you're connecting.*
* **Telegraf Database Name**: This field specifies the database that Chronograf will use for populating different parts of the application, including the Host List page. If none is provided, we will use `autogen`. You will still be able to query any database you have access to in the InfluxDB instance when building dashboards or exploring data.
* **Default Retention Policy**: Enter the name of the default [retention policy](/influxdb/latest/concepts/glossary/#retention-policy-rp). If none is provided, it assumes `autogen`. If you've changed the default retention policy in your InfluxDB instance, you may want to change it here as well.
* **Make this the default connection**: When this option is selected, this InfluxDB connection will be used when Chronograf is launched.
4. Click **Add Connection**
* If the connection is valid, the Dashboards window appears, allowing you to import dashboard templates you can use to display and analyze your data. For details, see [Creating dashboards](/chronograf/latest/guides/create-a-dashboard).
* If the connection cannot be created, the following error message appears:
"Unable to create source: Error contacting source."
If this occurs, ensure all connection credentials are correct and that the InfluxDB instance is running and accessible.
The following dashboards are available:
- Docker
- Kubernetes Node
- Riak
- Consul
- Kubernetes Overview
- Mesos
- IIS
- RabbitMQ
- System
- VMware vSphere Overview
- Apache
- Elastisearch
- InfluxDB
- Memcached
- NSQ
- PostgreSQL
- Consul Telemetry
- HAProxy
- Kubernetes Pod
- NGINX
- Redis
- VMware vSphere VMs
- VMware vSphere Hosts
- PHPfpm
- Win System
- MySQL
- Ping
## Manage InfluxDB connections using .src files
Manually create `.src` files to store InfluxDB connection details.
`.src` files are simple JSON files that contain key-value paired connection details.
The location of `.src` files is defined by the [`--resources-path`](/chronograf/v1.8/administration/config-options/#resources-path)
command line option, which is, by default, the same as the [`--canned-path`](/chronograf/v1.8/administration/config-options/#canned-path-c).
An `.src` files contains the details for a single InfluxDB connection.
Create a new file named `example.src` (the filename is arbitrary) and place it at Chronograf's `resource-path`.
All `.src` files should contain the following:
```json
{
"id": "10000",
"name": "My InfluxDB",
"username": "test",
"password": "test",
"url": "http://localhost:8086",
"type": "influx",
"insecureSkipVerify": false,
"default": true,
"telegraf": "telegraf",
"organization": "example_org"
}
```
#### `id`
A unique, stringified non-negative integer.
Using a 4 or 5 digit number is recommended to avoid interfering with existing datasource IDs.
#### `name`
Any string you want to use as the display name of the source.
#### `username`
Username used to access the InfluxDB server or cluster.
*Only required if [authorization is enabled](/influxdb/latest/administration/authentication_and_authorization/) on the InfluxDB instance to which you're connecting.*
#### `password`
Password used to access the InfluxDB server or cluster.
*Only required if [authorization is enabled](/influxdb/latest/administration/authentication_and_authorization/) on the InfluxDB instance to which you're connecting.*
#### `url`
URL of the InfluxDB server or cluster.
#### `type`
Defines the type or distribution of InfluxDB to which you are connecting.
Below are the following options:
| InfluxDB Distribution | `type` Value |
| --------------------- | ------------ |
| InfluxDB OSS | `influx` |
| InfluxDB Enterprise | `influx-enterprise` |
#### `insecureSkipVerify`
Skips the SSL certificate verification process.
Set to `true` if you are using a self-signed SSL certificate on your InfluxDB server or cluster.
#### `default`
Set to `true` if you want the connection to be the default data connection used upon first login.
#### `telegraf`
The name of the Telegraf database on your InfluxDB server or cluster.
#### `organization`
The ID of the organization you want the data source to be associated with.
### Environment variables in .src files
`.src` files support the use of environment variables to populate InfluxDB connection details.
Environment variables can be loaded using the `"{{ .VARIABLE_KEY }}"` syntax:
```JSON
{
"id": "10000",
"name": "My InfluxDB",
"username": "{{ .INFLUXDB_USER }}",
"password": "{{ .INFLUXDB_PASS }}",
"url": "{{ .INFLUXDB_URL }}",
"type": "influx",
"insecureSkipVerify": false,
"default": true,
"telegraf": "telegraf",
"organization": "example_org"
}
```
## Manage Kapacitor connections using the Chronograf UI
Kapacitor is the data processing component of the TICK stack.
To use Kapacitor in Chronograf, create Kapacitor connections and configure alert endpoints.
To create a Kapacitor connection using the Chronograf UI:
1. Open Chronograf and click **Configuration** (wrench icon) in the navigation menu.
2. Next to an existing [InfluxDB connection](#managing-influxdb-connections-using-the-chronograf-ui), click **Add Kapacitor Connection** if there are no existing Kapacitor connections or select **Add Kapacitor Connection** in the **Kapacitor Connection** dropdown list.
![Add a new Kapacitor connection in Chronograf](/img/chronograf/v1.8/connection-kapacitor.png)
3. In the **Connection Details** section, enter values for the following fields:
<img src="/img/chronograf/v1.8/kapacitor-connection-config.png" style="width:100%; max-width:600px;">
* **Kapacitor URL**: Enter the hostname or IP address of the Kapacitor instance and the port. The field is prefilled with `http://localhost:9092`.
* **Name**: Enter the name for this connection.
* **Username**: Enter the username that will be shared for this connection.
*Only required if [authorization is enabled](/kapacitor/latest/administration/security/#kapacitor-authentication-and-authorization) on the Kapacitor instance or cluster to which you're connecting.*
* **Password**: Enter the password.
*Only required if [authorization is enabled](/kapacitor/latest/administration/security/#kapacitor-authentication-and-authorization) on the Kapacitor instance or cluster to which you're connecting.*
4. Click **Continue**. If the connection is valid, the message "Kapacitor Created! Configuring endpoints is optional." appears. To configure alert endpoints, see [Configuring alert endpoints](/chronograf/v1.8/guides/configuring-alert-endpoints/).
## Manage Kapacitor connections using .kap files
Manually create `.kap` files to store Kapacitor connection details.
`.kap` files are simple JSON files that contain key-value paired connection details.
The location of `.kap` files is defined by the `--resources-path` command line option, which is, by default, the same as the [`--canned-path`](/chronograf/v1.8/administration/config-options/#canned-path-c).
A `.kap` files contains the details for a single InfluxDB connection.
Create a new file named `example.kap` (the filename is arbitrary) and place it at Chronograf's `resource-path`.
All `.kap` files should contain the following:
```json
{
"id": "10000",
"srcID": "10000",
"name": "My Kapacitor",
"url": "http://localhost:9092",
"active": true,
"organization": "example_org"
}
```
#### `id`
A unique, stringified non-negative integer.
Using a 4 or 5 digit number is recommended to avoid interfering with existing datasource IDs.
#### `srcID`
The unique, stringified non-negative integer `id` of the InfluxDB server or cluster with which the Kapacitor service is associated.
#### `name`
Any string you want to use as the display name of the Kapacitor connection.
#### `url`
URL of the Kapacitor server.
#### `active`
If `true`, specifies that this is the Kapacitor connection that should be used when displaying Kapacitor-related information in Chronograf.
#### `organization`
The ID of the organization you want the Kapacitor connection to be associated with.
### Environment variables in .kap files
`.kap` files support the use of environment variables to populate Kapacitor connection details.
Environment variables can be loaded using the `"{{ .VARIABLE_KEY }}"` syntax:
```JSON
{
"id": "10000",
"srcID": "10000",
"name": "My Kapacitor",
"url": "{{ .KAPACITOR_URL }}",
"active": true,
"organization": "example_org"
}
```

52
content/chronograf/v1.8/administration/import-export-dashboards.md Normal file
View File

@ -0,0 +1,52 @@
---
title: Importing and exporting Chronograf dashboards
description: A step-by-step guide that walks through both exporting and importing Chrongraf dashboards.
menu:
chronograf_1_8:
weight: 120
parent: Administration
---
Chronograf makes it easy to both export and import dashboards.
Dashboard exports are simple JSON files that can be shared and imported into other Chronograf instances.
This allows you to recreate robust dashboards without having to manually configure them from the ground up.
[Exporting a dashboard](#exporting-a-dashboard)
[Importing a dashboard](#importing-a-dashboard)
[Required user roles](#required-user-roles)
## Exporting a dashboard
1. Go to your "Dashboards" landing page.
2. Hover over the dashboard you would like to export and click the "Export"
button that appears to the right.
<img src="/img/chronograf/v1.8/dashboard-export.png" alt="Exporting a Chronograf dashboard" style="width:100%;max-width:912px"/>
This downloads a JSON file containing dashboard information including template variables,
cells and cell information such as the query, cell-sizing, color scheme, visualization type, etc.
> No time series data is exported with a dashboard.
> Exports include only dashboard-related information as mentioned above.
## Importing a dashboard
1. On your "Dashboards" landing page, click the "Import Dashboard" button.
2. Either drag and drop or select the JSON export file to import.
3. Click the "Upload Dashboard" button.
The newly imported dashboard will be included in your list of dashboards.
![Importing a Chronograf dashboard](/img/chronograf/v1.8/dashboard-import.gif)
### Reconciling unmatched sources
If the data sources defined in the imported dashboard JSON file do not match any of your local sources,
you will have to reconcile each of the unmatched sources during the import process.
![Reconcile unmatched sources](/img/chronograf/v1.8/dashboard-import-reconcile.png)
## Required user roles
Depending on the role of your user, there are some restrictions on importing and exporting dashboards:
| Task vs Role | Admin | Editor | Viewer |
|------------------|:-----:|:------:|:------:|
| Export Dashboard | ✅ | ✅ | ✅ |
| Import Dashboard | ✅ | ✅ | ❌ |

246
content/chronograf/v1.8/administration/managing-chronograf-users.md Normal file
View File

@ -0,0 +1,246 @@
---
title: Managing Chronograf users
description: Managing Chronograf users and roles, SuperAdmin status, and InfluxDB and Kapacitor users.
menu:
chronograf_1_8:
name: Managing Chronograf users
weight: 90
parent: Administration
---
**On this page**
* [Managing Chronograf users and roles](#managing-chronograf-users-and-roles)
* [Organization-bound users](#organization-bound-users)
* [InfluxDB and Kapacitor users within Chronograf](#influxdb-and-kapacitor-users-within-chronograf)
* [Chronograf-owned resources](#chronograf-owned-resources)
* [Chronograf-accessed resources](#chronograf-accessed-resources)
* [Members](#members-role-member)
* [Viewers](#viewers-role-viewer)
* [Editors](#editors-role-editor)
* [Admins](#admins-role-admin)
* [Cross-organization SuperAdmin status](#cross-organization-superadmin-status)
* [All New Users are SuperAdmins configuration option](#all-new-users-are-superadmins-configuration-option)
* [Creating users](#creating-users)
* [Updating users](#updating-users)
* [Removing users](#removing-users)
* [Navigating organizations](#navigating-organizations)
* [Logging in and logging out](#logging-in-and-logging-out)
* [Switching the current organization](#switching-the-current-organization)
* [Purgatory](#purgatory)
## Managing Chronograf users and roles
> ***Note:*** Support for organizations and user roles is available in Chronograf 1.4 or later. First, OAuth 2.0 authentication must be configured (if it is, you'll see the Chronograf Admin tab on the Admin menu). For more information, see [Managing security] (https://docs.influxdata.com/chronograf/v1.8/administration/managing-security/).
Chronograf includes four organization-bound user roles and one cross-organization SuperAdmin status. In an organization, admins (with the `admin` role) or users with SuperAdmin status can create, update, and assign roles to a user or remove a role assignment.
### Organization-bound users
Chronograf users are assigned one of the following four organization-bound user roles, listed here in order of increasing capabilities:
- [`member`](#members-role-member)
- [`viewer`](#viewers-role-viewer)
- [`editor`](#editors-role-editor)
- [`admin`](#admins-role-admin)
Each of these four roles, described in detail below, have different capabilities for the following Chronograf-owned or Chronograf-accessed resources.
#### InfluxDB and Kapacitor users within Chronograf
Chronograf uses InfluxDB and Kapacitor connections to manage user access control to InfluxDB and Kapacitor resources within Chronograf. The permissions of the InfluxDB and Kapacitor user specified within such a connection determine the capabilities for any Chronograf user with access (i.e., viewers, editors, and administrators) to that connection. Administrators include either an admin (`admin` role) or a user of any role with SuperAdmin status.
> **Note:** Chronograf users are entirely separate from InfluxDB and Kapacitor users.
> The Chronograf user and authentication system applies to the Chronograf user interface.
> InfluxDB and Kapacitor users and their permissions are managed separately.
> [Chronograf connections](/chronograf/v1.8/administration/creating-connections/)
> determine which InfluxDB or Kapacitor users to use when when connecting to each service.
#### Chronograf-owned resources
Chronograf-owned resources include internal resources that are under the full control of Chronograf, including:
- Kapacitor connections
- InfluxDB connections
- Dashboards
- Canned layouts
- Chronograf organizations
- Chronograf users
- Chronograf Status Page content for News Feeds and Getting Started
#### Chronograf-accessed resources
Chronograf-accessed resources include external resources that can be accessed using Chronograf, but are under limited control by Chronograf. Chronograf users with the roles of `viewer`, `editor`, and `admin`, or users with SuperAdmin status, have equal access to these resources:
- InfluxDB databases, users, queries, and time series data (if using InfluxDB Enterprise, InfluxDB roles can be accessed too)
- Kapacitor alerts and alert rules (called tasks in Kapacitor)
#### Members (role:`member`)
Members are Chronograf users who have been added to organizations but do not have any functional capabilities. Members cannot access any resources within an organization and thus effectively cannot use Chronograf. Instead, a member can only access Purgatory, where the user can [switch into organizations](#navigating-organizations) based on assigned roles.
By default, new organizations have a default role of `member`. If the Default organization is Public, then anyone who can authenticate, would become a member, but not be able to use Chronograf until an administrator assigns a different role.
#### Viewers (role:`viewer`)
Viewers are Chronograf users with effectively read-only capabilities for Chronograf-owned resources within their current organization:
- View canned dashboards
- View canned layouts
- View InfluxDB connections
- Switch current InfluxDB connection to other available connections
- Access InfluxDB resources through the current connection
- View the name of the current Kapacitor connection associated with each InfluxDB connection
- Access Kapacitor resources through the current connection
- [Switch into organizations](#navigating-organizations) where the user has a role
For Chronograf-accessed resources, viewers can:
- InfluxDB
- Read and write time series data
- Create, view, edit, and delete databases and retention policies
- Create, view, edit, and delete InfluxDB users
- View and kill queries
- _InfluxDB Enterprise_: Create, view, edit, and delete InfluxDB Enterprise roles
- Kapacitor
- View alerts
- Create, edit, and delete alert rules
#### Editors (role:`editor`)
Editors are Chronograf users with limited capabilities for Chronograf-owned resources within their current organization:
- Create, view, edit, and delete dashboards
- View canned layouts
- Create, view, edit, and delete InfluxDB connections
- Switch current InfluxDB connection to other available connections
- Access InfluxDB resources through the current connection
- Create, view, edit, and delete Kapacitor connections associated with InfluxDB connections
- Switch current Kapacitor connection to other available connections
- Access Kapacitor resources through the current connection
- [Switch into organizations](#navigating-organizations) where the user has a role
For Chronograf-accessed resources, editors can:
- InfluxDB
- Read and write time series data
- Create, view, edit, and delete databases and retention policies
- Create, view, edit, and delete InfluxDB users
- View and kill queries
- _InfluxDB Enterprise_: Create, view, edit, and delete InfluxDB Enterprise roles
- Kapacitor
- View alerts
- Create, edit, and delete alert rules
#### Admins (role:`admin`)
Admins are Chronograf users with all capabilities for the following Chronograf-owned resources within their current organization:
- Create, view, update, and remove Chronograf users
- Create, view, edit, and delete dashboards
- View canned layouts
- Create, view, edit, and delete InfluxDB connections
- Switch current InfluxDB connection to other available connections
- Access InfluxDB resources through the current connection
- Create, view, edit, and delete Kapacitor connections associated with InfluxDB connections
- Switch current Kapacitor connection to other available connections
- Access Kapacitor resources through the current connection
- [Switch into organizations](#navigating-organizations) where the user has a role
For Chronograf-accessed resources, admins can:
- InfluxDB
- Read and write time series data
- Create, view, edit, and delete databases and retention policies
- Create, view, edit, and delete InfluxDB users
- View and kill queries
- _InfluxDB Enterprise_: Create, view, edit, and delete InfluxDB Enterprise roles
- Kapacitor
- View alerts
- Create, edit, and delete alert rules
### Cross-organization SuperAdmin status
SuperAdmin status is a Chronograf status that allows any user, regardless of role, to perform all administrator functions both within organizations, as well as across organizations. A user with SuperAdmin status has _unlimited_ capabilities, including for the following Chronograf-owned resources:
* Create, view, update, and remove organizations
* Create, view, update, and remove users within an organization
* Grant or revoke the SuperAdmin status of another user
* [Switch into any organization](#navigating-organizations)
* Toggle the Public setting of the Default organization
* Toggle the global config setting for [All new users are SuperAdmin](#all-new-users-are-superadmins-configuration-option)
Important SuperAdmin behaviors:
* SuperAdmin status grants any user (whether `member`, `viewer`, `editor`, or `admin`) the full capabilities of admins and the SuperAdmin capabilities listed above.
* When a Chronograf user with SuperAdmin status creates a new organization or switches into an organization where that user has no role, that SuperAdmin user is automatically assigned the `admin` role by default.
* SuperAdmin users cannot revoke their own SuperAdmin status.
* SuperAdmin users are the only ones who can change the SuperAdmin status of other Chronograf users. Regular admins who do not have SuperAdmin status can perform normal operations on SuperAdmin users (create that user within their organization, change roles, and remove them), but they will not see that these users have SuperAdmin status, nor will any of their actions affect the SuperAdmin status of these users.
* If a user has their SuperAdmin status revoked, that user will retain their assigned roles within their organizations.
#### All New Users are SuperAdmins configuration option
By default, the **Config** setting for "**All new users are SuperAdmins"** is **On**. Any user with SuperAdmin status can toggle this under the **Admin > Chronograf > Organizations** tab. If this setting is **On**, any new user (who is created or who authenticates) will_ automatically have SuperAdmin status. If this setting is **Off**, any new user (who is created or who authenticates) will _not_ have SuperAdmin status unless they are explicitly granted it later by another user with SuperAdmin status.
### Creating users
Role required: `admin`
**To create a user:**
1. Open Chronograf in your web browser and select **Admin (crown icon) > Chronograf**.
2. Click the **Users** tab and then click **Create User**.
3. Add the following user information:
* **Username**: Enter the username as provided by the OAuth provider.
* **Role**: Select the Chronograf role.
* **Provider**: Enter the OAuth 2.0 provider to be used for authentication. Valid values are: `github`, `google`, `auth0`, `heroku`, or other names defined in the [`GENERIC_NAME` environment variable](/chronograf/v1.8/administration/config-options#generic-name).
* **Scheme**: Displays `oauth2`, which is the only supported authentication scheme in this release.
4. Click **Save** to finish creating the user.
### Updating users
Role required: `admin`
Only a user's role can be updated. A user's username, provider, and scheme cannot be updated. (Effectively, to "update" a user's username, provider, or scheme, the user must be removed and added again with the desired values.)
**To change a user's role:**
1. Open Chronograf in your web browser and select **Admin (crown icon) > Chronograf**.
2. Click the **Users** tab to display the list of users within the current organization.
3. Select a new role for the user. The update is automatically persisted.
### Removing users
Role required: `admin`
**To remove a user:**
1. Open Chronograf in your web browser and select **Admin (crown icon) > Chronograf**.
2. Click the **Users** tab to display the list of users.
3. Hover your cursor over the user you want to remove and then click **Remove** and **Confirm**.
### Navigating organizations
Chronograf is always used in the context of an organization. When a user logs in to Chronograf, that user will access only the resources owned by their current organization. The only exception to this is that users with SuperAdmin status will also be able to [manage organizations](/chronograf/v1.8/administration/managing-organizations/) in the Chronograf Admin page.
#### Logging in and logging out
A user can log in from the Chronograf homepage using any configured OAuth 2.0 provider.
A user can log out by hovering over the **User (person icon)** in the left navigation bar and clicking **Log out**.
#### Switching the current organization
A user's current organization and role is highlighted in the **Switch Organizations** list, which can be found by hovering over the **User (person icon)** in the left navigation bar.
When a user has a role in more than one organization, that user can switch into any other organization where they have a role by selecting the desired organization in the **Switch Organizations** list.
#### Purgatory
If at any time, a user is a `member` within their current organization and does not have SuperAdmin status, that user will be redirected to a page called Purgatory. There, the user will see their current organization and role, as well as a message to contact an administrator for access.
On the same page, that user will see a list of all of their organizations and roles. The user can switch into any listed organization where their role is `viewer`, `editor`, or `admin` by clicking **Log in** next to the desired organization.
**Note** In the rare case that a user is granted SuperAdmin status while in Purgatory, they will be able to switch into any listed organization, as expected.

309
content/chronograf/v1.8/administration/managing-influxdb-users.md Normal file
View File

@ -0,0 +1,309 @@
---
title: Managing InfluxDB users in Chronograf
description: Using Chronograf to enable authentication and manage InfluxDB OSS and InfluxDB Enterprise users.
aliases:
- /chronograf/v1.8/administration/user-management/
menu:
chronograf_1_8:
name: Managing InfluxDB users
weight: 60
parent: Administration
---
The **Chronograf Admin** provides InfluxDB user management for InfluxDB OSS and InfluxDB Enterprise users.
> ***Note:*** For details on Chronograf user authentication and management, see [Managing security](/chronograf/latest/administration/managing-security/).
**On this page:**
* [Enabling authentication](#enabling-authentication)
* [InfluxDB OSS user management](#influxdb-oss-user-management)
* [InfluxDB Enterprise user management](#influxdb-enterprise-user-management)
## Enabling authentication
Follow the steps below to enable authentication.
The steps are the same for InfluxDB OSS instances and InfluxEnterprise clusters.
> ***InfluxEnterprise clusters:***
> Repeat the first three steps for each data node in a cluster.
### Step 1: Enable authentication.
Enable authentication in the InfluxDB configuration file.
For most Linux installations, the configuration file is located in `/etc/influxdb/influxdb.conf`.
In the `[http]` section of the InfluxDB configuration file (`influxdb.conf`), uncomment the `auth-enabled` option and set it to `true`, as shown here:
```
[http]
# Determines whether HTTP endpoint is enabled.
# enabled = true
# The bind address used by the HTTP service.
# bind-address = ":8086"
# Determines whether HTTP authentication is enabled.
auth-enabled = true #
```
### Step 2: Restart the InfluxDB service.
Restart the InfluxDB service for your configuration changes to take effect:
```
~# sudo systemctl restart influxdb
```
### Step 3: Create an admin user.
Because authentication is enabled, you need to create an [admin user](/influxdb/latest/administration/authentication_and_authorization/#user-types-and-privileges) before you can do anything else in the database.
Run the `curl` command below to create an admin user, replacing:
* `localhost` with the IP or hostname of your InfluxDB OSS instance or one of your InfluxEnterprise data nodes
* `chronothan` with your own username
* `supersecret` with your own password (note that the password requires single quotes)
```
~# curl -XPOST "http://localhost:8086/query" --data-urlencode "q=CREATE USER chronothan WITH PASSWORD 'supersecret' WITH ALL PRIVILEGES"
```
A successful `CREATE USER` query returns a blank result:
```
{"results":[{"statement_id":0}]} <--- Success!
```
### Step 4: Edit the InfluxDB source in Chronograf.
If you've already [connected your database to Chronograf](chronograf/latest/introduction/installation#connect-chronograf-to-your-influxdb-instance-or-influxdb-enterprise-cluster), update the connection configuration in Chronograf with your new username and password.
Edit existing InfluxDB database sources by navigating to the Chronograf configuration page and clicking on the name of the source.
## InfluxDB OSS User Management
On the **Chronograf Admin** page:
* View, create, and delete admin and non-admin users
* Change user passwords
* Assign admin and remove admin permissions to or from a user
![InfluxDB OSS user management](/img/chronograf/chrono-admin-usermanagement-oss.png)
InfluxDB users are either admin users or non-admin users.
See InfluxDB's [authentication and authorization](/influxdb/latest/administration/authentication_and_authorization/#user-types-and-privileges) documentation for more information about those user types.
> ***Note:*** Note that Chronograf currently does not support assigning InfluxDB database `READ`or `WRITE` access to non-admin users.
>This is a known issue.
>
>As a workaround, grant `READ`, `WRITE`, or `ALL` (`READ` and `WRITE`) permissions to non-admin users with the following curl commands, replacing anything inside `< >` with your own values:
#### Grant `READ` permission:
```
~# curl -XPOST "http://<InfluxDB-IP>:8086/query?u=<username>&p=<password>" --data-urlencode "q=GRANT READ ON <database-name> TO <non-admin-username>"
```
#### Grant `WRITE` permission:
```
~# curl -XPOST "http://<InfluxDB-IP>:8086/query?u=<username>&p=<password>" --data-urlencode "q=GRANT WRITE ON <database-name> TO <non-admin-username>"
```
#### Grant `ALL` permission:
```
~# curl -XPOST "http://<InfluxDB-IP>:8086/query?u=<username>&p=<password>" --data-urlencode "q=GRANT ALL ON <database-name> TO <non-admin-username>"
```
In all cases, a successful `GRANT` query returns a blank result:
```
{"results":[{"statement_id":0}]} <--- Success!
```
Remove `READ`, `WRITE`, or `ALL` permissions from non-admin users by replacing `GRANT` with `REVOKE` in the curl commands above.
## InfluxDB Enterprise user management
On the `Admin` page:
* View, create, and delete users
* Change user passwords
* Assign and remove permissions to or from a user
* Create, edit, and delete roles
* Assign and remove roles to or from a user
![InfluxDB Enterprise user management](/img/chronograf/chrono-admin-usermanagement-cluster.png)
### User types
Admin users have the following permissions by default:
* [CreateDatabase](#createdatabase)
* [CreateUserAndRole](#createuserandrole)
* [DropData](#dropdata)
* [DropDatabase](#dropdatabase)
* [ManageContinuousQuery](#managecontinuousquery)
* [ManageQuery](#managequery)
* [ManageShard](#manageshard)
* [ManageSubscription](#managesubscription)
* [Monitor](#monitor)
* [ReadData](#readdata)
* [WriteData](#writedata)
Non-admin users have no permissions by default.
Assign permissions and roles to both admin and non-admin users.
### Permissions
#### AddRemoveNode
Permission to add or remove nodes from a cluster.
**Relevant `influxd-ctl` arguments**:
[`add-data`](/enterprise_influxdb/latest/administration/cluster-commands/#add-data),
[`add-meta`](/enterprise_influxdb/latest/administration/cluster-commands/#add-meta),
[`join`](/enterprise_influxdb/latest/administration/cluster-commands/#join),
[`remove-data`](/enterprise_influxdb/latest/administration/cluster-commands/#remove-data),
[`remove-meta`](/enterprise_influxdb/latest/administration/cluster-commands/#remove-meta), and
[`leave`](/enterprise_influxdb/latest/administration/cluster-commands/#leave)
**Pages in Chronograf that require this permission**: NA
#### CopyShard
Permission to copy shards.
**Relevant `influxd-ctl` arguments**:
[`copy-shard`](/enterprise_influxdb/latest/administration/cluster-commands/#copy-shard)
**Pages in Chronograf that require this permission**: NA
#### CreateDatabase
Permission to create databases, create [retention policies](/influxdb/latest/concepts/glossary/#retention-policy-rp), alter retention policies, and view retention policies.
**Relevant InfluxQL queries**:
[`CREATE DATABASE`](/influxdb/latest/query_language/database_management/#create-database),
[`CREATE RETENTION POLICY`](/influxdb/latest/query_language/database_management/#create-retention-policies-with-create-retention-policy),
[`ALTER RETENTION POLICY`](/influxdb/latest/query_language/database_management/#modify-retention-policies-with-alter-retention-policy), and
[`SHOW RETENTION POLICIES`](/influxdb/latest/query_language/schema_exploration/#show-retention-policies)
**Pages in Chronograf that require this permission**: Dashboards, Data Explorer, and Databases on the Admin page
#### CreateUserAndRole
Permission to manage users and roles; create users, drop users, grant admin status to users, grant permissions to users, revoke admin status from users, revoke permissions from users, change user passwords, view user permissions, and view users and their admin status.
**Relevant InfluxQL queries**:
[`CREATE USER`](/influxdb/latest/administration/authentication_and_authorization/#user-management-commands),
[`DROP USER`](/influxdb/latest/administration/authentication_and_authorization/#general-admin-and-non-admin-user-management),
[`GRANT ALL PRIVILEGES`](/influxdb/latest/administration/authentication_and_authorization/#user-management-commands),
[`GRANT [READ,WRITE,ALL]`](/influxdb/latest/administration/authentication_and_authorization/#non-admin-user-management),
[`REVOKE ALL PRIVILEGES`](/influxdb/latest/administration/authentication_and_authorization/#user-management-commands),
[`REVOKE [READ,WRITE,ALL]`](/influxdb/latest/administration/authentication_and_authorization/#non-admin-user-management),
[`SET PASSWORD`](/influxdb/latest/administration/authentication_and_authorization/#general-admin-and-non-admin-user-management),
[`SHOW GRANTS`](/influxdb/latest/administration/authentication_and_authorization/#non-admin-user-management), and
[`SHOW USERS`](/influxdb/latest/administration/authentication_and_authorization/#user-management-commands)
**Pages in Chronograf that require this permission**: Data Explorer, Dashboards, Users and Roles on the Admin page
#### DropData
Permission to drop data, in particular [series](/influxdb/latest/concepts/glossary/#series) and [measurements](/influxdb/latest/concepts/glossary/#measurement).
**Relevant InfluxQL queries**:
[`DROP SERIES`](/influxdb/latest/query_language/database_management/#drop-series-from-the-index-with-drop-series),
[`DELETE`](/influxdb/latest/query_language/database_management/#delete-series-with-delete), and
[`DROP MEASUREMENT`](/influxdb/latest/query_language/database_management/#delete-measurements-with-drop-measurement)
**Pages in Chronograf that require this permission**: NA
#### DropDatabase
Permission to drop databases and retention policies.
**Relevant InfluxQL queries**:
[`DROP DATABASE`](/influxdb/latest/query_language/database_management/#delete-a-database-with-drop-database) and
[`DROP RETENTION POLICY`](/influxdb/latest/query_language/database_management/#delete-retention-policies-with-drop-retention-policy)
**Pages in Chronograf that require this permission**: Data Explorer, Dashboards, Databases on the Admin page
#### KapacitorAPI
Permission to access the API for InfluxKapacitor Enterprise.
This does not include configuration-related API calls.
**Pages in Chronograf that require this permission**: NA
#### KapacitorConfigAPI
Permission to access the configuration-related API calls for InfluxKapacitor Enterprise.
**Pages in Chronograf that require this permission**: NA
#### ManageContinuousQuery
Permission to create, drop, and view [continuous queries](/influxdb/latest/concepts/glossary/#continuous-query-cq).
**Relevant InfluxQL queries**:
[`CreateContinuousQueryStatement`](/influxdb/latest/query_language/continuous_queries/),
[`DropContinuousQueryStatement`](/influxdb/latest/query_language/continuous_queries/#deleting-continuous-queries), and
[`ShowContinuousQueriesStatement`](/influxdb/latest/query_language/continuous_queries/#listing-continuous-queries)
**Pages in Chronograf that require this permission**: Data Explorer, Dashboards
#### ManageQuery
Permission to view and kill queries.
**Relevant InfluxQL queries**:
[`SHOW QUERIES`](/influxdb/latest/troubleshooting/query_management/#list-currently-running-queries-with-show-queries) and
[`KILL QUERY`](/influxdb/latest/troubleshooting/query_management/#stop-currently-running-queries-with-kill-query)
**Pages in Chronograf that require this permission**: Queries on the Admin page
#### ManageShard
Permission to copy, delete, and view [shards](/influxdb/latest/concepts/glossary/#shard).
**Relevant InfluxQL queries**:
[`DropShardStatement`](/influxdb/latest/query_language/database_management/#delete-a-shard-with-drop-shard),
[`ShowShardGroupsStatement`](/influxdb/latest/query_language/spec/#show-shard-groups), and
[`ShowShardsStatement`](/influxdb/latest/query_language/spec/#show-shards)
**Pages in Chronograf that require this permission**: NA
#### ManageSubscription
Permission to create, drop, and view [subscriptions](/influxdb/latest/concepts/glossary/#subscription).
**Relevant InfluxQL queries**:
[`CREATE SUBSCRIPTION`](/influxdb/latest/query_language/spec/#create-subscription),
[`DROP SUBSCRIPTION`](/influxdb/latest/query_language/spec/#drop-subscription), and
[`SHOW SUBSCRIPTIONS`](/influxdb/latest/query_language/spec/#show-subscriptions)
**Pages in Chronograf that require this permission**: Alerting
#### Monitor
Permission to view cluster statistics and diagnostics.
**Relevant InfluxQL queries**:
[`SHOW DIAGNOSTICS`](/influxdb/administration/server_monitoring/#show-diagnostics) and
[`SHOW STATS`](/influxdb/administration/server_monitoring/#show-stats)
**Pages in Chronograf that require this permission**: Data Explorer, Dashboards
#### ReadData
Permission to read data.
**Relevant InfluxQL queries**:
[`SHOW FIELD KEYS`](/influxdb/latest/query_language/schema_exploration/#show-field-keys),
[`SHOW MEASUREMENTS`](/influxdb/latest/query_language/schema_exploration/#show-measurements),
[`SHOW SERIES`](/influxdb/latest/query_language/schema_exploration/#show-series),
[`SHOW TAG KEYS`](/influxdb/latest/query_language/schema_exploration/#show-tag-keys),
[`SHOW TAG VALUES`](/influxdb/latest/query_language/schema_exploration/#show-tag-values), and
[`SHOW RETENTION POLICIES`](/influxdb/latest/query_language/schema_exploration/#show-retention-policies)
**Pages in Chronograf that require this permission**: Admin, Alerting, Dashboards, Data Explorer, Host List
#### WriteData
Permission to write data.
**Relevant InfluxQL queries**: NA
**Pages in Chronograf that require this permission**: NA
### Roles
Roles are groups of permissions.
Assign roles to one or more users.
For example, the image below contains three roles: `CREATOR`, `DESTROYER`, and `POWERLESS`.
`CREATOR` includes two permissions (`CreateDatbase` and `CreateUserAndRole`) and is assigned to one user (`chrononut`).
`DESTROYER` also includes two permissions (`DropDatabase` and `DropData`) and is assigned to two users (`chrononut` and `chronelda`).
![InfluxDB OSS user management](/img/chronograf/chrono-admin-usermanagement-roles.png)

114
content/chronograf/v1.8/administration/managing-organizations.md Normal file
View File

@ -0,0 +1,114 @@
---
title: Managing Chronograf organizations
description: "Managing multiple organizations or groups: creating, configuring, mapping, and removing organizations."
menu:
chronograf_1_8:
name: Managing Chronograf organizations
weight: 80
parent: Administration
---
**On this page:**
* [About Chronograf organizations](#about-chronograf-organizations)
* [Using the Default organization](#using-the-default-organization)
* [Creating organizations](#creating-organizations)
* [Configuring organizations](#configuring-organizations)
* [Mapping organizations](#mapping-organizations)
* [Removing organizations](#removing-organizations)
## About Chronograf organizations
> ***Note:*** Support for organizations and user roles is available in Chronograf 1.4 or later.
First, OAuth 2.0 authentication must be configured (if it is, you'll see the Chronograf Admin tab on the Admin menu).
For more information, see [managing security](/chronograf/v1.8/administration/managing-security/).
For information about the new user roles and SuperAdmin status, see [Managing Chronograf users](https://docs.influxdata.com/chronograf/v1.8/administration/managing-chronograf-users/).
A Chronograf organization is a collection of Chronograf users who share common Chronograf-owned resources, including dashboards, InfluxDB connections, and Kapacitor connections. Organizations can be used to represent companies, functional units, projects, or teams. Chronograf users can be members of multiple organizations.
> ***Note:*** Only users with SuperAdmin status can manage organizations. Admins, editors, viewers, and members cannot manage organizations unless they have SuperAdmin status.
## Using the Default organization
>***Note:*** The Default organization can be used to support Chronograf as configured in versions earlier than 1.4.
> Upon upgrading, any Chronograf resources that existed prior to 1.4 automatically become owned by the Default organization.
Upon installation, the Default organization is ready for use and allows Chronograf to be used as-is.
## Creating organizations
Your company, organizational units, teams, and projects may require the creation of additional organizations, beyond the Default organization. Additional organizations can be created as described below.
**To create an organization:**
**Required status:** SuperAdmin
1) In the Chronograf navigation bar, click **Admin** (crown icon) > **Chronograf** to open the **Chronograf Admin** page.
2) In the **All Orgs** tab, click **Create Organization**.
3) Under **Name**, click on **"Untitled Organization"** and enter the new organization name.
4) Under **Default Role**, select the default role for new users within that organization. Valid options include `member` (default), `viewer`, `editor`, and `admin`.
5) Click **Save**.
## Configuring organizations
**Required status:** SuperAdmin
You can configure existing and new organizations in the **Organizations** tab of the **Chronograf Admin** page as follows:
* **Name**: The name of the organization. Click on the organization name to change it.
> ***Note:*** You can change the Default organization's name, but that organization will always be the default organization.
* **Public**: [Default organization only] Indicates whether a user can authenticate without being explicitly added to the organization. When **Public** is toggled to **Off**, new users cannot authenticate into your Chronograf instance unless they have been explicitly added to the organization by an administrator.
> ***Note:*** All organizations other than the Default organization require users to be explicitly added by an administrator.
* **Default Role**: The role granted to new users by default when added to an organization. Valid options are `member` (default), `viewer`, `editor`, and `admin`.
See the following pages for more information about managing Chronograf users and security:
* [Managing Chronograf users](/chronograf/v1.8/administration/managing-chronograf-users/)
* [Managing security](/chronograf/v1.8/administration/managing-security/)
## Mapping organizations
**To create an organization mapping:**
**Required status:** SuperAdmin
1) In the Chronograf navigation bar, select **Admin** (crown icon) > **Chronograf** to open the **Chronograf Admin** page.
2) Click the **Org Mappings** tab to view a list of organization mappings.
3) To add an organization mapping, click the **Create Mapping** button. A new row is added to the listing.
4) In the new row, enter the following:
- **Scheme**, select `oauth2`.
- **Provider**: Enter the provider. Valid values include `Google` and `GitHub`.
- **Provider Org**: [Optional] Enter the email domain(s) you want to accept.
- **Organization**: Select the organization that can use this authentication provider.
**To remove an organization mapping:**
**Required status:** SuperAdmin
1) In the Chronograf navigation bar, select **Admin** (crown icon) > **Chronograf** to open the **Chronograf Admin** page.
2) Click the **Org Mappings** tab to view a list of organization mappings.
3) To remove an organization mapping, click the **Delete** button at the end of the mapping row you want to remove, and then confirm the action.
## Removing organizations
When an organization is removed:
* Users within that organization are removed from that organization and will be logged out of the application.
* All users with roles in that organization are updated to no longer have a role in that organization
* All resources owned by that organization are deleted.
**To remove an organization:**
**Required status:** SuperAdmin
1) In the navigation bar of the Chronograf application, select **Admin** (crown icon) > **Chronograf** to open the **Chronograf Admin** page.
2) Click the **All Orgs** tab to view a list of organizations.
3) To the right of the the organization that you want to remove, click the **Remove** button (trashcan icon) and then confirm by clicking the **Save** button.

509
content/chronograf/v1.8/administration/managing-security.md Normal file
View File

@ -0,0 +1,509 @@
---
title: Managing Chronograf security
description: Managing Chronograf security using authentication and authorization with OAuth 2.0 providers (GitHub, Google, Heroku, Okta, and generic). Also covers TLS and HTTPS setup.
aliases: /chronograf/v1.8/administration/security-best-practices/
menu:
chronograf_1_8:
name: Managing Chronograf security
weight: 70
parent: Administration
---
To enhance security, configure Chronograf to authenticate and authorize with [OAuth 2.0](https://oauth.net/) and use TLS/HTTPS.
* [Configure OAuth 2.0](#configure-oauth-2-0)
1. [Generate a Token Secret](#generate-a-token-secret)
2. [Set configurations for your OAuth provider](#set-configurations-for-your-oauth-provider)
3. [Configure authentication duration](#configure-authentication-duration)
* [Configure TLS (Transport Layer Security) and HTTPS](#configure-tls-transport-layer-security-and-https)
## Configure OAuth 2.0
> After configuring OAuth 2.0, the Chronograf Admin tab becomes visible.
> You can then set up [multiple organizations](https://docs.influxdata.com/chronograf/latest/administration/managing-organizations/)
> and [users](https://docs.influxdata.com/chronograf/latest/administration/managing-influxdb-users/).
Configure Chronograf to use an OAuth 2.0 provider and JWT (JSON Web Token) to authenticate users and enable role-based access controls.
(For more details on OAuth and JWT, see [RFC 6749](https://tools.ietf.org/html/rfc6749) and [RFC 7519](https://tools.ietf.org/html/rfc7519).)
### Generate a Token Secret
To configure any of the supported OAuth 2.0 providers to work with Chronograf,
you must configure the `TOKEN_SECRET` environment variable (or command line option).
Chronograf will use this secret to generate the JWT Signature for all access tokens.
1. Generate a secret, high-entropy pseudo-random string.
> For example, to do this with OpenSSL, run this command:
> ```
> openssl rand -base64 256 | tr -d '\n'
> ```
2. Set the environment variable:
```
TOKEN_SECRET=<mysecret>
```
> ***InfluxEnterprise clusters:*** If you are running multiple Chronograf servers in a high availability configuration,
> set the `TOKEN_SECRET` environment variable on each server to ensure that users can stay logged in.
### JWKS Signature Verification (optional)
If the OAuth provider implements OpenID Connect with RS256 signatures, you need to enable this feature with the `USE_ID_TOKEN` variable
and provide a JSON Web Key Set (JWKS) document (holding the certificate chain) to validate the RSA signatures against.
This certificate chain is regularly rolled over (when the certificates expire), so it is fetched from the `JWKS_URL` on demand.
**Example:**
```sh
export USE_ID_TOKEN=true
export JWKS_URL=https://example.com/adfs/discovery/keys
```
### Set configurations for your OAuth provider
To enable OAuth 2.0 authorization and authentication in Chronograf,
you must set configuration options that are specific for the OAuth 2.0 authentication provider you want to use.
Configuration steps for the following supported authentication providers are provided in these sections below:
* [GitHub](#configure-github-authentication)
* [Google](#configure-google-authentication)
* [Auth0](#configure-auth0-authentication)
* [Heroku](#configure-heroku-authentication)
* [Okta](#configure-okta-authentication)
* [Gitlab](#configure-gitlab-authentication)
* [Azure Active Directory](#configure-azure-active-directory-authentication)
* [Configure Chronograf to use any OAuth 2.0 provider](#configure-chronograf-to-use-any-oauth-2-0-provider)
> If you haven't already, you must first [generate a token secret](#generate-a-token-secret) before proceeding.
---
#### Configure GitHub authentication
1. Follow the steps to [Register a new OAuth application](https://github.com/settings/applications/new)
on GitHub to obtain your Client ID and Client Secret.
On the GitHub application registration page, enter the following values:
- **Homepage URL**: the full Chronograf server name and port.
For example, to run the application locally with default settings, set the this URL to `http://localhost:8888`.
- **Authorization callback URL**: the **Homepage URL** plus the callback URL path `/oauth/github/callback`
(for example, `http://localhost:8888/oauth/github/callback`).
2. Set the Chronograf environment variables with the credentials provided by GitHub:
```sh
export GH_CLIENT_ID=<client-id-from-github>
export GH_CLIENT_SECRET=<client-secret-from-github>
```
3. If you haven't already, set the Chronograf environment with your token secret:
```sh
export TOKEN_SECRET=Super5uperUdn3verGu355!
```
Alternatively, set environment variables using the equivalent command line options:
* [`--github-client-id=`](/chronograf/v1.8/administration/config-options/#github-client-id-i)
* [`--github-client-secret=`](/chronograf/v1.8/administration/config-options/#github-client-secret-s)
* [`--token_secret=`](/chronograf/v1.8/administration/config-options/#token-secret-t)
For details on the command line options and environment variables, see [GitHub OAuth 2.0 authentication options](/chronograf/v1.8/administration/config-options#github-specific-oauth-2-0-authentication-options).
##### GitHub organizations (optional)
To require GitHub organization membership for authenticating users, set the `GH_ORGS` environment variable with the name of your organization.
```sh
export GH_ORGS=biffs-gang
```
If the user is not a member of the specified GitHub organization, then the user will not be granted access.
To support multiple organizations, use a comma-delimited list.
```sh
export GH_ORGS=hill-valley-preservation-sociey,the-pinheads
```
> When logging in for the first time, make sure to grant access to the organization you configured.
> The OAuth application can only see membership in organizations it has been granted access to.
##### Example GitHub OAuth configuration
```bash
# GitHub Client ID
export GH_CLIENT_ID=b339dd4fddd95abec9aa
# GitHub Client Secret
export GH_CLIENT_SECRET=260041897d3252c146ece6b46ba39bc1e54416dc
# Secret used to generate JWT tokens
export TOKEN_SECRET=Super5uperUdn3verGu355!
# Restrict to specific GitHub organizations
export GH_ORGS=biffs-gang
```
#### Configure Google authentication
1. Follow the steps in [Obtain OAuth 2.0 credentials](https://developers.google.com/identity/protocols/OpenIDConnect#getcredentials)
to obtain the required Google OAuth 2.0 credentials, including a Google Client ID and Client Secret, by
2. Verify that Chronograf is publicly accessible using a fully-qualified domain name so that Google can properly redirect users back to the application.
3. Set the Chronograf environment variables for the Google OAuth 2.0 credentials and **Public URL** used to access Chronograf:
```sh
export GOOGLE_CLIENT_ID=812760930421-kj6rnscmlbv49pmkgr1jq5autblc49kr.apps.googleusercontent.com
export GOOGLE_CLIENT_SECRET=wwo0m29iLirM6LzHJWE84GRD
export PUBLIC_URL=http://localhost:8888
```
4. If you haven't already, set the Chronograf environment with your token secret:
```sh
export TOKEN_SECRET=Super5uperUdn3verGu355!
```
Alternatively, the environment variables discussed above can be set using their corresponding command line options:
* [`--google-client-id=`](/chronograf/v1.8/administration/config-options/#google-client-id)
* [`--google-client-secret=`](/chronograf/v1.8/administration/config-options/#google-client-secret)
* [`--public-url=`](/chronograf/v1.8/administration/config-options/#public-url)
* [`--token_secret=`](/chronograf/v1.8/administration/config-options/#token-secret-t)
For details on Chronograf command line options and environment variables, see [Google OAuth 2.0 authentication options](/chronograf/v1.8/administration/config-options#google-specific-oauth-2-0-authentication-options).
##### Optional Google domains
Configure Google authentication to restrict access to Chronograf to specific domains.
Set the `GOOGLE_DOMAINS` environment variable or the [`--google-domains`](/chronograf/v1.8/administration/config-options/#google-domains) command line option.
Separate multiple domains using commas.
For example, to permit access only from `biffspleasurepalace.com` and `savetheclocktower.com`, set the environment variable as follows:
```sh
export GOOGLE_DOMAINS=biffspleasurepalance.com,savetheclocktower.com
```
#### Configure Auth0 authentication
See [OAuth 2.0](https://auth0.com/docs/protocols/oauth2) for details about the Auth0 implementation.
1. Set up your Auth0 account to obtain the necessary credentials.
1. From the Auth0 user dashboard, click **Create Application**.
2. Choose **Regular Web Applications** as the type of application and click **Create**.
3. In the **Settings** tab, set **Token Endpoint Authentication** to **None**.
4. Set **Allowed Callback URLs** to `https://www.example.com/oauth/auth0/callback` (substituting `example.com` with the [`PUBLIC_URL`](/chronograf/v1.8/administration/config-options/#general-authentication-options) of your Chronograf instance)
5. Set **Allowed Logout URLs** to `https://www.example.com` (substituting `example.com` with the [`PUBLIC_URL`](/chronograf/v1.8/administration/config-options/#general-authentication-options) of your Chronograf instance)
<!-- ["OIDC Conformant"](https://auth0.com/docs/api-auth/intro#how-to-use-the-new-flows). -->
2. Set the Chronograf environment variables based on your Auth0 client credentials:
* `AUTH0_DOMAIN` (Auth0 domain)
* `AUTH0_CLIENT_ID` (Auth0 Client ID)
* `AUTH0_CLIENT_SECRET` (Auth0 client Secret)
* `PUBLIC_URL` (Public URL, used in callback URL and logout URL above)
3. If you haven't already, set the Chronograf environment with your token secret:
```sh
export TOKEN_SECRET=Super5uperUdn3verGu355!
```
Alternatively, the environment variables discussed above can be set using their corresponding command line options:
* [`--auth0-domain`](/chronograf/v1.8/administration/config-options/#auth0-specific-oauth-2-0-authentication-options)
* [`--auth0-client-id`](/chronograf/v1.8/administration/config-options/#auth0-specific-oauth-2-0-authentication-options)
* [`--auth0-client-secret`](/chronograf/v1.8/administration/config-options/#auth0-specific-oauth-2-0-authentication-options)
* [`--public-url`](/chronograf/v1.8/administration/config-options/#general-authentication-options)
##### Auth0 organizations (optional)
Auth0 can be customized to the operator's requirements, so it has no official concept of an "organization."
Organizations are supported in Chronograf using a lightweight `app_metadata` key that can be inserted into Auth0 user profiles automatically or manually.
To assign a user to an organization, add an `organization` key to the user `app_metadata` field with the value corresponding to the user's organization.
For example, you can assign the user Marty McFly to the "time-travelers" organization by setting `app_metadata` to `{"organization": "time-travelers"}`.
This can be done either manually by an operator or automatically through the use of an [Auth0 Rule](https://auth0.com/docs/rules) or a [pre-user registration Auth0 Hook](https://auth0.com/docs/hooks/concepts/pre-user-registration-extensibility-point).
Next, you will need to set the Chronograf [`AUTH0_ORGS`](/chronograf/v1.8/administration/config-options/#auth0-organizations) environment variable to a comma-separated list of the allowed organizations.
For example, if you have one group of users with an `organization` key set to `biffs-gang` and another group with an `organization` key set to `time-travelers`, you can permit access to both with this environment variable: `AUTH0_ORGS=biffs-gang,time-travelers`.
An `--auth0-organizations` command line option is also available, but it is limited to a single organization and does not accept a comma-separated list like its environment variable equivalent.
#### Configure Heroku authentication
1. Obtain a client ID and application secret for Heroku by following the guide posted [here](https://devcenter.heroku.com/articles/oauth#register-client).
2. Set the Chronograf environment variables based on your Heroku client credentials:
```sh
export HEROKU_CLIENT_ID=<client-id-from-heroku>
export HEROKU_SECRET=<client-secret-from-heroku>
```
3. If you haven't already, set the Chronograf environment with your token secret:
```sh
export TOKEN_SECRET=Super5uperUdn3verGu355!
```
##### Heroku organizations (optional)
To restrict access to members of specific Heroku organizations,
use the `HEROKU_ORGS` environment variable (or associated command line option).
Multiple values must be comma-separated.
For example, to permit access from the `hill-valley-preservation-society` organization and `the-pinheads` organization,
use the following environment variable:
```sh
export HEROKU_ORGS=hill-valley-preservation-sociey,the-pinheads
```
#### Configure Okta authentication
1. Create an Okta web application by following the steps in the Okta documentation: [Implement the Authorization Code Flow](https://developer.okta.com/docs/guides/implement-auth-code/overview/).
1. In the **General Settings** section, find the **Allowed grant types** listing and select
only the **Client acting on behalf of a user:** **Authorization Code** option.
2. In the **LOGIN** section, set the **Login redirect URIs* and **Initiate login URI** to `http://localhost:8888/oauth/okta/callback` (the default callback URL for Chronograf).
2. Set the following Chronograf environment variables:
```bash
GENERIC_NAME=okta
# The client ID is provided in the "Client Credentials" section of the Okta dashboard.
GENERIC_CLIENT_ID=<okta_client_ID>
# The client secret is in the "Client Credentials" section of the Okta dashboard.
GENERIC_CLIENT_SECRET=<okta_client_secret>
GENERIC_AUTH_URL=https://dev-553212.oktapreview.com/oauth2/default/v1/authorize
GENERIC_TOKEN_URL=https://dev-553212.oktapreview.com/oauth2/default/v1/token
GENERIC_API_URL=https://dev-553212.oktapreview.com/oauth2/default/v1/userinfo
PUBLIC_URL=http://localhost:8888
TOKEN_SECRET=secretsecretsecret
GENERIC_SCOPES=openid,profile,email
```
3. If you haven't already, set the Chronograf environment with your token secret:
```sh
export TOKEN_SECRET=Super5uperUdn3verGu355!
```
#### Configure GitLab authentication
1. In your GitLab profile, [create a new OAuth2 authentication service](https://docs.gitlab.com/ee/integration/oauth_provider.html#adding-an-application-through-the-profile).
1. Provide a name for your application, then enter your publicly accessible Chronograf URL with the `/oauth/gitlab/callback` path as your GitLab **callback URL**.
(For example, `http://<your_chronograf_server>:8888/oauth/gitlab/callback`.)
2. Click **Submit** to save the service details.
3. Make sure your application has **openid** and **read_user** scopes.
2. Copy the provided **Application Id** and **Secret** and set the following environment variables:
> In the examples below, note the use of `gitlab-server-example.com` and `chronograf-server-example.com` in urls.
> These should be replaced by the actual URLs used to access each service.
```bash
GENERIC_NAME="gitlab"
GENERIC_CLIENT_ID=<gitlab_application_id>
GENERIC_CLIENT_SECRET=<gitlab_secret>
GENERIC_AUTH_URL="https://gitlab.com/oauth/authorize"
GENERIC_TOKEN_URL="https://gitlab.com/oauth/token"
TOKEN_SECRET=<mytokensecret>
GENERIC_SCOPES="api,openid,read_user"
PUBLIC_URL="http://<chronograf-host>:8888"
GENERIC_API_URL="https://gitlab.com/api/v3/user"
```
The equivalent command line options are:
```bash
--generic-name=gitlab
--generic-client-id=<gitlab_application_id>
--generic-client-secret=<gitlab_secret>
--generic-auth-url=https://gitlab.com/oauth/authorize
--generic-token-url=https://gitlab.com/oauth/token
--token-secret=<mytokensecret>
--generic-scopes=openid,read_user
--generic-api-url=https://gitlab.com/api/v3/user
--public-url=http://<chronograf-host>:8888/
```
#### Configure Azure Active Directory authentication
1. [Create an Azure Active Directory application](https://docs.microsoft.com/en-us/azure/active-directory/develop/howto-create-service-principal-portal#create-an-azure-active-directory-application).
Note the following information: `<APPLICATION-ID>`, `<TENANT-ID>`, and `<APPLICATION-KEY>`.
You'll need these to define your Chronograf environment.
2. Be sure to register a reply URL in your Azure application settings.
This should match the calling URL from Chronograf.
Otherwise, you will get an error stating no reply address is registered for the application.
For example, if Chronograf is configured with a `GENERIC_NAME` value of AzureAD, the reply URL would be `http://localhost:8888/oauth/AzureAD/callback`.
3. After completing the application provisioning within Azure AD, you can now complete the configuration with Chronograf.
Using the metadata from your Azure AD instance, proceed to export the following environment variables:
Set the following environment variables in `/etc/default/chronograf`:
```
GENERIC_TOKEN_URL=https://login.microsoftonline.com/<<TENANT-ID>>/oauth2/token
TENANT=<<TENANT-ID>>
GENERIC_NAME=AzureAD
GENERIC_API_KEY=userPrincipalName
GENERIC_SCOPES=openid
GENERIC_CLIENT_ID=<<APPLICATION-ID>>
GENERIC_AUTH_URL=https://login.microsoftonline.com/<<TENANT-ID>>/oauth2/authorize?resource=https://graph.windows.net
GENERIC_CLIENT_SECRET=<<APPLICATION-KEY>>
TOKEN_SECRET=secret
GENERIC_API_URL=https://graph.windows.net/<<TENANT-ID>>/me?api-version=1.6
PUBLIC_URL=http://localhost:8888
```
Note: If you’ve configured TLS/SSL, modify the `PUBLIC_URL` to ensure you're using HTTPS.
#### Configure Chronograf to use any OAuth 2.0 provider
Chronograf can be configured to work with any OAuth 2.0 provider, including those defined above, by using the generic configuration options below.
Additionally, the generic provider implements OpenID Connect (OIDC) as implemented by Active Directory Federation Services (AD FS).
When using the generic configuration, some or all of the following environment variables (or corresponding command line options) are required (depending on your OAuth 2.0 provider):
* `GENERIC_CLIENT_ID`: Application client [identifier](https://tools.ietf.org/html/rfc6749#section-2.2) issued by the provider
* `GENERIC_CLIENT_SECRET`: Application client [secret](https://tools.ietf.org/html/rfc6749#section-2.3.1) issued by the provider
* `GENERIC_AUTH_URL`: Provider's authorization [endpoint](https://tools.ietf.org/html/rfc6749#section-3.1) URL
* `GENERIC_TOKEN_URL`: Provider's token [endpoint](https://tools.ietf.org/html/rfc6749#section-3.2) URL used by the Chronograf client to obtain an access token
* `USE_ID_TOKEN`: Enable OpenID [id_token](https://openid.net/specs/openid-connect-core-1_0.html#rfc.section.3.1.3.3) processing
* `JWKS_URL`: Provider's JWKS [endpoint](https://tools.ietf.org/html/rfc7517#section-4.7) used by the client to validate RSA signatures
* `GENERIC_API_URL`: Provider's [OpenID UserInfo endpoint](https://connect2id.com/products/server/docs/api/userinfo)] URL used by Chronograf to request user data
* `GENERIC_API_KEY`: JSON lookup key for [OpenID UserInfo](https://connect2id.com/products/server/docs/api/userinfo)] (known to be required for Microsoft Azure, with the value `userPrincipalName`)
* `GENERIC_SCOPES`: [Scopes](https://tools.ietf.org/html/rfc6749#section-3.3) of user data required for your instance of Chronograf, such as user email and OAuth provider organization
- Multiple values must be space-delimited, e.g. `user:email read:org`
- These may vary by OAuth 2.0 provider
- Default value: `user:email`
* `PUBLIC_URL`: Full public URL used to access Chronograf from a web browser, i.e. where Chronograf is hosted
- Used by Chronograf, for example, to construct the callback URL
* `TOKEN_SECRET`: Used to validate OAuth [state](https://tools.ietf.org/html/rfc6749#section-4.1.1) response. (see above)
##### Optional environment variables
The following environment variables (and corresponding command line options) are also available for optional use:
* `GENERIC_DOMAINS`: Email domain where email address must include.
* `GENERIC_NAME`: Value used in the callback URL in conjunction with `PUBLIC_URL`, e.g. `<PUBLIC_URL>/oauth/<GENERIC_NAME>/callback`
- This value is also used in the text for the Chronograf Login button
- Default value is `generic`
- So, for example, if `PUBLIC_URL` is `https://localhost:8888` and `GENERIC_NAME` is its default value, then the callback URL would be `https://localhost:8888/oauth/generic/callback`, and the Chronograf Login button would read `Log in with Generic`
- While using Chronograf, this value should be supplied in the `Provider` field when adding a user or creating an organization mapping.
##### Example: OIDC with AD FS
See [Enabling OpenID Connect with AD FS 2016](https://docs.microsoft.com/en-us/windows-server/identity/ad-fs/development/enabling-openid-connect-with-ad-fs) for a walk through of the server configuration.
Exports for Chronograf (e.g. in `/etc/default/chronograf`):
```sh
PUBLIC_URL="https://example.com:8888"
GENERIC_CLIENT_ID="chronograf"
GENERIC_CLIENT_SECRET="KW-TkvH7vzYeJMAKj-3T1PdHx5bxrZnoNck2KlX8"
GENERIC_AUTH_URL="https://example.com/adfs/oauth2/authorize"
GENERIC_TOKEN_URL="https://example.com/adfs/oauth2/token"
GENERIC_SCOPES="openid"
GENERIC_API_KEY="upn"
USE_ID_TOKEN="true"
JWKS_URL="https://example.com/adfs/discovery/keys"
TOKEN_SECRET="ZNh2N9toMwUVQxTVEe2ZnnMtgkh3xqKZ"
```
> _**Note:**_ Do not use special characters for the GENERIC_CLIENT_ID as AD FS will split strings here, finally resulting in an identifier mismatch.
### Configure authentication duration
By default, user authentication remains valid for 30 days using a cookie stored in the web browser.
To configure a different authorization duration, set a duration using the `AUTH_DURATION` environment variable.
**Example:**
To set the authentication duration to 1 hour, use the following shell command:
```sh
export AUTH_DURATION=1h
```
The duration uses the Go (golang) [time duration format](https://golang.org/pkg/time/#ParseDuration), so the largest time unit is `h` (hours).
So to change it to 45 days, use:
```sh
export AUTH_DURATION=1080h
```
To require re-authentication every time the browser is closed, set `AUTH_DURATION` to `0`.
This makes the cookie transient (aka "in-memory").
## Configure TLS (Transport Layer Security) and HTTPS
The TLS (Transport Layer Security) cryptographic protocol is supported in Chronograf to provides server authentication, data confidentiality, and data integrity.
Using TLS secures traffic between a server and web browser and enables the use of HTTPS.
InfluxData recommends using HTTPS to communicate securely with Chronograf applications.
If you are not using a TLS termination proxy, you can run your Chronograf server with TLS connections.
Chronograf includes command line and environment variable options for configuring TLS (Transport Layer Security) certificates and key files.
Use of the TLS cryptographic protocol provides server authentication, data confidentiality, and data integrity.
When configured, users can use HTTPS to securely communicate with your Chronograf applications.
> ***Note:*** Using HTTPS helps guard against nefarious agents sniffing the JWT and using it to spoof a valid user against the Chronograf server.
### Configuring TLS for Chronograf
Chronograf server has command line and environment variable options to specify the certificate and key files.
The server reads and parses a public/private key pair from these files.
The files must contain PEM-encoded data.
All Chronograf command line options have corresponding environment variables.
**To configure Chronograf to support TLS:**
1. Specify the certificate file using the `TLS_CERTIFICATE` environment variable (or the `--cert` CLI option).
2. Specify the key file using the `TLS_PRIVATE_KEY` environment variable (or `--key` CLI option).
> ***Note:*** If both the TLS certificate and key are in the same file, specify them using the `TLS_CERTIFICATE` environment variable (or the `--cert` CLI option).
#### Example with CLI options
```sh
chronograf --cert=my.crt --key=my.key
```
#### Example with environment variables
```sh
TLS_CERTIFICATE=my.crt TLS_PRIVATE_KEY=my.key chronograf
```
#### Docker example with environment variables
```sh
docker run -v /host/path/to/certs:/certs -e TLS_CERTIFICATE=/certs/my.crt -e TLS_PRIVATE_KEY=/certs/my.key quay.io/influxdb/chronograf:latest
```
### Testing with self-signed certificates
In a production environment you should not use self-signed certificates, but for testing it is fast to create your own certificates.
To create a certificate and key in one file with OpenSSL:
```sh
openssl req -x509 -newkey rsa:4096 -sha256 -nodes -keyout testing.pem -out testing.pem -subj "/CN=localhost" -days 365
```
Next, set the environment variable `TLS_CERTIFICATE`:
```sh
export TLS_CERTIFICATE=$PWD/testing.pem
```
Run Chronograf:
```sh
./chronograf
INFO[0000] Serving chronograf at https://[::]:8888 component=server
```
In the first log message you should see `https` rather than `http`.

32
content/chronograf/v1.8/administration/migrate-to-high-availability.md Normal file
View File

@ -0,0 +1,32 @@
---
title: Migrate to a Chronograf HA configuration
description: Migrate a Chronograf single instance configuration using BoltDB to a Chronograf high-availability (HA) cluster configuration using etcd.
menu:
chronograf_1_8:
weight: 10
parent: Administration
---
Use [`chronoctl`](/chronograf/v1.8/tools/chronoctl/) to migrate your Chronograf configuration store from BoltDB to a shared `etcd` data store used for Chronograf high-availability (HA) clusters.
> **Note:** Migrating Chronograf to a shared data source creates new source IDs for each resource. Update external links to Chronograf dashboards to reflect new source IDs.
1. Stop the Chronograf server by killing the `chronograf` process.
2. To prevent data loss, we **strongly recommend** that you back up your Chronograf data store before migrating to a Chronograf cluster.
3. [Install and start etcd](/chronograf/v1.8/administration/create-high-availability/#install-and-start-etcd).
4. Run the following command, specifying the local BoltDB file and the `etcd` endpoint beginning with `etcd://`. (We recommend adding the prefix `bolt://` to an absolute path. To specify a relative path to the BoltDB file, the prefix cannot be used.)
```sh
$ chronoctl migrate -f bolt:///path/to/chronograf-v1.db -t etcd://localhost:2379
```
> **Note:**
If you have authentication on `etcd`, use the standard URI format to define a username and password. For example, `etcd://user:pass@localhost:2379`
5. Update links to Chronograf (for example, from external sources) to reflect your new URLs:
- **from BoltDB:**
http://localhost:8888/sources/1/status
- **to etcd:**
http://localhost:8888/sources/373921399246786560/status
6. Set up a load balancer for Chronograf.
7. [Start Chronograf](/chronograf/v1.8/administration/create-high-availability/#start-chronograf).

486
content/chronograf/v1.8/administration/prebuilt-dashboards.md Normal file
View File

@ -0,0 +1,486 @@
---
title: Prebuilt dashboards in Chronograf
description: Prebuilt dashboards available to import based on Telegraf input plugins.
menu:
chronograf_1_8:
name: Prebuilt dashboards in Chronograf
weight: 50
parent: Administration
---
Chronograf lets you import a variety of prebuilt dashboards that visualize metrics collect by specific [Telegraf input plugins](/telegraf/latest/plugins/plugin-list). The following Telegraf-related dashboards templates are available.
For details on how to import dashboards while adding a connection in Chronograf, see [Creating connections](/chronograf/v1.8/administration/creating-connections/#managing-influxdb-connections-using-the-chronograf-ui).
## Docker
The Docker dashboard displays the following information:
- nCPU
- Total Memory
- # Containers
- System Memory Usage
- System Load
- Disk I/O
- Filesystem Usage
- Block I/O per Container
- CPU Usage per Container
- Memory Usage % per Container
- Memory Usage per Container
- Net I/O per Container
### Plugins
- [`docker` plugin](/telegraf/latest/plugins/plugin-list/#docker)
- [`disk` plugin](/telegraf/latest/plugins/plugin-list/#disk)
- [`mem` plugin](/telegraf/latest/plugins/plugin-list/#mem)
- [`diskio` plugin](/telegraf/latest/plugins/plugin-list/#diskio)
- [`system` plugin](/telegraf/latest/plugins/plugin-list/#system)
- [`cpu` plugin](/telegraf/latest/plugins/plugin-list/#cpu)
## Kubernetes Node
The Kubernetes Node dashboard displays the following information:
- Total Nodes
- Total Pod Count
- Total Containers
- K8s - Node Millicores
- K8s - Node Memory Bytes
- K8s - Pod Millicores
- K8s - Pod Memory Bytes
- K8s - Pod TX Bytes/Second
- K8s - Pod RX Bytes/Second
- K8s - Kubelet Millicores
- K8s - Kubelet Memory Bytes
### Plugins
- [kubernetes](/telegraf/latest/plugins/plugin-list/#kubernetes)
## Kubernetes Overview
The Kubernetes Node dashboard displays the following information:
- Total Nodes
- Total Pod Count
- Total Containers
- K8s - Node Millicores
- K8s - Node Memory Bytes
- K8s - Pod Millicores
- K8s - Pod Memory Bytes
- K8s - Pod TX Bytes/Second
- K8s - Pod RX Bytes/Second
- K8s - Kubelet Millicores
- K8s - Kubelet Memory Bytes
### Plugins
- [kubernetes](/telegraf/latest/plugins/plugin-list/#kubernetes)
## Kubernetes Pod
The Kubernetes Pod dashboard displays the following information:
- Total Nodes
- Total Pod Count
- Total Containers
- K8s - Pod Millicores
- K8s - Pod Memory Bytes
- K8s - Pod Millicores
- K8s - Pod Memory Bytes
- K8s - Pod TX Bytes/Second
### Plugins
- [kubernetes](/telegraf/latest/plugins/plugin-list/#kubernetes)
## Riak
The Riak dashboard displays the following information:
- Riak - Total Memory Bytes
- Riak - Object Byte Size
- Riak - Number of Siblings/Minute
- Riak - Latency (ms)
- Riak - Reads and Writes/Minute
- Riak - Active Connections
- Riak - Read Repairs/Minute
### Plugins
- [`riak` plugin](/telegraf/latest/plugins/plugin-list/#riak)
## Consul
The Consul dashboard displays the following information:
- Consul - Number of Critical Health Checks
- Consul - Number of Warning Health Checks
### Plugins
- [`consul` plugin](/telegraf/latest/plugins/plugin-list/#consul)
## Consul Telemetry
The Consul Telemetry dashboard displays the following information:
- Consul Agent - Number of Go Routines
- Consul Agent - Runtime Alloc Bytes
- Consul Agent - Heap Objects
- Consul - Number of Agents
- Consul - Leadership Election
- Consul - HTTP Request Time (ms)
- Consul - Leadership Change
- Consul - Number of Serf Events
### Plugins
[`consul` plugin](/telegraf/latest/plugins/plugin-list/#consul)
## Mesos
The Mesos dashboard displays the following information:
- Mesos Active Slaves
- Mesos Tasks Active
- Mesos Tasks
- Mesos Outstanding Offers
- Mesos Available/Used CPUs
- Mesos Available/Used Memory
- Mesos Master Uptime
### Plugins
- [`mesos` plugin](/telegraf/latest/plugins/plugin-list/#mesos)
## RabbitMQ
The RabbitMQ dashboard displays the following information:
- RabbitMQ - Overview
- RabbitMQ - Published/Delivered per Second
- RabbitMQ - Acked/Unacked per Second
### Plugins
- [`rabbitmq` plugin](/telegraf/latest/plugins/plugin-list/#rabbitmq)
## System
The System dashboard displays the following information:
- System Uptime
- CPUs
- RAM
- Memory Used %
- Load
- I/O
- Network
- Processes
- Swap
### Plugins
- [`system` plugin](/telegraf/latest/plugins/plugin-list/#system)
- [`mem` plugin](/telegraf/latest/plugins/plugin-list/#mem)
- [`cpu` plugin](/telegraf/latest/plugins/plugin-list/#cpu)
- [`disk` plugin](/telegraf/latest/plugins/plugin-list/#disk)
- [`diskio` plugin](/telegraf/latest/plugins/plugin-list/#diskio)
- [`net` plugin](/telegraf/latest/plugins/plugin-list/#net)
- [`processes` plugin](/telegraf/latest/plugins/plugin-list/#processes)
- [`swap` plugin](/telegraf/latest/plugins/plugin-list/#swap)
## VMware vSphere Overview
The VMware vSphere Overview dashboard gives an overview of your VMware vSphere Clusters and uses metrics from the `vsphere_cluster_*` and `vsphere_vm_*` set of measurements. It displays the following information:
- Cluster Status
- Uptime for :clustername:
- CPU Usage for :clustername:
- RAM Usage for :clustername:
- Datastores - Usage Capacity
- Network Usage for :clustername:
- Disk Throughput for :clustername:
- VM Status
- VM CPU Usage MHz for :clustername:
- VM Mem Usage for :clustername:
- VM Network Usage for :clustername:
- VM CPU % Ready for :clustername:
### Plugins
- [`vsphere` plugin](/telegraf/latest/plugins/plugin-list/#vmware-vsphere)
## Apache
The Apache dashboard displays the following information:
- System Uptime
- CPUs
- RAM
- Memory Used %
- Load
- I/O
- Network
- Workers
- Scoreboard
- Apache Uptime
- CPU Load
- Requests per Sec
- Throughput
- Response Codes
- Apache Log
### Plugins
- [`apache` plugin](/telegraf/latest/plugins/plugin-list/#apache)
- [`system` plugin](/telegraf/latest/plugins/plugin-list/#system)
- [`mem` plugin](/telegraf/latest/plugins/plugin-list/#mem)
- [`diskio` plugin](/telegraf/latest/plugins/plugin-list/#diskio)
- [`net` plugin](/telegraf/latest/plugins/plugin-list/#net)
- [`logparser` plugin](/telegraf/latest/plugins/plugin-list/#logparser)
## ElasticSearch
The ElasticSearch dashboard displays the following information:
- ElasticSearch - Query Throughput
- ElasticSearch - Open Connections
- ElasticSearch - Query Latency
- ElasticSearch - Fetch Latency
- ElasticSearch - Suggest Latency
- ElasticSearch - Scroll Latency
- ElasticSearch - Indexing Latency
- ElasticSearch - JVM GC Collection Counts
- ElasticSearch - JVM GC Latency
- ElasticSearch - JVM Heap Usage
### Plugins
- [`elasticsearch` plugin](/telegraf/latest/plugins/plugin-list/#elasticsearch)
## InfluxDB
The InfluxDB dashboard displays the following information:
- System Uptime
- System Load
- Network
- Memory Usage
- CPU Utilization %
- Filesystems Usage
- # Measurements
- nCPU
- # Series
- # Measurements per DB
- # Series per DB
- InfluxDB Memory Heap
- InfluxDB Active Requests
- InfluxDB - HTTP Requests/Min
- InfluxDB GC Activity
- InfluxDB - Written Points/Min
- InfluxDB - Query Executor Duration
- InfluxDB - Write Errors
- InfluxDB - Client Errors
- # CQ/Minute
### Plugins
- [`influxdb` plugin](/telegraf/latest/plugins/plugin-list/#influxdb)
- [`cpu` plugin](/telegraf/latest/plugins/plugin-list/#cpu)
- [`system` plugin](/telegraf/latest/plugins/plugin-list/#system)
- [`mem` plugin](/telegraf/latest/plugins/plugin-list/#mem)
- [`diskio` plugin](/telegraf/latest/plugins/plugin-list/#diskio)
- [`net` plugin](/telegraf/latest/plugins/plugin-list/#net)
## Memcached
The Memcached dashboard displays the following information:
- Memcached - Current Connections
- Memcached - Get Hits/Second
- Memcached - Get Misses/Second
- Memcached - Delete Hits/Second
- Memcached - Delete Misses/Second
- Memcached - Incr Hits/Second
- Memcached - Incr Misses/Second
- Memcached - Current Items
- Memcached - Total Items
- Memcached - Bytes Stored
- Memcached - Bytes Read/Sec
- Memcached - Bytes Written/Sec
- Memcached - Evictions/10 Seconds
### Plugins
- [`memcached` plugin](/telegraf/latest/plugins/plugin-list/#memcached)
## NSQ
The NSQ dashboard displays the following information:
- NSQ - Channel Client Count
- NSQ - Channel Messages Count
- NSQ - Topic Count
- NSQ - Server Count
- NSQ - Topic Messages
- NSQ - Topic Messages on Disk
- NSQ - Topic Ingress
- NSQ - Topic Egress
### Plugins
- [`nsq` plugin](/telegraf/latest/plugins/plugin-list/#nsq)
## PostgreSQL
The PostgreSQL dashboard displays the following information:
- System Uptime
- nCPU
- System Load
- Total Memory
- Memory Usage
- Filesystems Usage
- CPU Usage
- System Load
- I/O
- Network
- Processes
- Swap
- PostgreSQL rows out/sec
- PostgreSQL rows in/sec
- PostgreSQL - Buffers
- PostgreSQL commit/rollback per sec
- Postgres deadlocks/conflicts
### Plugins
- [`postgresql` plugin](/telegraf/latest/plugins/plugin-list/#postgresql)
- [`system` plugin](/telegraf/latest/plugins/plugin-list/#system)
- [`mem` plugin](/telegraf/latest/plugins/plugin-list/#mem)
- [`cpu` plugin](/telegraf/latest/plugins/plugin-list/#cpu)
- [`diskio` plugin](/telegraf/latest/plugins/plugin-list/#diskio)
## HAProxy
The HAProxy dashboard displays the following information:
- HAProxy - Number of Servers
- HAProxy - Sum HTTP 2xx
- HAProxy - Sum HTTP 4xx
- HAProxy - Sum HTTP 5xx
- HAProxy - Frontend HTTP Requests/Second
- HAProxy - Frontend Sessions/Second
- HAProxy - Frontend Session Usage %
- HAProxy - Frontend Security Denials/Second
- HAProxy - Frontend Request Errors/Second
- HAProxy - Frontend Bytes/Second
- HAProxy - Backend Average Response Time
- HAProxy - Backend Connection Errors/Second
- HAProxy - Backend Queued Requests/Second
- HAProxy - Backend Average Requests Queue Time (ms)
- HAProxy - Backend Error Responses/Second
### Plugins
- [`haproxy` plugin](/telegraf/latest/plugins/plugin-list/#haproxy)
## NGINX
The NGINX dashboard displays the following information:
- NGINX - Client Connection
- NGINX - Client Errors
- NGINX - Client Requests
- NGINX - Active Client State
### Plugins
- [`nginx` plugin](/telegraf/latest/plugins/plugin-list/#nginx)
## Redis
The Redis dashboard displays the following information:
- Redis - Connected Clients
- Redis - Blocked Clients
- Redis - CPU
- Redis - Memory
### Plugins
- [`redis` plugin](/telegraf/latest/plugins/plugin-list/#redis)
## VMware vSphere VMs
The VMWare vSphere VMs dashboard gives an overview of your VMware vSphere virtual machines and includes metrics from the `vsphere_vm_*` set of measurements. It displays the following information:
- Uptime for :vmname:
- CPU Usage for :vmname:
- RAM Usage for :vmname:
- CPU Usage Average for :vmname:
- RAM Usage Average for :vmname:
- CPU Ready Average % for :vmname:
- Network Usage for:vmname:
- Total Disk Latency for :vmname:
### Plugins
- [`vsphere` plugin](/telegraf/latest/plugins/plugin-list/#vsphere)
## VMware vSphere Hosts
The VMWare vSphere Hosts dashboard displays the following information:
- Uptime for :esxhostname:
- CPU Usage for :esxhostname:
- RAM Usage for :esxhostname:
- CPU Usage Average for :esxhostname:
- RAM Usage Average for :esxhostname:
- CPU Ready Average % for :esxhostname:
- Network Usage for :esxhostname:
- Total Disk Latency for :esxhostname:
### Plugins
- [`vsphere` plugin](/telegraf/latest/plugins/plugin-list/#vsphere)
## PHPfpm
The PHPfpm dashboard displays the following information:
- PHPfpm - Accepted Connections
- PHPfpm - Processes
- PHPfpm - Slow Requests
- PHPfpm - Max Children Reached
### Plugins
- [`phpfpm` plugin](/telegraf/latest/plugins/plugin-list/#nginx)
## Win System
The Win System dashboard displays the following information:
- System - CPU Usage
- System - Available Bytes
- System - TX Bytes/Second
- System - RX Bytes/Second
- System - Load
### Plugins
- [`win_services` plugin](/telegraf/latest/plugins/plugin-list/#windows-services)
## MySQL
The MySQL dashboard displays the following information:
- System Uptime
- nCPU
- MySQL uptime
- Total Memory
- System Load
- Memory Usage
- InnoDB Buffer Pool Size
- InnoDB Buffer Usage
- Max Connections
- Open Connections
- I/O
- Network
- MySQL Connections/User
- MySQL Received Bytes/Sec
- MySQL Sent Bytes/Sec
- MySQL Connections
- MySQL Queries/Sec
- MySQL Slow Queries
- InnoDB Data
### Plugins
- [`mySQL` plugin](/telegraf/latest/plugins/plugin-list/#mysql)
- [`system` plugin](/telegraf/latest/plugins/plugin-list/#system)
- [`mem` plugin](/telegraf/latest/plugins/plugin-list/#mem)
## Ping
The Ping dashboard displays the following information:
- Ping - Packet Loss Percent
- Ping - Response Times (ms)
### Plugins
- [`ping` plugin](/telegraf/latest/plugins/plugin-list/#ping)

81
content/chronograf/v1.8/administration/restoring-chronograf-db.md Normal file
View File

@ -0,0 +1,81 @@
---
title: Restoring a Chronograf database
description: 'An outline of the process required to roll the Chronoraf internal database back to a previous version and/or rerun update migrations.'
menu:
chronograf_1_8:
weight: 110
parent: Administration
---
Chronograf uses [Bolt](https://github.com/boltdb/bolt) to store Chronograf-specific key-value data.
Generally speaking, you should never have to manually administer your internal Chronograf database.
However, rolling back to a previous version of Chronograf does require restoring
the data and data-structure specific to that version.
Chronograf's internal database, `chronograf-v1.db`, is stored at your specified
[`--bolt-path`](/chronograf/v1.8/administration/config-options/#bolt-path-b) which,
by default, is the current working directory where the `chronograf` binary is executed.
In the upgrade process, an unmodified backup of your Chronograf data is stored inside the
`backup` directory before any necessary migrations are run.
This is done as a convenience in case issues arise with the data migrations
or the upgrade process in general.
The `backup` directory contains a copy of your previous `chronograf-v1.db` file.
Each backup file is appended with the corresponding Chronograf version.
For example, if you moved from Chronograf 1.4.4.2 to 1.8.0, there will be a
file called `backup/chronograf-v1.db.1.4.4.2`.
_**Chronograf backup directory structure**_
```
chronograf-working-dir/
├── chronograf-v1.db
├── backup/
| ├── chronograf-v1.db.1.4.4.0
| ├── chronograf-v1.db.1.4.4.1
| └── chronograf-v1.db.1.4.4.2
└── ...
```
## Rolling back to a previous version
If there is an issue during the upgrade process or you simply want/need to roll
back to an earlier version of Chronograf, you must restore the data file
associated with that specific version, then downgrade and restart Chronograf.
The process is as follows:
### 1. Locate your desired backup file
Inside your `backup` directory, locate the database file with a the appended Chronograf
version that corresponds to the version to which you are rolling back.
For example, if rolling back to 1.4.4.2, find `backup/chronograf-v1.db.1.4.4.2`.
### 2. Stop your Chronograf server
Stop the Chronograf server by killing the `chronograf` process.
### 3. Replace your current database with the backup
Remove the current database file and replace it with the desired backup file:
```bash
# Remove the current database
rm chronograf-v1.db
# Replace it with the desired backup file
cp backup/chronograf-v1.db.1.4.4.2 chronograf-v1.db
```
### 4. Install the desired Chronograf version
Install the desired Chronograf version.
Chronograf releases can be viewed and downloaded either from the
[InfluxData downloads](https://portal.influxdata.com/downloads)
page or from the [Chronograf releases](https://github.com/influxdata/chronograf/releases)
page on Github.
### 5. Start the Chronograf server
Restart the Chronograf server.
Chronograf will use the `chronograf-v1.db` in the current working directory.
## Rerunning update migrations
This process can also be used to rerun Chronograf update migrations.
Go through steps 1-5, but on [step 3](#3-replace-your-current-database-with-the-backup)
select the backup you want to use as a base for the migrations.
When Chronograf starts again, it will automatically run the data migrations
required for the installed version.

19
content/chronograf/v1.8/administration/upgrading.md Normal file
View File

@ -0,0 +1,19 @@
---
title: Upgrading Chronograf
description: Covers upgrading Chronograf to the latest version.
menu:
chronograf_1_8:
name: Upgrading
weight: 10
parent: Administration
---
## Upgrading to Chronograf 1.8
If you're upgrading from Chronograf 1.3.x, first install 1.7.x, and then install 1.8.
If you're upgrading from Chronograf 1.4 or later, [download and install](https://portal.influxdata.com/downloads) the most recent version of Chronograf, and then restart Chronograf.
> ***Note:*** Installing a new version of Chronograf automatically clears the localStorage settings.
After upgrading, see [Getting Started](/chronograf/latest/introduction/getting-started/) to get up and running.

64
content/chronograf/v1.8/guides/_index.md Normal file
View File

@ -0,0 +1,64 @@
---
title: Guides for Chronograf
description: The Chronograf guides discuss dashboards, monitoring InfluxDB Enterprise clusters, Kapacitor alerts and event handlers, template variables, visualization types, and TICKscript editing/logging.
menu:
chronograf_1_8:
name: Guides
weight: 30
---
Follow the links below to explore Chronograf's features.
## [Exploring data in Chronograf](/chronograf/v1.8/guides/querying-data)
Use Chronograf's Data Explorer to query and visualize your time series data.
## [Using pre-created dashboards](/chronograf/v1.8/guides/using-precreated-dashboards/)
Pre-created dashboards are available when the required Telegraf input plugins are enabled. These dashboards include cells with data visualizations for metrics that are relevant to data sources you are likely to be using.
## [Using the TICKscript editor](/chronograf/v1.8/guides/tickscript-logging/)
Using the TICKscript editor in Chronograf to create, test, and debug Kapacitor TICKscripts.
## [Creating dashboards](/chronograf/latest/guides/create-a-dashboard/)
Chronograf offers a complete dashboard solution for visualizing your data and monitoring your infrastructure.
Learn how to create customized dashboards in Chronograf.
## [Cloning dashboards and cells](/chronograf/v1.8/guides/cloning-in-ui/)
Use Chronograf's cloning functionality to make copies of dashboards and cells.
## [Visualization types in Chronograf](/chronograf/v1.8/guides/visualization-types/)
Describes the visualization types available to display in Chronograf views in dashboards.
## [Adding annotations in Chronograf views](/chronograf/v1.8/guides/annotations/)
Describes how to add annotations to Chronograf views with the user interface or using the command line interface.
## [Creating Chronograf alert rules](/chronograf/v1.8/guides/create-alert-rules/)
Learn how to create alert rules in Chronograf.
## [Configuring Chronograf alert endpoints](/chronograf/v1.8/guides/configuring-alert-endpoints/)
Chronograf works with Kapacitor to send alert messages to supported event handlers.
Use Chronograf to send alert messages to specific URLs as well as to applications like Slack and HipChat.
Learn how to set up event handlers in Chronograf.
## [Monitoring InfluxDB Enterprise clusters](/chronograf/v1.8/guides/monitoring-influxenterprise-clusters/)
InfluxDB Enterprise offers high availability and a highly-scalable clustering solution for your time series data needs.
Learn how to use Chronograf to assess your cluster’s health and monitor the infrastructure behind your project.
## [Using dashboard template variables](/chronograf/v1.8/guides/dashboard-template-variables/)
Learn how to use Chronograf's dashboard template variables to interact with your dashboards and gain insights into your data.
## [Advanced Kapacitor usage](/chronograf/v1.8/guides/advanced-kapacitor/)
Chronograf provides a user interface for Kapacitor, InfluxData’s processing framework for creating alerts, running ETL jobs, and detecting anomalies in your data.
Learn how Kapacitor interacts with Chronograf at a lower level and learn about advanced Kapacitor usage within Chronograf.

72
content/chronograf/v1.8/guides/advanced-kapacitor.md Normal file
View File

@ -0,0 +1,72 @@
---
title: Advanced Kapacitor usage
description: Learn how Kapacitor can be used with Chronograf for alert history and TICKscript management.
menu:
chronograf_1_8:
weight: 100
parent: Guides
---
### On this page
* [Alert history management](#alert-history-management)
* [TICKscript management](#tickscript-management)
Chronograf provides a user interface for [Kapacitor](/kapacitor/latest/), InfluxData's processing framework for creating alerts, running ETL jobs, and detecting anomalies in your data.
This guide offers insights into how Kapacitor interacts with Chronograf and introduces advanced Kapacitor usage within Chronograf.
## Alert history management
Chronograf stores the information on the Alert History page as time series data in InfluxDB.
It stores it in the `chronograf` database and in the `alerts` [measurement](/influxdb/latest/concepts/glossary/#measurement).
By default, this data is subject to an infinite [retention policy](/influxdb/latest/concepts/glossary/#retention-policy-rp) (RP), that is, InfluxDB stores them forever.
Users who expect to have a large number of alerts and users who do not want to store their alert history forever may want to shorten the [duration](/influxdb/latest/concepts/glossary/#duration) of that retention policy.
### Modifying the retention policy in Chronograf
Use the Chronograf Admin page to modify the retention policy in the `chronograf` database.
In the Databases tab:
#### Step 1: Locate the `chronograf` database and click on the infinity symbol (∞)
![RP in practice](/img/chronograf/v1.8/g-advkap-dur.png)
#### Step 2: Enter a different duration
The minimum allowable duration is one hour (`1h`) and the maximum is infinite (`INF`).
See the InfluxDB documentation for the list of [acceptable duration units](/influxdb/latest/query_language/spec/#duration-units).
#### Step 3: Click the green check mark to save your changes
InfluxDB only keeps data in the `chronograf` database that fall within that new duration; the system automatically deletes any data with timestamps that occur before the duration setting.
### Example
If you set the retention policy's duration to one hour (`1h`), InfluxDB automatically deletes any alerts that occurred before the past hour.
Those alerts no longer appear in your InfluxDB instance or on Chronograf's Alert History page.
Looking at the image below and assuming that the current time is 19:00 on April 27, 2017, only the first three alerts would appear in your alert history; they occurred within the previous hour (18:00 through 19:00).
The fourth alert, which occurred on the same day at 16:58:50, is outside the previous hour and would no longer appear in the InfluxDB `chronograf` database or on the Chronograf Alert History page.
![RP in practice](/img/chronograf/v1.8/g-advkap-rp.png)
## TICKscript management
Chronograf creates Kapacitor tasks using the information that you provide on the Rule Configuration page.
It uses that information to communicate with Kapacitor and populate Chronograf alert pages.
Pre-existing tasks, or [TICKscripts](/kapacitor/latest/tick/), that you created and enabled on your Kapacitor instance without using Chronograf, have limited functionality in the user interface.
In Chronograf, you can:
* View pre-existing tasks the Alert Rules page
* View pre-existing task activity on the Alert History page
* Enable and disable pre-existing tasks on the Alert Rules page (this is equivalent to the `kapacitor enable` and `kapacitor disable` commands)
* Delete pre-existing tasks the Alert Rules page (this is equivalent to the `kapacitor delete tasks` command)
You cannot edit pre-existing tasks on the Chronograf Alert Rules page.
The `mytick` task in the image below is a pre-existing task; its name appears on the Alert Rules page but you cannot click on it or edit its TICKscript in the interface.
Currently, you must manually edit your existing tasks and TICKscripts on your machine.
![Pre-existing task](/img/chronograf/v1.8/g-advkap-pretick.png)

87
content/chronograf/v1.8/guides/analyzing-logs.md Normal file
View File

@ -0,0 +1,87 @@
---
title: Analyzing logs with Chronograf
description: View, search, filter, visualize, and analyze log information using Chronograf and InfluxDB.
menu:
chronograf_1_8:
weight: 120
parent: Guides
---
Chronograf gives you the ability to view, search, filter, visualize, and analyze log information from a variety of sources.
This helps to recognize and diagnose patterns, then quickly dive into logged events that lead up to events.
## Logging setup
Logs data is a first class citizen in InfluxDB and is populated using available log-related [Telegraf input plugins](/telegraf/latest/plugins/inputs/):
[syslog](https://github.com/influxdata/telegraf/tree/release-1.8/plugins/inputs/syslog)
## Viewing logs in Chronograf
Chronograf has a dedicated log viewer accessed by clicking the **Log Viewer** button in the left navigation.
<img src="/img/chronograf/v1.8/logs-nav-log-viewer.png" alt="Log viewer in the left nav" style="width:100%;max-width:209px;"/>
The log viewer provides a detailed histogram showing the time-based distribution of log entries color-coded by log severity.
It also includes a live stream of logs that can be searched, filtered, and paused to analyze specific time ranges.
Logs are pulled from the `syslog` measurement.
_Other log inputs and alternate log measurement options will be available in future updates._
<img src="/img/chronograf/log-viewer-overview.png" alt="Chronograf log viewer" style="width:100%;max-width:1016px;"/>
### Searching and filtering logs
Search for logs using keywords or regular expressions.
They can also be filtered by clicking values in the log table such as `severity` or `facility`.
Any tag values included with the log entry can be used as a filter.
You can also use search operators to filter your results. For example, if you want to find results with a severity of critical that don't mention RSS, you can enter: `severity == crit` and `-RSS`.
![Searching and filtering logs](/img/chronograf/log-viewer-search-filter.gif)
> **Note:** The log search field is case-sensitive.
To remove filters, click the `×` next to the tag key by which you no longer want to filter.
### Selecting specific times
In the log viewer, you can select time ranges from which to view logs.
By default, logs are streamed and displayed relative to "now," but it is possible to view logs from a past window of time.
timeframe selection allows you to go to to a specific event and see logs for a time window both preceding and following that event. The default window is one minute, meaning the graph shows logs from thirty seconds before and the target time. Click the dropdown menu change the window.
![Selecting time ranges](/img/chronograf/log-viewer-specific-time.gif)
## Configuring the log viewer
The log viewer can be customized to fit your specific needs.
Open the log viewer configuration options by clicking the gear button in the top right corner of the log viewer. Once done, click **Save** to apply the changes.
<img src="/img/chronograf/v1.8/logs-log-viewer-config-options.png" alt="Log viewer configuration options" style="width:100%;max-width:819px;"/>
### Severity colors
Every log severity is assigned a color which is used in the display of log entries.
To customize colors, select a color from the available color dropdown.
### Table columns
Columns in the log viewer are auto-populated with all fields and tags associated with your log data.
Each column can be reordered, renamed, and hidden or shown.
### Severity format
"Severity Format" specifies how the severity of log entries is displayed in your log table.
Below are the options and how they appear in the log table:
| Severity Format | Display |
| --------------- |:------- |
| Dot | <img src="/img/chronograf/v1.8/logs-serverity-fmt-dot.png" alt="Log serverity format 'Dot'" style="display:inline;max-height:24px;"/> |
| Dot + Text | <img src="/img/chronograf/v1.8/logs-serverity-fmt-dot-text.png" alt="Log serverity format 'Dot + Text'" style="display:inline;max-height:24px;"/> |
| Text | <img src="/img/chronograf/v1.8/logs-serverity-fmt-text.png" alt="Log serverity format 'Text'" style="display:inline;max-height:24px;"/> |
### Truncate or wrap log messages
By default, text in Log Viewer columns is truncated if it exceeds the column width. You can choose to wrap the text instead to display the full content of each cell.
Select the **Truncate** or **Wrap** option to determine how text appears when it exceeds the width of the cell.
To copy the complete, untruncated log message, select the message cell and click **Copy**.
## Logs in dashboards
An incredibly powerful way to analyze log data is by creating dashboards that include log data.
This is possible by using the [Table visualization type](/chronograf/v1.8/guides/visualization-types/#table) to display log data in your dashboard.
![Correlating logs with other metrics](/img/chronograf/log-viewer-dashboard.gif)
This type of visualization allows you to quickly identify anomalies in other metrics and see logs associated with those anomalies.

35
content/chronograf/v1.8/guides/annotations.md Normal file
View File

@ -0,0 +1,35 @@
---
title: Using annotations in Chronograf views
description: Annotations provide contextual information by adding explanatory notes or comments to Chronograf graph views and charts in the user interface and dashboards.
menu:
chronograf_1_8:
name: Using annotations
weight: 50
parent: Guides
---
## Using annotations in the Chronograf interface
Annotations in Chronograf are notes of explanation or comments added to graph views by editors or administrators. Annotations can provide Chronograf users with useful contextual information about single points in time or time intervals. Users can use annotations to correlate the effects of important events, such as system changes or outages across multiple metrics, with Chronograf data.
When an annotation is added, a solid white line appears on all graph views for that point in time or an interval of time.
### Annotations example
The following screenshot of five graph views displays annotations for a single point in time and a time interval.
The text and timestamp for the single point in time can be seem above the annotation line in the graph view on the lower right.
The annotation displays "`Deploy v3.8.1-2`" and the time "`2018/28/02 15:59:30:00`".
![Annotations on multiple graph views](/img/chronograf/chrono-annotations-example.png)
**To add an annotation using the Chronograf user interface:**
1. Click the **Edit** button ("pencil" icon) on the graph view.
2. Click **Add Annotation** to add an annotation.
3. Move cursor to point of time and click or drag cursor to set an annotation.
4. Click **Edit** again and then click **Edit Annotation**.
5. Click the cursor on the annotation point or interval. The annotation text box appears above the annotation point or interval.
6. Click on `Name Me` in the annotation and type a note or comment.
7. Click **Done Editing**.
8. Your annotation is now available in all graph views.

43
content/chronograf/v1.8/guides/cloning-in-ui.md Normal file
View File

@ -0,0 +1,43 @@
---
title: Cloning dashboards and cells
description: Dashboards and their cells can be cloned, or copied, to be used as templates for easily creating new dashboards and cells.
menu:
chronograf_1_8:
weight: 70
parent: Guides
---
This guide explains how to clone, or duplicate, a dashboard or a cell for use as starting points for creating dashboards or cells using the copy as a template.
## Cloning dashboards
Dashboards in Chronograf can be cloned (or copied) to be used to create a dashboard based on the original. Rather than building a new dashboard from scratch, you can clone a dashboard and make changes to the dashboard copy.
### To clone a dashboard
1. On the **Dashboards** page, hover your cursor over the listing of the dashboard that you want to clone and click the **Clone** button that appears.
![Click the Clone button](/img/chronograf/clone-dashboard.png)
The cloned dashboard opens and displays the name of the original dashboard with `(clone)` after it.
![Cloned dashboard](/img/chronograf/clone-dashboard-clone.png)
You can now change the dashboard name and customize the dashboard.
## Cloning cells
Cells in Chronograf dashboards can be cloned, or copied, to quickly create a cell copy that can be edited for another use.
### To clone a cell
1. On the dashboard cell that you want to make a copy of, click the **Clone** icon and then confirm by clicking **Clone Cell**.
![Click the Clone icon](/img/chronograf/clone-cell-click-button.png)
2. The cloned cell appears in the dashboard displaying the nameof the original cell with `(clone)` after it.
![Cloned cell](/img/chronograf/clone-cell-cell-copy.png)
You can now change the cell name and customize the cell.

368
content/chronograf/v1.8/guides/configuring-alert-endpoints.md Normal file
View File

@ -0,0 +1,368 @@
---
title: Configuring Chronograf alert endpoints
aliases:
- /chronograf/v1.8/guides/configure-kapacitor-event-handlers/
description: Use Chronograf alert endpoints to send alert messages using Chronograf support for Alerta, Exec, HipChat, HTTP/Post, Kafka, Log, OpsGenie, PagerDuty, Sensu, Slack, SMTP/email, Talk, Telegram, TCP, and VictorOps.
menu:
chronograf_1_8:
name: Configuring alert endpoints
weight: 70
parent: Guides
---
Chronograf alert endpoints can be configured using the Chronograf user interface to create Kapacitor-based event handlers that send alert messages.
You can use Chronograf to send alert messages to specific URLs as well as to applications.
This guide offers step-by-step instructions for configuring Chronograf alert endpoints.
## Kapacitor event handlers supported in Chronograf
Chronograf integrates with [Kapacitor](/kapacitor/latest/), InfluxData's data processing platform, to send alert messages to event handlers.
Chronograf supports the following event handlers:
* Alerta
* Exec
* [HipChat](#hipchat)
* HTTP/Post
* [Kafka](#kafka)
* Log
* [OpsGenie](#opsgenie)
* [OpsGenie2](#opsgenie2)
* [PagerDuty](#pagerduty)
* [PagerDuty2](#pagerduty2)
* [Pushover](#pushover)
* Sensu
* [Slack](#slack)
* SMTP/Email
* Talk
* [Telegram](#telegram)
* TCP
* VictorOps
To configure a Kapacitor event handler in Chronograf, [install Kapacitor](/kapacitor/latest/introduction/installation/) and [connect it to Chronograf](/kapacitor/latest/working/kapa-and-chrono/#add-a-kapacitor-instance).
The **Configure Kapacitor** page includes the event handler configuration options.
## Alert endpoint configurations
Alert endpoint configurations appear on the Chronograf Configure Kapacitor page.
You must have a connected Kapacitor instance to access the configurations.
For more information, see [Kapacitor installation instructions](/kapacitor/latest/introduction/installation/) and how to [connect a Kapacitor instance](/kapacitor/latest/working/kapa-and-chrono/#add-a-kapacitor-instance) to Chronograf.
Note that the configuration options in the **Configure alert endpoints** section are not all-inclusive.
Some event handlers allow users to customize event handler configurations per [alert rule](/chronograf/latest/guides/create-a-kapacitor-alert/).
For example, Chronograf's Slack integration allows users to specify a default channel in the **Configure alert endpoints** section and a different channel for individual alert rules.
### HipChat
[HipChat](https://www.hipchat.com/) is an Atlassian web service for group chat, video chat, and screen sharing.
Configure Chronograf to send alert messages to a HipChat room.
The sections below describe each configuration option.
#### Subdomain
The HipChat subdomain name.
Identify the subdomain in your HipChat URL;
for example, the subdomain in the Hipchat URL `https://example-hi.hipchat.com/home` is `example-hi`.
#### Room
The HipChat room name.
Chronograf sends alert messages to this room.
#### Token
A HipChat API access token for sending notifications.
The following steps describe how to create the API access token:
1. From the **HipChat home page** (`https://<your-subdomain>.hipchat.com/home`), access **Account settings** by clicking on the person icon in the top right corner.
2. Select **API access** from the items in the left menu sidebar.
3. Under **Create new token**, enter a label for your token (it can be anything).
4. Under **Create new token**, select **Send Notification** as the **Scope**.
5. Click **Create**.
Your token appears in the table just above the **Create new token** section:
![HipChat token](/img/chronograf/latest/g-eventhandlers-hipchattoken.png)
### Kafka
**To configure a Kafka alert endpoint:**
1. In the **Configure Alert Endpoints** of the **Configure Kapacitor Connection** page, click the **Kafka** tab.
2. Enter the following:
* **ID**: Unique identifier for a Kafka cluster. Default is `localhost`.
* **Brokers**: List of Kafka broker addresses, using the `host:port` format.
* **Timeout**: The maximum amount of time to wait before flushing an incomplete batch. Default is `10s`.
* **Batch Size**: Number of messages batched before sending to Kafka. Default is `100`.
* **Batch Timeout**: Timeout period for the batch. Default is `1s`.
* **Use SSL**: Check to enable SSL communication.
* **SSL CA**: Path to the SSL CA (certificate authority) file.
* **SSL Cert**: Path to the SSL host certificate.
* **SSL Key**: Path to the SSL certificate private key file.
* **Insecure Skip Verify**: Check to use SSL, but skip chain and host verification. Required if using a self-signed certificate.
3. Click **Save Changes** to save the configuration settings.
4. Click **Send Test Alert** to verify the configuration.
See [Kafka event handler (Kapacitor)](/kapacitor/latest/event_handlers/kafka/) in the Kapacitor documentation for details about enabling OpsGenie services using TICKscripts.
### OpsGenie
The original OpsGenie alert endpoint is deprecated -- use the [OpsGenie2](#opsgenie2) alert endpoint.
> **Note:** Support for OpsGenie Events API 1.0 is deprecated. As [noted by OpGenie](https://docs.opsgenie.com/docs/migration-guide-for-alert-rest-api), API v1 will be inaccessible for all customers as of June 30, 2018.
### OpsGenie2
Send an incident alert to OpsGenie teams and recipients using the Chronograf alert endpoint.
**To configure a OpsGenie alert endpoint:**
1. In the **Configure Alert Endpoints** of the **Configure Kapacitor Connection** page, click the **OpsGenie** tab.
2. Enter the following information:
* **API Key**: API key (or GenieKey). The API Key can be found by signing into your [OpsGenie account](https://app.opsgenie.com/auth/login) and selecting the **Settings** menu option in the **Admin** menu.
* **Teams**: List of [OpsGenie teams](https://docs.opsgenie.com/docs/teams) to be alerted.
* **Recipients** field, enter the list of [OpsGenie team members](https://docs.opsgenie.com/docs/teams#section-team-members)) to receive alerts.
4. Click **Save Changes** to save the configuration settings.
5. Click **Send Test Alert** to verify the configuration.
See [Alert API](https://docs.opsgenie.com/docs/alert-api) in the OpsGenie documentation for details on the OpsGenie Alert API
See [OpsGenie V2 event handler](/kapacitor/latest/event_handlers/opsgenie/v2/) in the Kapacitor documentation for details about the OpsGenie V2 event handler.
See the [AlertNode (Kapacitor TICKscript node) - OpsGenie v2](/kapacitor/latest/nodes/alert_node/#opsgenie-v2) in the Kapacitor documentation for details about enabling OpsGenie services using TICKscripts.
### PagerDuty
The original PagerDuty alert endpoint is deprecated -- use the [PagerDuty2](#pagerduty2) alert endpoint.
### PagerDuty2
Send an alerts about recognized events to PagerDuty using the Chronograf PagerDuty alert endpoint.
**To configure a PagerDuty alert endpoint:**
1. In the **Configure Alert Endpoints** of the **Configure Kapacitor Connection** page, click the **PagerDuty** tab
2. Enter the following:
* **Routing Key**: GUID of your PagerDuty Events API V2 integration, listed as "Integration Key" on the Events API V2 integration's detail page. See [Create a new service](https://support.pagerduty.com/docs/services-and-integrations#section-create-a-new-service) in the PagerDuty documentation details on getting an "Integration Key" (`routing_key`).
* **PagerDuty URL**: URL used to POST a JSON body representing the event. This value should not be changed. Valid value is `https://events.pagerduty.com/v2/enqueue`.
* **Configuration Enabled**: Check to enable this configuration.
3. Click **Save Changes** to save the configuration settings.
4. Click **Send Test Alert** to verify the configuration.
See the [PagerDuty Events API V2 Overview](https://v2.developer.pagerduty.com/docs/events-api-v2) for details on the PagerDuty Events API and recognized event types (`trigger`, `acknowledge`, and `resolve`).
See [AlertNode (Kapacitor TICKscript node) - PagerDuty v2](/kapacitor/latest/nodes/alert_node/#pagerduty-v2) in the Kapacitor documentation for details about enabling a new "Generic API" service using TICKscripts.
### Pushover
Configure Chronograf to send Pushover event handler alerts.
#### User Key
Enter your Pushover USER_TOKEN.
#### Token
Enter your Pushover API token.
#### Pushover URL
The URL for the Pushover API. The default value is `https://api.pushover.net/1/messages.json`.
#### Configuration Enabled
Check the **Configuration Enabled** checkbox to enable this configuration.
#### Save Changes
Click **Save Changes** to save the Pushover configuration.
#### Send Test Alert
Click **Send Test Alert** to test your alert endpoint configuration.
### Slack
[Slack](https://slack.com/) is a popular messaging app for teams.
Configure Chronograf to send alerts to an existing Slack channel or as a [direct messages (DMs)](https://get.slack.help/hc/en-us/articles/212281468-Direct-messages-and-group-DMs).
The sections below describe each configuration option.
#### Nickname this Configuration
Add a unique name for a Slack endpoint if you configure more than one Slack alert endpoint. This field is not available unless at least one Slack endpoint has been configured.
#### Slack WebHook URL
The optional Slack WebHook URL allows you to post messages from Chronograf to Slack.
The following steps describe how to create a Slack WebHook URL:
1. Visit [Incoming Webhooks](https://api.slack.com/incoming-webhooks) for details on how to send data into Slack in realtime.
2. Follow the steps on this page to create an [incoming webhook integration](https://my.slack.com/services/new/incoming-webhook/) in your Slack workspace.
3. Select a channel or DM in the `Post to Channel` section.
This step is necessary for creating the WebHook.
Note that you can configure Chronograf to send messages to a different Slack channel or DM later.
4. On your [Incoming Webhooks](ttps://my.slack.com/services/new/incoming-webhook/) page, click **Add Incoming WebHooks integration**.
5. In the **Slack Webhook URL** field, enter the Slack WebHook URL that is listed as **Webhook URL** on the **Incoming Webhooks** page.
#### Slack Channel (optional)
Chronograf sends alert messages to the specified Slack channel, or DM (direct message).
Prefix the Slack channel with `#`, or the DM (direct message) with `@`. For example, `#chronocats` is a channel and `@chronothan` is a DM.
If this field is empty (not specified), Chronograf sends alert messages to the channel or DM selected for the **Slack WebHook URL** or to the channel or DM specified in the [alert rule](/chronograf/v1.8/guides/create-a-kapacitor-alert/).
The channel or DM specified in the alert rule takes precedence over both the `Slack Channel` configuration option and the WebHook URL configuration.
#### Configuration Enabled
Check the **Configuration Enabled** checkbox to enable this configuration.
#### Save Changes
Click **Save Changes** to save the Slack configuration.
#### Send Test Alert
Click **Send Test Alert** to test your alert endpoint configuration.
#### Add Another Config
Click **Add Another Config** to add additional Slack alert endpoints. Each additional Slack alert endpoints requires you to specify a unique identifier in the **Nickname this Configuration** field that becomes enabled after the initial Slack alert endpoint is configured.
### Telegram
[Telegram](https://telegram.org/) is a popular messaging app.
Configure Chronograf to send alert messages to an existing Telegram bot.
The sections below describe each configuration option.
![Telegram configuration](/img/chronograf/v1.8/g-eventhandlers-telegram.png)
#### Telegram bot
Chronograf sends alerts to an existing Telegram bot.
The following steps describe how to create a new Telegram bot:
1. Search for the `@BotFather` username in your Telegram application
2. Click `Start` to begin a conversation with `@BotFather`
3. Send `/newbot` to `@BotFather`
`@BotFather` responds:
Alright, a new bot. How are we going to call it? Please choose a name for your bot.
`@BotFather` will prompt you through the rest of the bot-creation process;
feel free to follow his directions or continue with our version of the steps below.
Both setups result in success!
4. Send your bot's name to `@BotFather`
Your bot name can be anything.
Note that this is not your bot's Telegram `@username`;
you'll create the username in step 5.
`@BotFather` responds:
Good. Now let's choose a username for your bot. It must end in `bot`. Like this, for example: TetrisBot or tetris_bot.
5. Send your bot's username to `@BotFather`
Your bot's username must end in `bot`.
For example: `mushroomKap_bot`.
`BotFather` responds:
Done! Congratulations on your new bot. You will find it at t.me/<bot-username>. You can now add a description, about section and profile picture for your bot, see /help for a list of commands. By the way, when you've finished creating your cool bot, ping our Bot Support if you want a better username for it. Just make sure the bot is fully operational before you do this.
Use this token to access the HTTP API:
`<API-access-token>`
For a description of the Bot API, see this page: https://core.telegram.org/bots/api
6. Begin a conversation with your bot
Click on the `t.me/<bot-username>` link in `@BotFather`'s response
and click `Start` at the bottom of your Telegram application.
Your newly-created bot will appear in the chat list on the left side of the application.
#### Token
The Telegram API access token.
The following section describes how to identify or create the API access token.
Telegram's `@BotFather` bot sent you an API access token when you created your bot.
See the `@BotFather` response in step 5 of the previous section for where to find your token.
If you can't find the API access token, create a new token with the steps
below:
1. Send `/token` to `@BotFather`
2. Select the relevant bot at the bottom of your Telegram application
`@BotFather` responds with a new API access token:
You can use this token to access HTTP API:
<API-access-token>
For a description of the Bot API, see this page: https://core.telegram.org/bots/api
#### Chat ID
The Telegram chat ID.
The following steps describe how to identify your chat ID:
1. Paste the following link in your browser.
Replace `<API-access-token>` with the API access token that you identified or created in the previous section:
`https://api.telegram.org/bot<API-access-token>/getUpdates?offset=0`
2. Send a message to your bot.
Send a message to your bot in the Telegram application.
The message text can be anything; your chat history must include at least one message to get your chat ID.
3. Refresh your browser.
4. Identify the chat ID.
Identify the numerical chat ID in the browser.
In the example below, the chat ID is `123456789`.
```
{"ok":true,"result":[{"update_id":XXXXXXXXX,
"message":{"message_id":2,"from":{"id":123456789,"first_name":"Mushroom","last_name":"Kap"},"chat":{"id":123456789,"first_name":"Mushroom","last_name":"Kap","type":"private"},"date":1487183963,"text":"hi"}}]}
```
#### Select the alert message format
Select **Markdown** (default) or **HTML** to specify the formatting for your alert messages.
#### Disable link previews
Select this option to disable [link previews](https://telegram.org/blog/link-preview) in alert messages.
#### Disable notifications
Select this option to disable notifications on iOS Devices and sounds on Android devices.
Android users will continue to receive notifications.

130
content/chronograf/v1.8/guides/create-a-dashboard.md Normal file
View File

@ -0,0 +1,130 @@
---
title: Creating Chronograf dashboards
description: This tutorial guides you quickly through the essential steps required to create custom Chronograf dashboards for use with InfluxDB and the InfluxData Platform.
menu:
chronograf_1_8:
name: Creating dashboards
weight: 30
parent: Guides
---
Chronograf offers a complete dashboard solution for visualizing your data and monitoring your infrastructure:
* View [pre-created dashboards](/chronograf/latest/guides/using-precreated-dashboards) from the Host List page. Dashboards are available depending on which Telegraf input plugins you have enabled. These pre-created dashboards cannot be cloned or edited.
* Create custom dashboards from scratch by building queries in the Data Explorer, as described [below](#build-a-dashboard).
* Import dashboard templates when you add or update a connection in Chronograf. See [Dashboard templates](#dashboard-templates) for details.
By the end of this guide, you'll be aware of the tools available to you for creating dashboards similar to this example:
![Oh, the Chronobilities](/img/chronograf/v1.8/g-dashboard-possibilities.png)
## Requirements
To perform the tasks in this guide, you must have a working Chronograf instance that is connected to an InfluxDB source.
Data is accessed using the Telegraf [system ](https://github.com/influxdata/telegraf/tree/master/plugins/inputs/system) input plugins.
For more information, see [Configuring Chronograf](/chronograf/latest/administration/configuration).
## Build a Dashboard
Click **Dashboards** in the navigation bar and then click the **Create Dashboard** button.
A new dashboard is created and ready to begin adding cells.
### Step 1: Name your dashboard
Click **Name This Dashboard** and type a new name. In this guide, "ChronoDash" is used.
### Step 2: Enter cell editor mode
In the first cell, titled "Untitled Cell", click **Edit**
to open the cell editor mode.
![Edit your cell](/img/chronograf/g-dashboard-cell-edit.png)
### Step 3: Create your query
Click the **Add a Query** button to create an [InfluxQL](/influxdb/latest/query_language/) query.
In query editor mode, use the builder to select from your existing data and allow Chronograf to format the query for you.
Alternatively, manually enter and edit a query.
Chronograf allows you to move seamlessly between using the builder and manually editing the query; when possible, the interface automatically populates the builder with the information from your raw query.
For our example, the query builder is used to generate a query that shows the average idle CPU usage grouped by host (in this case, there are three hosts).
By default, Chronograf applies the [`MEAN()` function](/influxdb/latest/query_language/functions/#mean) to the data, groups averages into auto-generated time intervals (`:interval:`), and shows data for the past hour (`:dashboardTime:`).
Those defaults are configurable using the query builder or by manually editing the query.
In addition, the time range (`:dashboardTime:` and `:upperDashboardTime:`) are [configurable on the dashboard](#step-6-configure-your-dashboard).
![Build your query](/img/chronograf/v1.8/g-dashboard-builder.png)
### Step 4: Choose your visualization type
Chronograf supports many different [visualization types](/chronograf/latest/guides/visualization-types/). To choose a visualization type, click **Visualization** and select **Step-Plot Graph**.
![Visualization type](/img/chronograf/v1.8/g-dashboard-visualization.png)
### Step 5: Save your cell
Click **Save** (the green checkmark icon) to save your cell.
> ***Note:*** If you navigate away from this page without clicking Save, your work will not be saved.
### Step 6: Configure your dashboard
#### Customize cells
* You can change the name of the cell from "Untitled Cell" by returning to the cell editor mode, clicking on the name, and renaming it. Remember to save your changes.
* **Move** your cell around by clicking its top bar and dragging it around the page
* **Resize** your cell by clicking and dragging its bottom right corner
#### Explore cell data
* **Zoom** in on your cell by clicking and dragging your mouse over the area of interest
* **Pan** over your cell data by pressing the shift key and clicking and dragging your mouse over the graph
* **Reset** your cell by double-clicking your mouse in the cell window
> **Note:**
These tips only apply to the line, stacked, step-plot, and line+stat [visualization types](/chronograf/latest/guides/visualization-types/).
#### Configure dashboard-wide settings
* Change the dashboard's *selected time* at the top of the page - the default time is **Local**, which uses your browser's local time. Select **UTC** to use Coordinated Universal Time.
> **Note:** If your organization spans multiple time zones, we recommend using UTC (Coordinated Universal Time) to ensure that everyone sees metrics and events for the same time.
* Change the dashboard's *auto-refresh interval* at the top of the page - the default interval selected is **Every 10 seconds**.
> **Note:** A dashboard's refresh rate persists in local storage, so the default refresh rate is only used when a refresh rate isn't found in local storage.
* Modify the dashboard's *time range* at the top of the page - the default range is **Past 15 minutes**.
Now, you're ready to experiment and complete your dashboard by creating, editing, and repositioning more cells!
## Dashboard templates
Select from a variety of dashboard templates to import and customize based on which Telegraf plugins you have enabled, such as the following examples:
<img src="/img/chronograf/v1.8/protoboard-kubernetes.png" style="width:100%; max-width:600px;">
<img src="/img/chronograf/v1.8/protoboard-mysql.png" style="width:100%; max-width:600px;">
<img src="/img/chronograf/v1.8/protoboard-system.png" style="width:100%; max-width:600px;">
<img src="/img/chronograf/v1.8/protoboard-vsphere.png" style="width:100%; max-width:600px;">
**To import dashboard templates:**
1. From the Configuration page, click **Add Connection** or select an existing connection to edit it.
2. In the **InfluxDB Connection** window, enter or verify your connection details and click **Add** or **Update Connection**.
3. In the **Dashboards** window, select from the available dashboard templates to import based on which Telegraf plugins you have enabled.
<img src="/img/chronograf/v1.8/protoboard-select.png" style="width:100%; max-width:500px;">
4. Click **Create (x) Dashboards**.
5. Edit, clone, or configure the dashboards as needed.
## Extra Tips
### Full screen mode
View your dashboard in full screen mode by clicking on the full screen icon in the top right corner of your dashboard.
To exit full screen mode, press the Esc key.
### Template variables
Dashboards support template variables.
See the [Dashboard Template Variables](/chronograf/latest/guides/dashboard-template-variables/) guide for more information.

158
content/chronograf/v1.8/guides/create-alert-rules.md Normal file
View File

@ -0,0 +1,158 @@
---
title: Creating Chronograf alert rules
description: Creating Chronograf alert rules, specifying time series data and thresholds. Example sends alerts to a Slack channel.
aliases:
- /chronograf/v1.8/guides/create-a-kapacitor-alert/
menu:
chronograf_1_8:
name: Creating alert rules
weight: 60
parent: Guides
---
Chronograf provides a user interface for [Kapacitor](/kapacitor/latest/), InfluxData's processing framework for creating alerts, ETL jobs (running extract, transform, load), and detecting anomalies in your data.
Chronograf alert rules correspond to Kapacitor tasks that trigger alerts whenever certain conditions are met.
Behind the scenes, these tasks are stored as [TICKscripts](/kapacitor/latest/tick/) that can be edited manually or through Chronograf.
Common alerting use cases that can be managed using Chronograf include:
* Thresholds with static ceilings, floors, and ranges.
* Relative thresholds based on unit or percentage changes.
* Deadman switches.
Complex alerts and other tasks can be defined directly in Kapacitor as TICKscripts, but can be viewed and managed within Chronograf.
This guide walks through creating a Chronograf alert rule that sends an alert message to an existing [Slack](https://slack.com/) channel whenever your idle CPU usage crosses the 80% threshold.
## Requirements
[Getting started with Chronograf](/chronograf/latest/introduction/getting-started/) offers step-by-step instructions for each of the following requirements:
* Downloaded and install the entire TICKstack (Telegraf, InfluxDB, Chronograf, and Kapacitor).
* Configure Telegraf to collect data using the InfluxDB [system statistics](https://github.com/influxdata/telegraf/tree/master/plugins/inputs/system) input plugin and write data to your InfluxDB instance.
* [Create a Kapacitor connection in Chronograf](/chronograf/latest/introduction/getting-started/#4-connect-chronograf-to-kapacitor).
* Slack is available and configured as an [event handler](/chronograf/latest/troubleshooting/frequently-asked-questions/#what-kapacitor-event-handlers-are-supported-in-chronograf) in Chronograf.
See the [Configuring Kapacitor Event Handlers](/chronograf/latest/guides/configuring-alert-endpoints/) guide for detailed configuration instructions.
## Configuring Chronograf alert rules
Navigate to the **Manage Tasks** page under **Alerting** in the left navigation, then click **+ Build Alert Rule** in the top right corner.
![Navigate to Manage Tasks](/img/chronograf/v1.8/alerts-manage-tasks-nav.png)
The **Manage Tasks** page is used to create and edit your Chronograf alert rules.
The steps below guide you through the process of creating a Chronograf alert rule.
![Empty Rule Configuration](/img/chronograf/v1.8/alerts-rule-builder.png)
### Step 1: Name the alert rule
Under **Name this Alert Rule** provide a name for the alert.
For this example, use "Idle CPU Usage" as your alert name.
### Step 2: Select the alert type
Choose from three alert types under the **Alert Types** section of the Rule Configuration page:
_**Threshold**_
Alert if data crosses a boundary.
_**Relative**_
Alert if data changes relative to data in a different time range.
_**Deadman**_
Alert if InfluxDB receives no relevant data for a specified time duration.
For this example, select the **Threshold** alert type.
### Step 3: Select the time series data
Choose the time series data you want the Chronograf alert rule to use.
Navigate through databases, measurements, fields, and tags to select the relevant data.
In this example, select the `telegraf` [database](/influxdb/latest/concepts/glossary/#database), the `autogen` [retention policy](/influxdb/latest/concepts/glossary/#retention-policy-rp), the `cpu` [measurement](/influxdb/latest/concepts/glossary/#measurement), and the `usage_idle` [field](/influxdb/latest/concepts/glossary/#field).
![Select your data](/img/chronograf/v1.8/alerts-time-series.png)
### Step 4: Define the rule condition
Define the threshold condition.
Condition options are determined by the [alert type](#step-2-select-the-alert-type).
For this example, the alert conditions are if `usage_idle` is less than `80`.
![Create a condition](/img/chronograf/v1.8/alerts-conditions.png)
The graph shows a preview of the relevant data and the threshold number.
By default, the graph shows data from the past 15 minutes.
Adjusting the graph's time range is helpful when determining a reasonable threshold number based on your data.
> We set the threshold number to `80` for demonstration purposes.
> Setting the threshold for idle CPU usage to a high number ensures that we'll be able to see the alert in action.
> In practice, you'd set the threshold number to better match the patterns in your data and your alerting needs.
### Step 5: Select and configure the alert handler
The **Alert Handler** section determines where the system sends the alert (the event handler)
Chronograf supports several event handlers.
Each handler has unique configurable options.
For this example, choose the **slack** alert handler and enter the desired options.
![Select the alert handler](/img/chronograf/v1.8/alerts-configure-handlers.png)
> Multiple alert handlers can be added to send alerts to multiple endpoints.
### Step 6: Configure the alert message
The alert message is the text that accompanies an alert.
Alert messages are templates that have access to alert data.
Available data templates appear below the message text field.
As you type your alert message, clicking the data templates will insert them at end of whatever text has been entered.
In this example, use the alert message, `Your idle CPU usage is {{.Level}} at {{ index .Fields "value" }}.`.
![Specify event handler and alert message](/img/chronograf/v1.8/alerts-message.png)
*View the Kapacitor documentation for more information about [message template data](/kapacitor/latest/nodes/alert_node/#message).*
### Step 7: Save the alert rule
Click **Save Rule** in the top right corner and navigate to the **Manage Tasks** page to see your rule.
Notice that you can easily enable and disable the rule by toggling the checkbox in the **Enabled** column.
![See the alert rule](/img/chronograf/v1.8/alerts-view-rules.png)
Next, move on to the section below to experience your alert rule in action.
## Viewing alerts in practice
### Step 1: Create some load on your system
The purpose of this step is to generate enough load on your system to trigger an alert.
More specifically, your idle CPU usage must dip below `80%`.
On the machine that's running Telegraf, enter the following command in the terminal to start some `while` loops:
```
while true; do i=0; done
```
Let it run for a few seconds or minutes before terminating it.
On most systems, kill the script by using `Ctrl+C`.
### Step 2: View the alerts
Go to the Slack channel that you specified in the previous section.
In this example, it's the `#chronocats` channel.
Assuming the first step was successful, `#ohnos` should reveal at least two alert messages:
* The first alert message indicates that your idle CPU usage was `CRITICAL`, meaning it dipped below `80%`.
* The second alert message indicates that your idle CPU usage returned to an `OK` level of `80%` or above.
![See the alerts](/img/chronograf/v1.8/alerts-slack-notifications.png)
You can also see alerts on the **Alert History** page available under **Alerting** in the left navigation.
![Chronograf alert history](/img/chronograf/v1.8/alerts-history.png)
That's it! You've successfully used Chronograf to configure an alert rule to monitor your idle CPU usage and send notifications to Slack.

400
content/chronograf/v1.8/guides/dashboard-template-variables.md Normal file
View File

@ -0,0 +1,400 @@
---
title: Using dashboard template variables
description: Chronograf dashboards support template variables that let you modify queries through simple user interactions. Variable types include databases, measurements, field keys, tag keys, tag values, comma-separated values (CSV), maps, custom meta queries, and text.
aliases:
- /chronograf/v1.8/introduction/templating/
- /chronograf/v1.8/templating/
menu:
chronograf_1_8:
weight: 90
parent: Guides
---
Chronograf's dashboard template variables allow you to alter specific components of cells' queries
without having to edit the queries, making it easy to interact with your dashboard cells and explore your data.
## Using template variables
Template variables are used in cell queries and titles when creating Chronograf dashboards.
Within the query, template variables are referenced by surrounding the variable name with colons (`:`).
```sql
SELECT :variable_name: FROM "telegraf"."autogen".:measurement: WHERE time < :dashboardTime:
```
You can use either [predefined template variables](#predefined-template-variables)
or [custom template variables](#create-custom-template-variables).
Variable values are then selected in your dashboard user-interface (UI).
![Using template variables](/img/chronograf/v1.8/template-vars-use.gif)
## Predefined template variables
Chronograf includes predefined template variables controlled by elements in the Chrongraf UI.
These template variables can be used in any of your cells' queries.
[`:dashboardTime:`](#dashboardtime)
[`:upperDashboardTime:`](#upperdashboardtime)
[`:interval:`](#interval)
### dashboardTime
The `:dashboardTime:` template variable is controlled by the "time" dropdown in your Chronograf dashboard.
<img src="/img/chronograf/v1.8/template-vars-time-dropdown.png" style="width:100%;max-width:549px;" alt="Dashboard time selector"/>
If using relative times, it represents the time offset specified in the dropdown (-5m, -15m, -30m, etc.) and assumes time is relative to "now".
If using absolute times defined by the date picker, `:dashboardTime:` is populated with lower threshold.
```sql
SELECT "usage_system" AS "System CPU Usage"
FROM "telegraf".."cpu"
WHERE time > :dashboardTime:
```
> In order to use the date picker to specify a particular time range in the past
> which does not include "now", the query should be constructed using `:dashboardTime:`
> as the lower limit and [`:upperDashboardTime:`](#upperdashboardtime) as the upper limit.
### upperDashboardTime
The `:upperDashboardTime:` template variable is defined by the upper time limit specified using the date picker.
<img src="/img/chronograf/v1.8/template-vars-date-picker.png" style="width:100%;max-width:762px;" alt="Dashboard date picker"/>
It will inherit `now()` when using relative time frames or the upper time limit when using absolute timeframes.
```sql
SELECT "usage_system" AS "System CPU Usage"
FROM "telegraf".."cpu"
WHERE time > :dashboardTime: AND time < :upperDashboardTime:
```
### interval
The `:interval:` template variable is defined by the interval dropdown in the Chronograf dashboard.
<img src="/img/chronograf/v1.8/template-vars-interval-dropdown.png" style="width:100%;max-width:549px;" alt="Dashboard interval selector"/>
In cell queries, it should be used in the `GROUP BY time()` clause that accompanies aggregate functions:
```sql
SELECT mean("usage_system") AS "Average System CPU Usage"
FROM "telegraf".."cpu"
WHERE time > :dashboardtime:
GROUP BY time(:interval:)
```
## Create custom template variables
Template variables are essentially an array of potential values used to populate parts of your cells' queries.
Chronograf lets you create custom template variables powered by meta queries or CSV uploads that return an array of possible values.
To create a template variable:
1. Click on **Template Variables** at the top of your dashboard, then **+ Add Variable**.
2. Select a data source from the **Data Source** dropdown menu.
3. Provide a name for the variable.
4. Select the [variable type](#template-variable-types).
The type defines the method for retrieving the array of possible values.
5. View the list of potential values and select a default.
If using the CSV or Map types, upload or input the CSV with the desired values in the appropriate format then select a default value.
6. Click **Create**.
Once created, the template variable can be used in any of your cell's queries or titles
and a dropdown for the variable will be included at the top of your dashboard.
## Template Variable Types
Chronograf supports the following template variable types:
[Databases](#databases)
[Measurements](#measurements)
[Field Keys](#field-keys)
[Tag Keys](#tag-keys)
[Tag Values](#tag-values)
[CSV](#csv)
[Map](#map)
[Custom Meta Query](#custom-meta-query)
[Text](#text)
### Databases
Database template variables allow you to select from multiple target [databases](/influxdb/latest/concepts/glossary/#database).
_**Database meta query**_
Database template variables use the following meta query to return an array of all databases in your InfluxDB instance.
```sql
SHOW DATABASES
```
_**Example database variable in a cell query**_
```sql
SELECT "purchases" FROM :databaseVar:."autogen"."customers"
```
#### Database variable use cases
Database template variables are good when visualizing multiple databases with similar or identical data structures. They allow you to quickly switch between visualizations for each of your databases.
### Measurements
Vary the target [measurement](/influxdb/latest/concepts/glossary/#measurement).
_**Measurement meta query**_
Measurement template variables use the following meta query to return an array of all measurements in a given database.
```sql
SHOW MEASUREMENTS ON database_name
```
_**Example measurement variable in a cell query**_
```sql
SELECT * FROM "animals"."autogen".:measurementVar:
```
#### Measurement variable use cases
Measurement template variables allow you to quickly switch between measurements in a single cell or multiple cells in your dashboard.
### Field Keys
Vary the target [field key](/influxdb/latest/concepts/glossary/#field-key).
_**Field key meta query**_
Field key template variables use the following meta query to return an array of all field keys in a given measurement from a given database.
```sql
SHOW FIELD KEYS ON database_name FROM measurement_name
```
_**Example field key var in a cell query**_
```sql
SELECT :fieldKeyVar: FROM "animals"."autogen"."customers"
```
#### Field key variable use cases
Field key template variables are great if you want to quickly switch between field key visualizations in a given measurement.
### Tag Keys
Vary the target [tag key](/influxdb/latest/concepts/glossary/#tag-key).
_**Tag key meta query**_
Tag key template variables use the following meta query to return an array of all tag keys in a given measurement from a given database.
```sql
SHOW TAG KEYS ON database_name FROM measurement_name
```
_**Example tag key variable in a cell query**_
```sql
SELECT "purchases" FROM "animals"."autogen"."customers" GROUP BY :tagKeyVar:
```
#### Tag key variable use cases
Tag key template variables are great if you want to quickly switch between tag key visualizations in a given measurement.
### Tag Values
Vary the target [tag value](/influxdb/latest/concepts/glossary/#tag-value).
_**Tag value meta query**_
Tag value template variables use the following meta query to return an array of all values associated with a given tag key in a specified measurement and database.
```sql
SHOW TAG VALUES ON database_name FROM measurement_name WITH KEY tag_key
```
_**Example tag value variable in a cell query**_
```sql
SELECT "purchases" FROM "animals"."autogen"."customers" WHERE "species" = :tagValueVar:
```
#### Tag value variable use cases
Tag value template variables are great if you want to quickly switch between tag value visualizations in a given measurement.
### CSV
Vary part of a query with a customized list of comma-separated values (CSV).
_**Example CSVs:**_
```csv
value1, value2, value3, value4
```
```csv
value1
value2
value3
value4
```
> Since string field values [require single quotes in InfluxQL](/influxdb/latest/troubleshooting/frequently-asked-questions/#when-should-i-single-quote-and-when-should-i-double-quote-in-queries), string values should be wrapped in single quotes.
>```csv
'string1','string2','string3','string4'
```
_**Example CSV variable in a cell query**_
```sql
SELECT "purchases" FROM "animals"."autogen"."customers" WHERE "petname" = :csvVar:
```
#### CSV variable use cases
CSV template variables are great when the array of values necessary for your variable can't be pulled from InfluxDB using a meta query.
They allow you to use custom variable values.
### Map
Vary part of a query with a customized list of key-value pairs in CSV format.
They key of each key-value pair is used to populate the template variable dropdown in your dashboard.
The value is used when processing cells' queries.
_**Example CSV:**_
```csv
key1,value1
key2,value2
key3,value3
key4,value4
```
<img src="/img/chronograf/v1.8/template-vars-map-dropdown.png" style="width:100%;max-width:140px;" alt="Map variable dropdown"/>
> If values are meant to be used as string field values, wrap them in single quote ([required by InfluxQL](/influxdb/latest/troubleshooting/frequently-asked-questions/#when-should-i-single-quote-and-when-should-i-double-quote-in-queries)). This only pertains to values. String keys do not matter.
>```csv
key1,'value1'
key2,'value2'
key3,'value3'
key4,'value4'
```
_**Example Map variable in a cell query**_
```sql
SELECT "purchases" FROM "animals"."autogen"."customers" WHERE "customer" = :mapVar:
```
#### Map variable use cases
Map template variables are good when you need to map or alias simple names or keys to longer or more complex values.
For example, you may want to create a `:customer:` variable that populates your cell queries with a long, numeric customer ID (`11394850823894034209`).
With a map variable, you can alias simple names to complex values, so your list of customers would look something like:
```
Apple,11394850823894034209
Amazon,11394850823894034210
Google,11394850823894034211
Microsoft,11394850823894034212
```
The customer names would populate your template variable dropdown rather than the customer IDs.
### Custom Meta Query
Vary part of a query with a customized meta query that pulls a specific array of values from InfluxDB.
These variables allow you to pull a highly customized array of potential values and offer advanced functionality such as [filtering values based on other template variables](#filtering-template-variables-with-other-template-variables).
<img src="/img/chronograf/v1.8/template-vars-custom-meta-query.png" style="width:100%;max-width:667px;" alt="Custom meta query"/>
_**Example custom meta query variable in a cell query**_
```sql
SELECT "purchases" FROM "animals"."autogen"."customers" WHERE "customer" = :customMetaVar:
```
#### Custom meta query variable use cases
Custom meta query template variables should be used any time you are pulling values from InfluxDB, but the pre-canned template variable types aren't able to return the desired list of values.
### Text
Vary a part of a query with a single string of text.
There is only one value per text variable, but this value is easily altered.
#### Text variable use cases
Text template variables allow you to dynamically alter queries, such as adding or altering `WHERE` clauses, for multiple cells at once.
You could also use a text template variable to alter a regular expression used in multiple queries.
They are great when troubleshooting incidents that affect multiple visualized metrics.
## Reserved variable names
The following variable names are reserved and cannot be used when creating template variables.
Chronograf accepts [template variables as URL query parameters](#defining-template-variables-in-the-url)
as well as many other parameters that control the display of graphs in your dashboard.
These names are either [predefined variables](#predefined-template-variables) or would
conflict with existing URL query parameters.
`:database:`
`:measurement:`
`:dashboardTime:`
`:upperDashboardTime:`
`:interval:`
`:upper:`
`:lower:`
`:zoomedUpper:`
`:zoomedLower:`
`refreshRate:`
## Advanced template variable usage
### Filtering template variables with other template variables
[Custom meta query template variables](#custom-meta-query) allow you to filter the array of potential variable values using other existing template variables.
For example, let's say you want to list all the field keys associated with a measurement, but want to be able to change the measurement:
1. Create a template variable named `:measurementVar:` _(the name "measurement" is [reserved]( #reserved-variable-names))_ that uses the [Measurements](#measurements) variable type to pull in all measurements from the `telegraf` database.
<img src="/img/chronograf/v1.8/template-vars-measurement-var.png" style="width:100%;max-width:667px;" alt="measurementVar"/>
2. Create a template variable named `:fieldKey:` that uses the [custom meta query](#custom-meta-query) variable type.
The following meta query pulls a list of field keys based on the existing `:measurementVar:` template variable.
```sql
SHOW FIELD KEYS ON telegraf FROM :measurementVar:
```
<img src="/img/chronograf/v1.8/template-vars-fieldkey.png" style="width:100%;max-width:667px;" alt="fieldKey"/>
3. Create a new dashboard cell that uses the `:fieldKey:` and `:measurementVar` template variables in its query.
```sql
SELECT :fieldKey: FROM "telegraf"..:measurementVar: WHERE time > :dashboardTime:
```
The resulting dashboard will work like this:
![Custom meta query filtering](/img/chronograf/v1.8/custom-meta-query-filtering.gif)
### Defining template variables in the URL
Chronograf uses URL query parameters (also known as query string parameters) to set both display options and template variables in the URL.
This makes it easy to share links to dashboards so they load in a specific state with specific template variable values selected.
URL query parameters are appeneded to the end of the URL with a question mark (`?`) indicating beginning of query parameters.
Multiple query paramemters can be chained together using an ampersand (`&`).
To declare a template variable or a date range as a URL query parameter, it must follow the following pattern:
#### Pattern for template variable query parameters
```bash
# Spaces for clarity only
& tempVars %5B variableName %5D = variableValue
```
`&`
Indicates the beginning of a new query parameter in a series of multiple query parameters.
`tempVars`
Informs Chronograf that the query parameter being passed is a template variable.
_**Required for all template variable query parameters.**_
`%5B`, `%5D`
URL-encoded `[` and `]` respectively that enclose the template variable name.
`variableName`
Name of the template variable.
`variableValue`
Value of the template variable.
> Whenever template variables are modified in the dashboard, the corresponding
> URL query parameters are automatically updated.
#### Example template variable query parameter
```
.../?&tempVars%5BmeasurementVar%5D=cpu
```
#### Including multiple template variables in the URL
To chain multiple template variables as URL query parameters, include the full [pattern](#pattern-for-template-variable-query-parameters) for _**each**_ template variable.
```bash
# Spaces for clarity only
.../? &tempVars%5BmeasurementVar%5D=cpu &tempVars%5BfieldKey%5D=usage_system
```

289
content/chronograf/v1.8/guides/live_leaderboard.md Normal file
View File

@ -0,0 +1,289 @@
---
title: Creating a live leaderboard for game scores
description: Tutorial on using Chronograf to build a leaderboard for gamers to be able to see player scores in realtime. Historical data is also available for post-game analysis.
menu:
chronograf_1_8:
name: Live leaderboard of game scores
weight: 20
parent: Guides
draft: true
---
**If you do not have a running Kapacitor instance, check out [Getting started with Kapacitor](/kapacitor/v1.4/introduction/getting-started/) to get Kapacitor up and running on localhost.**
Today we are game developers.
We host a several game servers, each running an instance of the game code, with about a hundred players per game.
We need to build a leaderboard so that spectators can see player scores in realtime.
We would also like to have historical data on leaders in order to do postgame
analysis on who was leading for how long, etc.
We will use Kapacitor stream processing to do the heavy lifting for us.
The game servers can send a [UDP](https://en.wikipedia.org/wiki/User_Datagram_Protocol) packet whenever a player's score changes,
or every 10 seconds if the score hasn't changed.
### Setup
> **Note:** Copies of the code snippets used here can be found in the [scores](https://github.com/influxdata/kapacitor/tree/master/examples/scores) example in Kapacitor project on GitHub.
First, we need to configure Kapacitor to receive the stream of scores.
In this example, the scores update too frequently to store all of the score data in a InfluxDB database, so the score data will be semt directly to Kapacitor.
Like InfluxDB, you can configure a UDP listener.
Add the following settings the `[[udp]]` secton in your Kapacitor configuration file (`kapacitor.conf`).
```
[[udp]]
enabled = true
bind-address = ":9100"
database = "game"
retention-policy = "autogen"
```
Using this configuration, Kapacitor will listen on port `9100` for UDP packets in [Line Protocol](/influxdb/latest/write_protocols/line_protocol_tutorial/) format.
Incoming data will be scoped to be in the `game.autogen` database and retention policy.
Restart Kapacitor so that the UDP listener service starts.
Here is a simple bash script to generate random score data so we can test it without
messing with the real game servers.
```bash
#!/bin/bash
# default options: can be overriden with corresponding arguments.
host=${1-localhost}
port=${2-9100}
games=${3-10}
players=${4-100}
games=$(seq $games)
players=$(seq $players)
# Spam score updates over UDP
while true
do
for game in $games
do
game="g$game"
for player in $players
do
player="p$player"
score=$(($RANDOM % 1000))
echo "scores,player=$player,game=$game value=$score" > /dev/udp/$host/$port
done
done
sleep 0.1
done
```
Place the above script into a file `scores.sh` and run it:
```bash
chmod +x ./scores.sh
./scores.sh
```
Now we are spamming Kapacitor with our fake score data.
We can just leave that running since Kapacitor will drop
the incoming data until it has a task that wants it.
### Defining the Kapacitor task
What does a leaderboard need to do?
1. Get the most recent score per player per game.
1. Calculate the top X player scores per game.
1. Publish the results.
1. Store the results.
To complete step one we need to buffer the incoming stream and return the most recent score update per player per game.
Our [TICKscript](/kapacitor/v1.4/tick/) will look like this:
```javascript
var topPlayerScores = stream
|from()
.measurement('scores')
// Get the most recent score for each player per game.
// Not likely that a player is playing two games but just in case.
.groupBy('game', 'player')
|window()
// keep a buffer of the last 11s of scores
// just in case a player score hasn't updated in a while
.period(11s)
// Emit the current score per player every second.
.every(1s)
// Align the window boundaries to be on the second.
.align()
|last('value')
```
Place this script in a file called `top_scores.tick`.
Now our `topPlayerScores` variable contains each player's most recent score.
Next to calculate the top scores per game we just need to group by game and run another map reduce job.
Let's keep the top 15 scores per game.
Add these lines to the `top_scores.tick` file.
```javascript
// Calculate the top 15 scores per game
var topScores = topPlayerScores
|groupBy('game')
|top(15, 'last', 'player')
```
The `topScores` variable now contains the top 15 player's score per game.
All we need to be able to build our leaderboard.
Kapacitor can expose the scores over HTTP via the [HTTPOutNode](/kapacitor/v1.4/nodes/http_out_node/).
We will call our task `top_scores`; with the following addition the most recent scores will be available at
`http://localhost:9092/kapacitor/v1/tasks/top_scores/top_scores`.
```javascript
// Expose top scores over the HTTP API at the 'top_scores' endpoint.
// Now your app can just request the top scores from Kapacitor
// and always get the most recent result.
//
// http://localhost:9092/kapacitor/v1/tasks/top_scores/top_scores
topScores
|httpOut('top_scores')
```
Finally we want to store the top scores over time so we can do in depth analysis to ensure the best game play.
But we do not want to store the scores every second as that is still too much data.
First we will sample the data and store scores only every 10 seconds.
Also let's do some basic analysis ahead of time since we already have a stream of all the data.
For now we will just do basic gap analysis where we will store the gap between the top player and the 15th player.
Add these lines to `top_scores.tick` to complete our task.
```javascript
// Sample the top scores and keep a score once every 10s
var topScoresSampled = topScores
|sample(10s)
// Store top fifteen player scores in InfluxDB.
topScoresSampled
|influxDBOut()
.database('game')
.measurement('top_scores')
// Calculate the max and min of the top scores.
var max = topScoresSampled
|max('top')
var min = topScoresSampled
|min('top')
// Join the max and min streams back together and calculate the gap.
max
|join(min)
.as('max', 'min')
// Calculate the difference between the max and min scores.
// Rename the max and min fields to more friendly names 'topFirst', 'topLast'.
|eval(lambda: "max.max" - "min.min", lambda: "max.max", lambda: "min.min")
.as('gap', 'topFirst', 'topLast')
// Store the fields: gap, topFirst and topLast in InfluxDB.
|influxDBOut()
.database('game')
.measurement('top_scores_gap')
```
Since we are writing data back to InfluxDB create a database `game` for our results.
```
curl -G 'http://localhost:8086/query?' --data-urlencode 'q=CREATE DATABASE game'
```
Here is the complete task TICKscript if you don't want to copy paste as much :)
```javascript
dbrp "game"."autogen"
// Define a result that contains the most recent score per player.
var topPlayerScores = stream
|from()
.measurement('scores')
// Get the most recent score for each player per game.
// Not likely that a player is playing two games but just in case.
.groupBy('game', 'player')
|window()
// keep a buffer of the last 11s of scores
// just in case a player score hasn't updated in a while
.period(11s)
// Emit the current score per player every second.
.every(1s)
// Align the window boundaries to be on the second.
.align()
|last('value')
// Calculate the top 15 scores per game
var topScores = topPlayerScores
|groupBy('game')
|top(15, 'last', 'player')
// Expose top scores over the HTTP API at the 'top_scores' endpoint.
// Now your app can just request the top scores from Kapacitor
// and always get the most recent result.
//
// http://localhost:9092/kapacitor/v1/tasks/top_scores/top_scores
topScores
|httpOut('top_scores')
// Sample the top scores and keep a score once every 10s
var topScoresSampled = topScores
|sample(10s)
// Store top fifteen player scores in InfluxDB.
topScoresSampled
|influxDBOut()
.database('game')
.measurement('top_scores')
// Calculate the max and min of the top scores.
var max = topScoresSampled
|max('top')
var min = topScoresSampled
|min('top')
// Join the max and min streams back together and calculate the gap.
max
|join(min)
.as('max', 'min')
// calculate the difference between the max and min scores.
|eval(lambda: "max.max" - "min.min", lambda: "max.max", lambda: "min.min")
.as('gap', 'topFirst', 'topLast')
// store the fields: gap, topFirst, and topLast in InfluxDB.
|influxDBOut()
.database('game')
.measurement('top_scores_gap')
```
Define and enable our task to see it in action:
```bash
kapacitor define top_scores -tick top_scores.tick
kapacitor enable top_scores
```
First let's check that the HTTP output is working.
```bash
curl 'http://localhost:9092/kapacitor/v1/tasks/top_scores/top_scores'
```
You should have a JSON result of the top 15 players and their scores per game.
Hit the endpoint several times to see that the scores are updating once a second.
Now, let's check InfluxDB to see our historical data.
```bash
curl \
-G 'http://localhost:8086/query?db=game' \
--data-urlencode 'q=SELECT * FROM top_scores WHERE time > now() - 5m GROUP BY game'
curl \
-G 'http://localhost:8086/query?db=game' \
--data-urlencode 'q=SELECT * FROM top_scores_gap WHERE time > now() - 5m GROUP BY game'
```
Great!
The hard work is done.
All that remains is configuring the game server to send score updates to Kapacitor and update the spectator dashboard to pull scores from Kapacitor.

289
content/chronograf/v1.8/guides/monitoring-influxenterprise-clusters.md Normal file
View File

@ -0,0 +1,289 @@
---
title: Monitoring InfluxDB Enterprise clusters
description: Use Chronograf dashboards with an InfluxDB OSS server to measure and monitor InfluxDB Enterprise cluster data nodes using Telegraf output plugins and input plugins.
aliases:
- /chronograf/v1.8/guides/monitor-an-influxenterprise-cluster/
menu:
chronograf_1_8:
weight: 80
parent: Guides
---
[InfluxEnterprise](/enterprise_influxdb/latest/) offers high availability and a highly scalable clustering solution for your time series data needs.
Use Chronograf to assess your cluster's health and to monitor the infrastructure behind your project.
This guide offers step-by-step instructions for using Chronograf, [InfluxDB](/influxdb/latest/), and [Telegraf](/telegraf/latest/) to monitor data nodes in your InfluxEnterprise cluster.
## Requirements
You have a fully-functioning InfluxEnterprise cluster with authentication enabled.
See the InfluxEnterprise documentation for
[detailed setup instructions](/enterprise_influxdb/latest/production_installation/).
This guide uses an InfluxData Enterprise cluster with three meta nodes and three data nodes; the steps are also applicable to other cluster configurations.
InfluxData recommends using a separate server to store your monitoring data.
It is possible to store the monitoring data in your cluster and [connect the cluster to Chronograf](/chronograf/latest/troubleshooting/frequently-asked-questions/#how-do-i-connect-chronograf-to-an-influxenterprise-cluster), but, in general, your monitoring data should live on a separate server.
You're working on an Ubuntu installation.
Chronograf and the other components of the TICK stack are supported on several operating systems and hardware architectures. Check out the [downloads page](https://portal.influxdata.com/downloads) for links to the binaries of your choice.
## Architecture overview
Before we begin, here's an overview of the final monitoring setup:
![Architecture diagram](/img/chronograf/chrono-cluster-diagram.png)
The diagram above shows an InfluxEnterprise cluster that consists of three meta nodes (M) and three data nodes (D).
Each data node has its own [Telegraf](/telegraf/latest/) instance (T).
Each Telegraf instance is configured to collect node CPU, disk, and memory data using the Telegraf [system stats](https://github.com/influxdata/telegraf/tree/master/plugins/inputs/system) input plugin.
The Telegraf instances are also configured to send those data to a single [InfluxDB OSS](/influxdb/latest/) instance that lives on a separate server.
When Telegraf sends data to InfluxDB, it automatically [tags](/influxdb/latest/concepts/glossary/#tag) the data with the hostname of the relevant data node.
The InfluxDB OSS instance that stores the Telegraf data is connected to Chronograf.
Chronograf uses the hostnames in the Telegraf data to populate the Host List page and provide other hostname-specific information in the user interface.
## Setup description
### InfluxDB OSS setup
#### Step 1: Download and install InfluxDB
InfluxDB can be downloaded from the [InfluxData downloads page](https://portal.influxdata.com/downloads).
#### Step 2: Enable authentication
For security purposes, enable authentication in the InfluxDB [configuration file (influxdb.conf)](/influxdb/latest/administration/config/), which is located in `/etc/influxdb/influxdb.conf`.
In the `[http]` section of the configuration file, uncomment the `auth-enabled` option and set it to `true`:
```
[http]
# Determines whether HTTP endpoint is enabled.
# enabled = true
# The bind address used by the HTTP service.
# bind-address = ":8086"
# Determines whether HTTP authentication is enabled.
auth-enabled = true #💥
```
#### Step 3: Start InfluxDB
Next, start the InfluxDB process:
```
~# sudo systemctl start influxdb
```
#### Step 4: Create an admin user
Create an [admin user](/influxdb/latest/query_language/authentication_and_authorization/#user-types-and-privileges) on your InfluxDB instance.
Because you enabled authentication, you must perform this step before moving on to the next section.
Run the command below to create an admin user, replacing `chronothan` and `supersecret` with your own username and password.
Note that the password requires single quotes.
```
~# curl -XPOST "http://localhost:8086/query" --data-urlencode "q=CREATE USER chronothan WITH PASSWORD 'supersecret' WITH ALL PRIVILEGES"
```
A successful `CREATE USER` query returns a blank result:
```
{"results":[{"statement_id":0}]} <--- Success!
```
### Telegraf setup
Perform the following steps on each data node in your cluster.
You'll return to your InfluxDB instance at the end of this section.
#### Step 1: Download and install Telegraf.
Telegraf can be downloaded from the [InfluxData downloads page](https://portal.influxdata.com/downloads).
#### Step 2: Configure Telegraf.
Configure Telegraf to write monitoring data to your InfluxDB OSS instance.
The Telegraf configuration file is located in `/etc/telegraf/telegraf.conf`.
First, in the `[[outputs.influxdb]]` section, set the `urls` option to the IP address and port of your InfluxDB OSS instance.
InfluxDB runs on port `8086` by default.
This step ensures that Telegraf writes data to your InfluxDB OSS instance.
```
[[outputs.influxdb]]
## The full HTTP or UDP endpoint URL for your InfluxDB instance.
## Multiple urls can be specified as part of the same cluster,
## this means that only ONE of the urls will be written to each interval.
# urls = ["udp://localhost:8089"] # UDP endpoint example
urls = ["http://xxx.xx.xxx.xxx:8086"] #💥
```
Next, in the same `[[outputs.influxdb]]` section, uncomment and set the `username` and `password` options to the username and password that you created in the [previous section](#step-4-create-an-admin-user).
Telegraf must be aware your username and password to successfully write data to your InfluxDB OSS instance.
```
[[outputs.influxdb]]
## The full HTTP or UDP endpoint URL for your InfluxDB instance.
## Multiple urls can be specified as part of the same cluster,
## this means that only ONE of the urls will be written to each interval.
# urls = ["udp://localhost:8089"] # UDP endpoint example
urls = ["http://xxx.xx.xxx.xxx:8086"] # required
[...]
## Write timeout (for the InfluxDB client), formatted as a string.
## If not provided, will default to 5s. 0s means no timeout (not recommended).
timeout = "5s"
username = "chronothan" #💥
password = "supersecret" #💥
```
The [Telegraf System input plugin](https://github.com/influxdata/telegraf/tree/master/plugins/inputs/system) is enabled by default and requires no additional configuration.
The input plugin automatically collects general statistics on system load, uptime, and the number of users logged in.
Enabled input plugins are configured in the `INPUT PLUGINS` section of the configuration file; for example, here's the section that controls the CPU data collection:
```
###############################################################################
# INPUT PLUGINS #
###############################################################################
# Read metrics about cpu usage
[[inputs.cpu]]
## Whether to report per-cpu stats or not
percpu = true
## Whether to report total system cpu stats or not
totalcpu = true
## If true, collect raw CPU time metrics.
collect_cpu_time = false
```
#### Step 3: Restart the Telegraf service.
Restart the Telegraf service so that your configuration changes take effect:
**macOS**
```sh
telegraf --config telegraf.conf
```
**Linux (sysvinit and upstart installations)**
```sh
sudo service telegraf restart
```
**Linux (systemd installations)**
```sh
systemctl restart telegraf
```
Repeat steps one through four for each data node in your cluster.
#### Step 4: Confirm the Telegraf setup.
To verify Telegraf is successfully collecting and writing data, use one of the following methods to query your InfluxDB OSS instance:
**InfluxDB CLI (`influx`)**
```sh
$ influx
> SHOW TAG VALUES FROM cpu WITH KEY=host
```
**`curl`**
Replace the `chronothan` and `supersecret` values with your actual username and password.
```
~# curl -G "http://localhost:8086/query?db=telegraf&u=chronothan&p=supersecret&pretty=true" --data-urlencode "q=SHOW TAG VALUES FROM cpu WITH KEY=host"
```
The expected output is similar to the JSON code block below.
In this case, the `telegraf` database has three different [tag values](/influxdb/latest/concepts/glossary/#tag-value) for the `host` [tag key](/influxdb/latest/concepts/glossary/#tag-key): `data-node-01`, `data-node-02`, and `data-node-03`.
Those values match the hostnames of the three data nodes in the cluster; this means Telegraf is successfully writing monitoring data from those hosts to the InfluxDB OSS instance!
```
{
"results": [
{
"statement_id": 0,
"series": [
{
"name": "cpu",
"columns": [
"key",
"value"
],
"values": [
[
"host",
"data-node-01"
],
[
"host",
"data-node-02"
],
[
"host",
"data-node-03"
]
]
}
]
}
]
}
```
### Chronograf Setup
#### Step 1: Download and install Chronograf
Download and install Chronograf on the same server as the InfluxDB instance.
This is not a requirement; you may host Chronograf on a separate server.
Chronograf can be downloaded from the [InfluxData downloads page](https://portal.influxdata.com/downloads).
#### Step 2: Start Chronograf
```
~# sudo systemctl start chronograf
```
### Step 3: Connect Chronograf to the InfluxDB OSS instance
To access Chronograf, go to http://localhost:8888.
The welcome page includes instructions for connecting Chronograf to that instance.
![Connect Chronograf to InfluxDB](/img/chronograf/chrono-cluster-welcome.png)
For the `Connection String`, enter the hostname or IP of your InfluxDB OSS instance, and be sure to include the default port: `8086`.
Next, name your data source; this can be anything you want.
Finally, enter your username and password and click `Add Source`.
### Step 4: Explore the monitoring data in Chronograf
Chronograf works with the Telegraf data in your InfluxDB OSS instance.
The `Host List` page shows your data node's hostnames, their statuses, CPU usage, load, and their configured applications.
In this case, you've only enabled the system stats input plugin so `system` is the single application that appears in the `Apps` column.
![Host List page](/img/chronograf/chrono-cluster-hostlist.png)
Click `system` to see the Chronograf canned dashboard for that application.
Keep an eye on your data nodes by viewing that dashboard for each hostname:
![Pre-created dashboard](/img/chronograf/chrono-cluster-predash.gif)
Next, check out the Data Explorer to create a customized graph with the monitoring data.
In the image below, the Chronograf query editor is used to visualize the idle CPU usage data for each data node:
![Data Explorer](/img/chronograf/chrono-cluster-de.png)
Create more customized graphs and save them to a dashboard on the Dashboard page in Chronograf.
See the [Creating Chronograf dashboards](/chronograf/latest/guides/create-a-dashboard/) guide for more information.
That's it! You've successfully configured Telegraf to collect and write data, InfluxDB to store those data, and Chonograf to use those data for monitoring and visualization purposes.

25
content/chronograf/v1.8/guides/presentation-mode.md Normal file
View File

@ -0,0 +1,25 @@
---
title: Viewing Chronograf dashboards in presentation mode
description: View dashboards in full screen using presentation mode.
menu:
chronograf_1_8:
name: Viewing dashboards in presentation mode
weight: 130
parent: Guides
---
Presentation mode allows you to view Chronograf in full screen, hiding the left and top navigation menus so only the cells appear. This mode might be helpful, for example, for stationary screens dedicated to monitoring visualizations.
## Entering presentation mode manually
To enter presentation mode manually, click the icon in the upper right:
<img src="/img/chronograf/chronograf-presentation-mode.png" style="width:100%; max-width:500px"/>
To exit presentation mode, press `ESC`.
## Using the URL query parameter
To load the dashboard in presentation mode, add URL query parameter `present=true` to your dashboard URL. For example, your URL might look like this:
`http://example.com:8888/sources/1/dashboards/2?present=true`
Note that if you use this option, you won't be able to exit presentation mode using `ESC`.

83
content/chronograf/v1.8/guides/querying-data.md Normal file
View File

@ -0,0 +1,83 @@
---
title: Explore data in Chronograf
description: Query and visualize data in the Data Explorer.
menu:
chronograf_1_8:
name: Exploring data in Chronograf
weight: 130
parent: Guides
---
Explore and visualize your data in the **Data Explorer**. For both InfluxQL and Flux, Chronograf allows you to move seamlessly between using the builder or templates and manually editing the query; when possible, the interface automatically populates the builder with the information from your raw query. Choose between [visualization types](/chronograf/latest/guides/visualization-types/) for your query.
To open the **Data Explorer**, click the **Explore** icon in the navigation bar:
<img src="/img/chronograf/v1.8/data-explorer-icon.png" style="width:100%; max-width:400px; margin:2em 0; display: block;">
## Select local time or UTC (Coordinated Universal Time)
- In the upper-right corner of the page, select the time to view metrics and events by clicking one of the following:
- **UTC** for Coordinated Universal Time
- **Local** for the local time reported by your browser
> **Note:** If your organization spans multiple time zones, we recommend using UTC (Coordinated Universal Time) to ensure that everyone sees metrics and events for the same time.
## Explore data with InfluxQL
InfluxQL is a SQL-like query language you can use to interact with data in InfluxDB. For detailed tutorials and reference material, see our [InfluxQL documentation](/influxdb/latest/query_language/).
1. Open the Data Explorer and click **Add a Query**.
2. To the right of the source dropdown above the graph placeholder, select **InfluxQL** as the source type.
3. Use the builder to select from your existing data and allow Chronograf to format the query for you. Alternatively, manually enter and edit a query.
4. You can also select from the dropdown list of **Metaquery Templates**. Metaqueries show information about a database, such as.
5. Click **Show template values** to display the calculated values in the template.
## Explore data with Flux
Flux is InfluxData's new functional data scripting language designed for querying, analyzing, and acting on time series data. To learn more about Flux, see [Getting started with Flux](/flux/v0.7/introduction/getting-started).
> ***Note:*** Flux v0.7 is a technical preview included with [InfluxDB v1.8](/influxdb/v1.8). It is still in active development and many functions provided by InfluxQL and TICKscript have yet to be implemented.
1. Open the Data Explorer and click **Add a Query**.
2. To the right of the source dropdown above the graph placeholder, select **Flux** as the source type.
The **Schema**, **Functions**, and **Script** panes appear.
3. Use the **Schema** pane to explore your available data. Click the **+** sign next to a bucket name to expand its content.
4. Use the **Functions** pane to view details about the available Flux functions.
5. Use the **Script** pane to enter your Flux query.
* To get started with your query, click the **Script Wizard**. In the wizard, you can select a bucket, measurement, fields and an aggregate.
<img src="/img/chronograf/v1.8/flux-script-wizard.png" style="width:100%; max-width:400px; margin:2em 0; display:block;">
For example, if you make the above selections, the wizard inserts the following script:
```js
from(bucket: "telegraf/autogen")
|> range(start: dashboardTime)
|> filter(fn: (r) => r._measurement == "cpu" and (r._field == "usage_system"))
|> window(every: autoInterval)
|> toFloat()
|> percentile(percentile: 0.95)
|> group(except: ["_time", "_start", "_stop", "_value"])
```
* Alternatively, you can enter your entire script manually.
6. Click **Run Script** in the top bar of the **Script** pane. You can then preview your graph in the above pane.
## Visualize your query
Select the **Visualization** tab at the top of the **Data Explorer**. For details about all of the available visualization options, see [Visualization types in Chronograf](/chronograf/latest/guides/visualization-types/).
## Add queries to dashboards
To add your query and graph to a dashboard:
1. Click **Send to Dashboard** in the upper right.
2. In the **Target Dashboard(s)** dropdown, select at least one existing dashboard to send the cell to, or select **Send to a New Dashboard**.
<img src="/img/chronograf/send-to-dashboard-target.png" style="width:100%; max-width:597px; margin:2em 0; display: block;">
3. Enter a name for the new cell and, if you created a new dashboard, the new dashboard.
4. Click **Send to Dashboard(s)**.
<img src="/img/chronograf/v1.8/send-to-dashboard-send.png" style="width:100%; max-width:597px; display:block; margin:2em 0;">

15
content/chronograf/v1.8/guides/tickscript-logging.md Normal file
View File

@ -0,0 +1,15 @@
---
title: Editing TICKscripts in Chronograf
description: Editing and viewing TICKscript logs in Chronograf
menu:
chronograf_1_8:
weight: 20
parent: Guides
---
TICKscript logs data to a log file for debugging purposes.
Notes:
* TICKscript logs data to a log file for debugging purposes. We have a bunch of hosts which post data to an external endpoint. the payload is logged before being sent.
A feature to show the list of hosts , and an ability to see the logs for each of them.

479
content/chronograf/v1.8/guides/using-precreated-dashboards.md Normal file
View File

@ -0,0 +1,479 @@
---
title: Using pre-created dashboards in Chronograf
description: Preconfigured dashboards can quickly be used to display metrics for popular applications, including Apache, Consul, Docker, Elasticsearch, InfluxDB, Mesos, MySQL, NGINX, PostgreSQL, RabbitMQ, Redis, and more
menu:
chronograf_1_8:
name: Using pre-created dashboards
weight: 10
parent: Guides
---
## Overview
Pre-created dashboards are delivered with Chronograf depending on which Telegraf input plugins you have enabled and are available from the Host List page. These dashboards, which are built in and not editable, include cells with data visualizations for metrics that are relevant to data sources you are likely to be using.
> Note that these pre-created dashboards cannot be cloned or customized. They appear only as part of the Host List view and are associated with metrics gathered from a single host. Dashboard templates are also available and deliver a solid starting point for customizing your own unique dashboards based on the Telegraf plugins enabled and operate across one or more hosts. For details, see [Dashboard templates](/chronograf/latest/guides/create-a-dashboard/#dashboard-templates).
## Requirements
The pre-created dashboards automatically appear in the Host List page to the right of hosts based on which Telegraf input plugins you have enabled. Check the list below for applications that you are interested in using and make sure that you have the required Telegraf input plugins enabled.
## Using pre-created dashboards
Pre-created dashboards are delivered in Chronograf installations and are ready to be used when you have the required Telegraf input plugins enabled.
**To view a pre-created dashboard:**
1. Open Chronograf in your web browser and click **Host List** in the navigation bar.
2. Select an application listed under **Apps**. By default, the system `app` should be listed next to a host listing. Other apps appear depending on the Telegraf input plugins that you have enabled.
The selected application appears showing pre-created cells, based on available measurements.
## Creating or editing dashboards
Find a list of apps (pre-created dashboards) available to use with Chronograf below. For each app, you'll find:
- Required Telegraf input plugins for the app
- JSON files included in the app
- Cell titles included in each JSON file
The JSON files for apps are included in the `/usr/share/chronograf/canned` directory. Find information about the configuration option `--canned-path` on the [Chronograf configuration options](/chronograf/latest/administration/config-options/) page.
Enable and disable apps in your [Telegraf configuration file](by default, `/etc/telegraf/telegraf.conf`). See [Configuring Telegraf](/telegraf/v1.13/administration/configuration/) for details.
## Apps (pre-created dashboards):
* [apache](#apache)
* [consul](#consul)
* [docker](#docker)
* [elasticsearch](#elasticsearch)
* [haproxy](#haproxy)
* [iis](#iis)
* [influxdb](#influxdb)
* [kubernetes](#kubernetes)
* [memcached](#memcached-memcached)
* [mesos](#mesos)
* [mysql](#mysql)
* [nginx](#nginx)
* [nsq](#nsq)
* [phpfpm](#phpfpm)
* [ping](#ping)
* [postgresql](#postgresql)
* [rabbitmq](#rabbitmq)
* [redis](#redis)
* [riak](#riak)
* [system](#system)
* [varnish](#varnish)
* [win_system](#win-system)
## apache
**Required Telegraf plugin:** [Apache input plugin](/telegraf/latest/plugins/inputs/#apache-http-server)
`apache.json`
* "Apache Bytes/Second"
* "Apache - Requests/Second"
* "Apache - Total Accesses"
## consul
**Required Telegraf plugin:** [Consul input plugin](/telegraf/latest/plugins/inputs/#consul)
`consul_http.json`
* "Consul - HTTP Request Time (ms)"
`consul_election.json`
* "Consul - Leadership Election"
`consul_cluster.json`
* "Consul - Number of Agents"
`consul_serf_events.json`
* "Consul - Number of serf events"
## docker
**Required Telegraf plugin:** [Docker input plugin](/telegraf/latest/plugins/inputs/#docker)
`docker.json`
* "Docker - Container CPU %"
* "Docker - Container Memory (MB)"
* "Docker - Containers"
* "Docker - Images"
* "Docker - Container State"
`docker_blkio.json`
* "Docker - Container Block IO"
`docker_net.json`
* "Docker - Container Network"
## elasticsearch
**Required Telegraf plugin:** [Elasticsearch input plugin](/telegraf/latest/plugins/inputs/#elasticsearch)
`elasticsearch.json`
* "ElasticSearch - Query Throughput"
* "ElasticSearch - Open Connections"
* "ElasticSearch - Query Latency"
* "ElasticSearch - Fetch Latency"
* "ElasticSearch - Suggest Latency"
* "ElasticSearch - Scroll Latency"
* "ElasticSearch - Indexing Latency"
* "ElasticSearch - JVM GC Collection Counts"
* "ElasticSearch - JVM GC Latency"
* "ElasticSearch - JVM Heap Usage"
## haproxy
**Required Telegraf plugin:** [HAProxy input plugin](/telegraf/latest/plugins/inputs/#haproxy)
`haproxy.json`
* "HAProxy - Number of Servers"
* "HAProxy - Sum HTTP 2xx"
* "HAProxy - Sum HTTP 4xx"
* "HAProxy - Sum HTTP 5xx"
* "HAProxy - Frontend HTTP Requests/Second"
* "HAProxy - Frontend Sessions/Second"
* "HAProxy - Frontend Session Usage %"
* "HAProxy - Frontend Security Denials/Second"
* "HAProxy - Frontend Request Errors/Second"
* "HAProxy - Frontend Bytes/Second"
* "HAProxy - Backend Average Response Time (ms)"
* "HAProxy - Backend Connection Errors/Second"
* "HAProxy - Backend Queued Requests/Second"
* "HAProxy - Backend Average Request Queue Time (ms)"
* "HAProxy - Backend Error Responses/Second"
## iis
**Required Telegraf plugin:** [Windows Performance Counters input plugin](/telegraf/v1.8/plugins/inputs/#windows-performance-counters)
`win_websvc.json`
* "IIS - Service"
## influxdb
**Required Telegraf plugin:** [InfluxDB input plugin](/telegraf/latest/plugins/inputs/#influxdb-v-1)
`influxdb_database.json`
* "InfluxDB - Cardinality"
`influxdb_httpd.json`
* "InfluxDB - Write HTTP Requests"
* "InfluxDB - Query Requests"
* "InfluxDB - Client Failures"
`influxdb_queryExecutor.json`
* "InfluxDB - Query Performance"
`influxdb_write.json`
* "InfluxDB - Write Points"
* "InfluxDB - Write Errors"
## kubernetes
`kubernetes_node.json`
* "K8s - Node Millicores"
* "K8s - Node Memory Bytes"
`kubernetes_pod_container.json`
* "K8s - Pod Millicores"
* "K8s - Pod Memory Bytes"
`kubernetes_pod_network.json`
* "K8s - Pod TX Bytes/Second"
* "K8s - Pod RX Bytes/Second "
`kubernetes_system_container.json`
* "K8s - Kubelet Millicores"
* "K8s - Kubelet Memory Bytes"
## Memcached (`memcached`)
**Required Telegraf plugin:** [Memcached input plugin](/telegraf/latest/plugins/inputs/#memcached)
`memcached.json`
* "Memcached - Current Connections"
* "Memcached - Get Hits/Second"
* "Memcached - Get Misses/Second"
* "Memcached - Delete Hits/Second"
* "Memcached - Delete Misses/Second"
* "Memcached - Incr Hits/Second"
* "Memcached - Incr Misses/Second"
* "Memcached - Current Items"
* "Memcached - Total Items"
* "Memcached - Bytes Stored"
* "Memcached - Bytes Written/Sec"
* "Memcached - Evictions/10 Seconds"
## mesos
**Required Telegraf plugin:** [Mesos input plugin](/telegraf/latest/plugins/inputs/#mesos)
`mesos.json`
* "Mesos Active Slaves"
* "Mesos Tasks Active"
* "Mesos Tasks"
* "Mesos Outstanding offers"
* "Mesos Available/Used CPUs"
* "Mesos Available/Used Memory"
* "Mesos Master Uptime"
## mongodb
**Required Telegraf plugin:** [MongoDB input plugin](/telegraf/latest/plugins/inputs/#mongodb)
`mongodb.json`
* "MongoDB - Read/Second"
* "MongoDB - Writes/Second"
* "MongoDB - Active Connections"
* "MongoDB - Reds/Writes Waiting in Queue"
* "MongoDB - Network Bytes/Second"
## mysql
**Required Telegraf plugin:** [MySQL input plugin](/telegraf/latest/plugins/inputs/#mysql)
`mysql.json`
* "MySQL - Reads/Second"
* "MySQL - Writes/Second"
* "MySQL - Connections/Second"
* "MySQL - Connection Errors/Second"
## nginx
**Required Telegraf plugin:** [NGINX input plugin](/telegraf/latest/plugins/inputs/#nginx)
`nginx.json`
* "NGINX - Client Connections"
* "NGINX - Client Errors"
* "NGINX - Client Requests"
* "NGINX - Active Client State"
## nsq
**Required Telegraf plugin:** [NSQ input plugin](/telegraf/latest/plugins/inputs/#nsq)
`nsq_channel.json`
* "NSQ - Channel Client Count"
* "NSQ - Channel Messages Count"
`nsq_server.json`
* "NSQ - Topic Count"
* "NSQ - Server Count"
`nsq_topic.json`
* "NSQ - Topic Messages"
* "NSQ - Topic Messages on Disk"
* "NSQ - Topic Ingress"
* "NSQ topic egress"
## phpfpm
**Required Telegraf plugin:** [PHPfpm input plugin](/telegraf/latest/plugins/inputs/#php-fpm)
`phpfpm.json`
* "phpfpm - Accepted Connections"
* "phpfpm - Processes"
* "phpfpm - Slow Requests"
* "phpfpm - Max Children Reached"
## ping
**Required Telegraf plugin:** [Ping input plugin](/telegraf/latest/plugins/inputs/#ping)
`ping.json`
* "Ping - Packet Loss Percent"
* "Ping - Response Times (ms)"
## postgresql
**Required Telegraf plugin:** [PostgreSQL input plugin](/telegraf/latest/plugins/inputs/#postgresql)
`postgresql.json`
* "PostgreSQL - Rows"
* "PostgreSQL - QPS"
* "PostgreSQL - Buffers"
* "PostgreSQL - Conflicts/Deadlocks"
## rabbitmq
**Required Telegraf plugin:** [RabbitMQ input plugin](/telegraf/latest/plugins/inputs/#rabbitmq)
`rabbitmq.json`
* "RabbitMQ - Overview"
* "RabbitMQ - Published/Delivered per second"
* "RabbitMQ - Acked/Unacked per second"
## redis
**Required Telegraf plugin:** [Redis input plugin](/telegraf/latest/plugins/inputs/#redis)
`redis.json`
* "Redis - Connected Clients"
* "Redis - Blocked Clients"
* "Redis - CPU"
* "Redis - Memory"
## riak
**Required Telegraf plugin:** [Riak input plugin](/telegraf/latest/plugins/inputs/#riak)
`riak.json`
* "Riak - Toal Memory Bytes"
* "Riak - Object Byte Size"
* "Riak - Number of Siblings/Minute"
* "Riak - Latency (ms)"
* "Riak - Reads and Writes/Minute"
* "Riak - Active Connections"
* "Riak - Read Repairs/Minute"
## system
The `system` application includes metrics that require all of the listed plugins. If any of the following plugins aren't enabled, the metrics associated with the plugins will not display data.
### cpu
**Required Telegraf plugin:** [CPU input plugin](/telegraf/latest/plugins/inputs/#cpu)
`cpu.json`
* "CPU Usage"
### disk
`disk.json`
**Required Telegraf plugin:** [Disk input plugin](/telegraf/latest/plugins/inputs/#disk)
* "System - Disk used %"
### diskio
**Required Telegraf plugin:** [DiskIO input plugin](/telegraf/latest/plugins/inputs/#diskio)
`diskio.json`
* "System - Disk MB/s"
*
### mem
**Required Telegraf plugin:** [Mem input plugin](/telegraf/latest/plugins/inputs/#mem)
`mem.json`
* "System - Memory Gigabytes Used"
### net
**Required Telegraf plugin:** [Net input plugin](/telegraf/latest/plugins/inputs/#net)
`net.json`
* "System - Network Mb/s"
* "System - Network Error Rate"
### netstat
**Required Telegraf plugin:** [Netstat input plugin](/telegraf/latest/plugins/inputs/#netstat)
`netstat.json`
* "System - Open Sockets"
* "System - Sockets Created/Second"
### processes
**Required Telegraf plugin:** [Processes input plugin](/telegraf/latest/plugins/inputs/#processes)
`processes.json`
* "System - Total Processes"
### procstat
**Required Telegraf plugin:** [Procstat input plugin](/telegraf/latest/plugins/inputs/#procstat)
`procstat.json`
* "Processes - Resident Memory (MB)"
* "Processes – CPU Usage %"
### system
**Required Telegraf plugin:** [Procstat input plugin](/telegraf/latest/plugins/inputs/#procstat)
`load.json`
* "System Load"
## varnish
**Required Telegraf plugin:** [Varnish](/telegraf/latest/plugins/inputs/#varnish)
`varnish.json`
* "Varnish - Cache Hits/Misses"
## win_system
**Required Telegraf plugin:** [Windows Performance Counters input plugin](/telegraf/latest/plugins/inputs/#windows-performance-counters)
`win_cpu.json`
* "System - CPU Usage"
`win_mem.json`
* "System - Available Bytes"
`win_net.json`
* "System - TX Bytes/Second"
* "RX Bytes/Second"
`win_system.json`
* "System - Load"

277
content/chronograf/v1.8/guides/visualization-types.md Normal file
View File

@ -0,0 +1,277 @@
---
title: Visualization types in Chronograf
descriptions: Chronograf dashboards and views support graphs and other visualization types, including line graphs, stacked graphs, step-plot graphs, single statistics, bar graphs, gauges, and tables.
menu:
chronograf_1_8:
name: Visualization types
weight: 40
parent: Guides
---
Chronograf's dashboard views support the following visualization types, which can be selected in the **Visualization Type** selection view of the [Data Explorer](/chronograf/latest/querying-data) .
[Visualization Type selector](/img/chronograf/chrono-viz-types-selector.png)
Each of the available visualization types and available user controls are described below.
* [Line Graph](#line-graph)
* [Stacked Graph](#stacked-graph)
* [Step-Plot Graph](#step-plot-graph)
* [Single Stat](#single-stat)
* [Line Graph + Single Stat](#line-graph-single-stat)
* [Bar Graph](#bar-graph)
* [Gauge](#gauge)
* [Table](#table)
* [Note](#note)
For information on adding and displaying annotations in graph views, see [Adding annotations to Chronograf views](/chronograf/v1.8/guides/annotations/).
### Line Graph
The **Line Graph** view displays a time series in a line graph.
![Line Graph selector](/img/chronograf/chrono-viz-line-graph-selector.png)
#### Line Graph Controls
![Line Graph Controls](/img/chronograf/chrono-viz-line-graph-controls.png)
Use the **Line Graph Controls** to specify the following:
* **Title**: y-axis title. Enter title, if using a custom title.
- **auto**: Enable or disable auto-setting.
* **Min**: Minimum y-axis value.
- **auto**: Enable or disable auto-setting.
* **Max**: Maximum y-axis value.
- **auto**: Enable or disable auto-setting.
* **Y-Value's Prefix**: Prefix to be added to y-value.
* **Y-Value's Suffix**: Suffix to be added to y-value.
* **Y-Value's Format**: Toggle between **K/M/B** (Thousand/Million/Billion) and **K/M/G** (Kilo/Mega/Giga).
* **Scale**: Toggle between **Linear** and **Logarithmic**.
* **Static Legend**: Toggle between **Show** and **Hide**.
#### Line Graph example
![Line Graph example](/img/chronograf/chrono-viz-line-graph-example.png)
### Stacked Graph
The **Stacked Graph** view displays multiple time series bars as segments stacked on top of each other.
![Stacked Graph selector](/img/chronograf/chrono-viz-stacked-graph-selector.png)
#### Stacked Graph Controls
![Stacked Graph Controls](/img/chronograf/chrono-viz-stacked-graph-controls.png)
Use the **Stacked Graph Controls** to specify the following:
* **Title**: y-axis title. Enter title, if using a custom title.
- **auto**: Enable or disable auto-setting.
* **Min**: Minimum y-axis value.
- **auto**: Enable or disable auto-setting.
* **Max**: Maximum y-axis value.
- **auto**: Enable or disable auto-setting.
* **Y-Value's Prefix**: Prefix to be added to y-value.
* **Y-Value's Suffix**: Suffix to be added to y-value.
* **Y-Value's Format**: Toggle between **K/M/B** (Thousand/Million/Billion) and **K/M/G** (Kilo/Mega/Giga).
* **Scale**: Toggle between **Linear** and **Logarithmic**.
* **Static Legend**: Toggle between **Show** and **Hide**.
#### Stacked Graph example
![Stacked Graph example](/img/chronograf/chrono-viz-stacked-graph-example.png)
### Step-Plot Graph
The **Step-Plot Graph** view displays a time series in a staircase graph.
![Step-Plot Graph selector](/img/chronograf/chrono-viz-step-plot-graph-selector.png)
#### Step-Plot Graph Controls
![Step-Plot Graph Controls](/img/chronograf/chrono-viz-step-plot-graph-controls.png)
Use the **Step-Plot Graph Controls** to specify the following:
* **Title**: y-axis title. Enter title, if using a custom title.
- **auto**: Enable or disable auto-setting.
* **Min**: Minimum y-axis value.
- **auto**: Enable or disable auto-setting.
* **Max**: Maximum y-axis value.
- **auto**: Enable or disable auto-setting.
* **Y-Value's Prefix**: Prefix to be added to y-value.
* **Y-Value's Suffix**: Suffix to be added to y-value.
* **Y-Value's Format**: Toggle between **K/M/B** (Thousand/Million/Billion) and **K/M/G** (Kilo/Mega/Giga).
* **Scale**: Toggle between **Linear** and **Logarithmic**.
#### Step-Plot Graph example
![Step-Plot Graph example](/img/chronograf/chrono-viz-step-plot-graph-example.png)
### Bar Graph
The **Bar Graph** view displays the specified time series using a bar chart.
To select this view, click the Bar Graph selector icon.
![Bar Graph selector](/img/chronograf/chrono-viz-bar-graph-selector.png)
#### Bar Graph Controls
![Bar Graph Controls](/img/chronograf/chrono-viz-bar-graph-controls.png)
Use the **Bar Graph Controls** to specify the following:
* **Title**: y-axis title. Enter title, if using a custom title.
- **auto**: Enable or disable auto-setting.
* **Min**: Minimum y-axis value.
- **auto**: Enable or disable auto-setting.
* **Max**: Maximum y-axis value.
- **auto**: Enable or disable auto-setting.
* **Y-Value's Prefix**: Prefix to be added to y-value.
* **Y-Value's Suffix**: Suffix to be added to y-value.
* **Y-Value's Format**: Toggle between **K/M/B** (Thousand/Million/Billion) and **K/M/G** (Kilo/Mega/Giga).
* **Scale**: Toggle between **Linear** and **Logarithmic**.
#### Bar Graph example
![Bar Graph example](/img/chronograf/chrono-viz-bar-graph-example.png)
### Line Graph + Single Stat
The **Line Graph + Single Stat** view displays the specified time series in a line graph and overlays the single most recent value as a large numeric value.
To select this view, click the **Line Graph + Single Stat** view option.
![Line Graph + Single Stat selector](/img/chronograf/chrono-viz-line-graph-single-stat-selector.png)
#### Line Graph + Single Stat Controls
![Line Graph + Single Stat Controls](/img/chronograf/chrono-viz-line-graph-single-stat-controls.png)
Use the **Line Graph + Single Stat Controls** to specify the following:
* **Title**: y-axis title. Enter title, if using a custom title.
- **auto**: Enable or disable auto-setting.
* **Min**: Minimum y-axis value.
- **auto**: Enable or disable auto-setting.
* **Max**: Maximum y-axis value.
- **auto**: Enable or disable auto-setting.
* **Y-Value's Prefix**: Prefix to be added to y-value.
* **Y-Value's Suffix**: Suffix to be added to y-value.
* **Y-Value's Format**: Toggle between **K/M/B** (Thousand/Million/Billion) and **K/M/G** (Kilo/Mega/Giga).
* **Scale**: Toggle between **Linear** and **Logarithmic**.
#### Line Graph + Single Stat example
![Line Graph + Single Stat example](/img/chronograf/chrono-viz-line-graph-single-stat-example.png)
### Single Stat
The **Single Stat** view displays the most recent value of the specified time series as a numerical value.
![Single Stat view](/img/chronograf/chrono-viz-single-stat-selector.png)
If a cell's query includes a [`GROUP BY` tag](/influxdb/latest/query_language/data_exploration/#group-by-tags) clause, Chronograf sorts the different [series](/influxdb/latest/concepts/glossary/#series) lexicographically and shows the most recent [field value](/influxdb/latest/concepts/glossary/#field-value) associated with the first series.
For example, if a query groups by the `name` [tag key](/influxdb/latest/concepts/glossary/#tag-key) and `name` has two [tag values](/influxdb/latest/concepts/glossary/#tag-value) (`chronelda` and `chronz`), Chronograf shows the most recent field value associated with the `chronelda` series.
If a cell's query includes more than one [field key](/influxdb/latest/concepts/glossary/#field-key) in the [`SELECT` clause](/influxdb/latest/query_language/data_exploration/#select-clause), Chronograf returns the most recent field value associated with the first field key in the `SELECT` clause.
For example, if a query's `SELECT` clause is `SELECT "chronogiraffe","chronelda"`, Chronograf shows the most recent field value associated with the `chronogiraffe` field key.
#### Single Stat Controls
Use the **Single Stat Controls** panel to specify one or more thresholds:
* **Add Threshold**: Button to add a new threshold.
* **Base Color**: Select a base, or background, color from the selection list.
* Color options: Ruby, Fire, Curacao, Tiger, Pineapple, Thunder, Honeydew, Rainforest, Viridian, Ocean, Pool, Laser (default), Planet, Star, Comet, Pepper, Graphite, White, and Castle.
* **Prefix**: Prefix. For example, `%`, `MPH`, etc.
* **Suffix**: Suffix. For example, `%`, `MPH`, etc.
* Threshold Coloring: Toggle between **Background** and **Text**
### Gauge
The **Gauge** view displays the single value most recent value for a time series in a gauge view.
To select this view, click the Gauge selector icon.
![Gauge selector](/img/chronograf/chrono-viz-gauge-selector.png)
#### Gauge Controls
![Gauge Controls](/img/chronograf/chrono-viz-gauge-controls.png)
Use the **Gauge Controls** to specify the following:
* **Add Threshold**: Click button to add a threshold.
* **Min**: Minimum value for the threshold.
- Select color to display. Selection list options include: Laser (default), Ruby, Fire, Curacao, Tiger, Pineapple, Thunder, and Honeydew.
* **Max**: Maximum value for the threshold.
- Select color to display. Selection list options include: Laser (default), Ruby, Fire, Curacao, Tiger, Pineapple, Thunder, and Honeydew.
* **Prefix**: Prefix. For example, `%`, `MPH`, etc.
* **Suffix**: Suffix. For example, `%`, `MPH`, etc.
#### Gauge example
![Gauge example](/img/chronograf/chrono-viz-gauge-example.png)
### Table
The **Table** panel displays the results of queries in a tabular view, which is sometimes easier to analyze than graph views of data.
![Table selector](/img/chronograf/chrono-viz-table-selector.png)
#### Table Controls
![Table Controls](/img/chronograf/chrono-viz-table-controls.png)
Use the **Table Controls** to specify the following:
* **Default Sort Field**: Select the default sort field. Default is **time**.
* **Decimal Places**: Enter the number of decimal places. Default (empty field) is **unlimited**.
* **Time Axis**: Select **Vertical** or **Horizontal**.
* **Time Format**: Select the time format.
- Options include: `MM/DD/YYYY HH:mm:ss` (default), `MM/DD/YYYY HH:mm:ss.SSS`, `YYYY-MM-DD HH:mm:ss`, `HH:mm:ss`, `HH:mm:ss.SSS`, `MMMM D, YYYY HH:mm:ss`, `dddd, MMMM D, YYYY HH:mm:ss`, or `Custom`.
* **Lock First Column**: Lock the first column so that the listings are always visible. Threshold settings do not apply in the first column when locked.
* **Customize Field**:
- **time**: Enter a new name to rename.
- [additional]: Enter name for each additional column.
- Change the order of the column by dragging to the desired position.
* **Thresholds**
> **Note:** Threshold settings apply to any cells with values, except when they appear in the first column and **Lock First Column** is enabled.
- **Add Threshold** (button): Click to add a threshold.
- **Base Color**: Select a base, or background, color from the selection list.
* Color options: Ruby, Fire, Curacao, Tiger, Pineapple, Thunder, Honeydew, Rainforest, Viridian, Ocean, Pool, Laser (default), Planet, Star, Comet, Pepper, Graphite, White, and Castle.
#### Table view example
![Table example](/img/chronograf/chrono-viz-table-example.png)
### Note
The **Note** panel displays Markdown-formatted text with your graph.
![Note selector](/img/chronograf/chrono-viz-note-selector.png)
#### Note Controls
![Note Controls](/img/chronograf/chrono-viz-note-controls.png)
Enter your text in the **Add a Note** panel, using Markdown to format the text.
Enable the **Display note in cell when query returns no results** option to display the note text in the cell instead of `No Results`.
#### Note view example
![Note example](/img/chronograf/chrono-viz-note-example.png)

25
content/chronograf/v1.8/introduction/_index.md Normal file
View File

@ -0,0 +1,25 @@
---
title: Introducing Chronograf
description: An introduction to Chronograf, the user interface and data visualization component for the InfluxData Platform. Includes documentation on getting started, installation, and downloading.
menu:
chronograf_1_8:
name: Introduction
weight: 20
---
Follow the links below to get acquainted with Chronograf:
## [Downloading Chronograf](https://portal.influxdata.com/downloads)
Chronograf is supported on several operating systems and hardware architectures.
See the [InfluxData downloads page](https://portal.influxdata.com/downloads) page for to the available binaries.
## [Installing Chronograf](/chronograf/latest/introduction/installation/)
[Installing Chronograf](/chronograf/latest/introduction/installation/) lists the requirements for installing, starting, and configuring Chronograf.
## Getting Started
[Getting started with Chronograf](/chronograf/latest/introduction/getting-started/) gets you up and running with Chronograf with as little configuration and code as possible.
By the end of the guide, you will have downloaded, installed, and configured all four packages of the
TICK stack ([Telegraf](https://github.com/influxdata/telegraf), [InfluxDB](https://github.com/influxdata/influxdb), Chronograf, and [Kapacitor](https://github.com/influxdata/kapacitor)), and you will be all set to monitor your infrastructure.

12
content/chronograf/v1.8/introduction/downloading.md Normal file
View File

@ -0,0 +1,12 @@
---
title: Downloading Chronograf
menu:
chronograf_1_8:
name: Downloading
weight: 10
parent: Introduction
---
Download the latest Chronograf release at the [InfluxData download page](https://portal.influxdata.com/downloads).

28
content/chronograf/v1.8/introduction/getting-started.md Normal file
View File

@ -0,0 +1,28 @@
---
title: Getting started with Chronograf
aliases:
- /chronograf/latest/introduction/getting-started/
- /chronograf/v1.8/introduction/getting_started/
menu:
chronograf_1_8:
name: Getting started
weight: 30
parent: Introduction
---
## Overview
Chronograf allows you to quickly see data you have stored in InfluxDB so you can build robust queries and alerts. After your administrator has set up Chronograf as described in [Installing Chronograf](/chronograf/latest/introduction/installation), get started with key features using the guides below.
### Data visualization
* Investigate your data by building queries using the [Data Explorer](/chronograf/latest/guides/querying-data/).
* Use [pre-created dashboards](/chronograf/latest/guides/using-precreated-dashboards/) to monitor your application data or [create your own dashboards](/chronograf/latest/guides/create-a-dashboard/).
* Customize dashboards using [template variables](/chronograf/latest/guides/dashboard-template-variables/).
### Alerting
* [Create alert rules](/chronograf/latest/guides/create-alert-rules/) to generate threshold, relative, and deadman alerts on your data.
* [View all active alerts](/chronograf/latest/guides/create-alert-rules/#step-2-view-the-alerts) on an alert dashboard.
* Use [alert endpoints](/chronograf/latest/guides/configuring-alert-endpoints/) in Chronograf to send alert messages to specific URLs and applications.
### Infrastructure monitoring
* [View all hosts](/chronograf/latest/guides/monitoring-influxenterprise-clusters/#step-4-explore-the-monitoring-data-in-chronograf) and their statuses in your infrastructure.
* [Use pre-created dashboards](/chronograf/latest/guides/using-precreated-dashboards/) to monitor your applications.

84
content/chronograf/v1.8/introduction/installation.md Normal file
View File

@ -0,0 +1,84 @@
---
title: Installing Chronograf
menu:
chronograf_1_8:
name: Installing
weight: 20
parent: Introduction
---
This page describes how to download and install Chronograf.
### Content
* [TICK overview](#tick-overview)
* [Download and install](#download-and-install)
* [Connect to your InfluxDB instance or InfluxDB Enterprise cluster](#connect-chronograf-to-your-influxdb-instance-or-influxdb-enterprise-cluster)
* [Connect to Kapacitor](#connect-chronograf-to-kapacitor)
## TICK overview
Chronograf is the user interface for InfluxData's [TICK stack](https://www.influxdata.com/time-series-platform/).
## Download and install
The latest Chronograf builds are available on InfluxData's [Downloads page](https://portal.influxdata.com/downloads).
1. Choose the download link for your operating system.
{{% note %}}
If your download includes a TAR package, save the underlying datastore `chronograf-v1.db` in directory outside of where you start Chronograf. This preserves and references your existing datastore, including configurations and dashboards, when you download future versions.
{{% /note %}}
2. Install Chronograf, replacing `<version#>` with the appropriate version:
{{% tabs-wrapper %}}
{{% tabs %}}
[macOS](#)
[Ubuntu & Debian](#)
[RedHat & CentOS](#)
{{% /tabs %}}
{{% tab-content %}}
```sh
tar zxvf chronograf-<version#>_darwin_amd64.tar.gz
```
{{% /tab-content %}}
{{% tab-content %}}
```sh
sudo dpkg -i chronograf_<version#>_amd64.deb
```
{{% /tab-content %}}
{{% tab-content %}}
```sh
sudo yum localinstall chronograf-<version#>.x86_64.rpm
```
{{% /tab-content %}}
{{% /tabs-wrapper %}}
3. Start Chronograf:
```sh
chronograf
```
## Connect Chronograf to your InfluxDB instance or InfluxDB Enterprise cluster
1. Point your web browser to [localhost:8888](http://localhost:8888).
2. Fill out the form with the following details:
* **Connection String**: Enter the hostname or IP of the machine that InfluxDB is running on, and be sure to include InfluxDB's default port `8086`.
* **Connection Name**: Enter a name for your connection string.
* **Username** and **Password**: These fields can remain blank unless you've [enabled authentication](/influxdb/v1.8/administration/authentication_and_authorization.md) in InfluxDB.
* **Telegraf Database Name**: Optionally, enter a name for your Telegraf database. The default name is Telegraf.
3. Click **Add Source**.
## Connect Chronograf to Kapacitor
1. In Chronograf, click the configuration (wrench) icon in the sidebar menu, then select **Add Config** in the **Active Kapacitator** column.
2. In the **Kapacitor URL** field, enter the hostname or IP of the machine that Kapacitor is running on. Be sure to include Kapacitor's default port: `9092`.
3. Enter a name for your connection.
4. Leave the **Username** and **Password** fields blank unless you've specifically enabled authorization in Kapacitor.
5. Click **Connect**.

18
content/chronograf/v1.8/tools/_index.md Normal file
View File

@ -0,0 +1,18 @@
---
title: Chronograf Tools
description: Chronograf provides command line tools designed to aid in managing and working with Chronograf from the command line.
menu:
chronograf_1_8:
name: Tools
weight: 40
---
Chronograf provides command line tools designed to aid in managing and working with Chronograf from the command line. The following command line interfaces (CLIs) are available:
## [`chronograf` command line interface](/chronograf/v1.8/tools/chronograf-cli/)
The `chronograf` command line interface (CLI) includes options to manage Chronograf security.
## [`chronoctl` command line interface](/chronograf/v1.8/tools/chronoctl/)
The `chronoctl` command line interface (CLI) includes commands to interact with an instance of Chronograf's data store.

25
content/chronograf/v1.8/tools/chronoctl/_index.md Normal file
View File

@ -0,0 +1,25 @@
---
title: chronoctl
description: The `chronoctl` command line interface (CLI) includes commands to interact with an instance of Chronograf's data store.
menu:
chronograf_1_8:
name: chronoctl
parent: Tools
weight: 10
---
The `chronoctl` command line interface (CLI) includes commands to interact with an instance of Chronograf's data store.
## Usage
```
chronoctl [command]
chronoctl [flags]
```
## Commands
| Command | Description |
|:------- |:----------- |
| [add-superadmin](/chronograf/v1.8/tools/chronoctl/add-superadmin/) | Create a new user with superadmin status |
| [list-users](/chronograf/v1.8/tools/chronoctl/list-users) | List all users in the Chronograf data store |
| [migrate](/chronograf/v1.8/tools/chronoctl/migrate) | Migrate your Chronograf configuration store |

26
content/chronograf/v1.8/tools/chronoctl/add-superadmin.md Normal file
View File

@ -0,0 +1,26 @@
---
title: chronoctl add-superadmin
description: The `add-superadmin` command creates a new user with superadmin status.
menu:
chronograf_1_8:
name: chronoctl add-superadmin
parent: chronoctl
weight: 20
---
The `add-superadmin` command creates a new user with superadmin status.
## Usage
```
chronoctl add-superadmin [flags]
```
## Flags
| Flag | Description | Input type |
| :--------------------- | :---------------------------------------------------------------------------------------------------- | :--------: |
| `-b`, `--bolt-path` | Full path to boltDB file (e.g. './chronograf-v1.db')" env:"BOLT_PATH" default:"chronograf-v1.db" | string |
| `-i`, `--id` | User ID for an existing user | uint64 |
| `-n`, `--name` | User's name. Must be Oauth-able email address or username. | |
| `-p`, `--provider` | Name of the Auth provider (e.g. Google, GitHub, auth0, or generic) | string |
| `-s`, `--scheme` | Authentication scheme that matches auth provider (default:oauth2) | string |
| `-o`, `--orgs` | A comma-separated list of organizations that the user should be added to (default:"default") | string |

22
content/chronograf/v1.8/tools/chronoctl/list-users.md Normal file
View File

@ -0,0 +1,22 @@
---
title: chronoctl list-users
description: The `list-users` command lists all users in the Chronograf data store.
menu:
chronograf_1_8:
name: chronoctl list-users
parent: chronoctl
weight: 30
---
The `list-users` command lists all users in the Chronograf data store.
## Usage
```
chronoctl list-users [flags]
```
## Flags
| Flag | Description | Input type |
| :--------------------- | :---------------------------------------------------------------------------------------------------- | :--------: |
| `--b`, `--bolt-path` | Full path to boltDB file (e.g. './chronograf-v1.db')" env:"BOLT_PATH" (default:chronograf-v1.db) | string |

25
content/chronograf/v1.8/tools/chronoctl/migrate.md Normal file
View File

@ -0,0 +1,25 @@
---
title: chronoctl migrate
description: The `migrate` command allows you to migrate your Chronograf configuration store.
menu:
chronograf_1_8:
name: chronoctl migrate
parent: chronoctl
weight: 40
---
The `migrate` command lets you migrate your Chronograf configuration store.
By default, Chronograf is delivered with BoltDB as a data store. For information on migrating from BoltDB to an etc cluster as a data store, see [Migrating to a Chronograf HA configuration](/chronograf/v1.8
/administration/migrate-to-high-availability-etcd/).
## Usage
```
chronoctl migrate [flags]
```
## Flags
| Flag | Description | Input type |
|:---- |:----------- |:----------: |
| `-f`, `--from` | Full path to BoltDB file or etcd (e.g. 'bolt:///path/to/chronograf-v1.db' or 'etcd://user:pass@localhost:2379 (default: chronograf-v1.db) | string |
| `-t`, `--to` | Full path to BoltDB file or etcd (e.g. 'bolt:///path/to/chronograf-v1.db' or 'etcd://user:pass@localhost:2379 (default: etcd://localhost:2379) | string |

122
content/chronograf/v1.8/tools/chronograf-cli/_index.md Normal file
View File

@ -0,0 +1,122 @@
---
title: chronograf cli
description: The `chronograf` command line interface (CLI) includes options to manage many aspects of Chronograf security.
menu:
chronograf_1_8:
name: chronograf CLI
parent: Tools
weight: 10
---
The `chronograf` command line interface (CLI) includes options to manage Chronograf security.
## Usage
```
chronograf [flags]
```
## Chronograf service flags
| Flag | Description | Default | Env. Variable |
|-----------------------|-------------------------------------------------------------------------------------------|-----------------------------------------|--------------------|
| `--host` | IP the Chronograf service listens on | `0.0.0.0` | `$HOST` |
| `--port` | Port the Chronograf service listens on for insecure connections | `8888` | `$PORT` |
| `-b`,`--bolt-path` | File path to the BoltDB file | `./chronograf-v1.db` | `$BOLT_PATH` |
| `-c`,`--canned-path` | File path to the directory of canned dashboard files | `/usr/share/chronograf/canned` | `$CANNED_PATH` |
| `--resources-path` | Path to directory of canned dashboards, sources, Kapacitor connections, and organizations | `/usr/share/chronograf/resources` | `$RESOURCES_PATH` |
| `-b`, `--basepath` | URL path prefix under which all Chronograf routes will be mounted. | | `$BASE_PATH` |
| `--status-feed-url` | URL of JSON feed to display as a news feed on the client status page | `https://www.influxdata.com/feed/json` | `$STATUS_FEED_URL` |
| `-v`, `--version` | Displays the version of the Chronograf service | | |
| `-h`, `--host-page-disabled` | Disables the hosts page | | `$HOST_PAGE_DISABLED` |
## InfluxDB connection flags
| Flag | Description | Env. Variable |
|-----------------------|-------------------------------------------------------------------------------|----------------------|
| `--influxdb-url` | Location of your InfluxDB instance, including `http://`, IP address, and port | `$INFLUXDB_URL` |
| `--influxdb-username` | Username for your InfluxDB instance | `$INFLUXDB_USERNAME` |
| `--influxdb-password` | Password for your InfluxDB instance | `$INFLUXDB_PASSWORD` |
## Kapacitor connection flags
| Flag | Description | Env. Variable |
|------------------------|--------------------------------------------------------------------------------|-----------------------|
| `--kapacitor-url` | Location of your Kapacitor instance, including `http://`, IP address, and port | `$KAPACITOR_URL` |
| `--kapacitor-username` | Username for your Kapacitor instance | `$KAPACITOR_USERNAME` |
| `--kapacitor-password` | Password for your Kapacitor instance | `$KAPACITOR_PASSWORD` |
## TLS (Transport Layer Security) flags
| Flag | Description | Env. Variable |
|---------|------------------------------------------------------------|--------------------|
| `--cert | File path to PEM-encoded public key certificate | `$TLS_CERTIFICATE` |
| `--key` | File path to private key associated with given certificate | `$TLS_PRIVATE_KEY` |
## Other service option flags
| Flag | Description | Env. Variable |
|----------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------|
| `--custom-link <display_name>:<link_address> | Custom link added to Chronograf user menu options. Useful for providing links to internal company resources for your Chronograf users. Can be used when any OAuth 2.0 authentication is enabled. To add another custom link, repeat the custom link option. | |
| `-r`, `--reporting-disabled` | Disables reporting of usage statistics. Usage statistics reported once every 24 hours include: `OS`, `arch`, `version`, `cluster_id`, and `uptime`. | `$REPORTING_DISABLED` |
| `-l`, `--log-level` | Sets the logging level. Valid values include `info` (default), `debug`, and `error`. | `$LOG_LEVEL` |
| `-d`, `--develop` | Runs the Chronograf service in developer mode | |
| `-h`, `--help` | Displays command line help for Chronograf | |
## Authentication option flags
### General authentication flags
| Flag | Description | Env. Variable |
|------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------|
| `-t`, `--token-secret` | Secret for signing tokens | `$TOKEN_SECRET` |
| `--auth-duration` | Total duration, in hours, of cookie life for authentication. Default value is `720h`. | `$AUTH_DURATION` |
| `--public-url` | Public URL required to access Chronograf using a web browser. For example, if you access Chronograf using the default URL, the public URL value would be `http://localhost:8888`. Required for Google OAuth 2.0 authentication. Used for Auth0 and some generic OAuth 2.0 authentication providers. | `$PUBLIC_URL` |
### GitHub-specific OAuth 2.0 authentication flags
| Flag | Description | Env. Variable |
|--------------------------------|-------------------------------------------------------------------------|---------------------|
| `-i`, `--github-client-id` | GitHub client ID value for OAuth 2.0 support | `$GH_CLIENT_ID` |
| `-s`, `--github-client-secret` | GitHub client secret value for OAuth 2.0 support | `$GH_CLIENT_SECRET` |
| `-o`, `--github-organization` | Specify a GitHub organization membership required for a user. Optional. | `$GH_ORGS` |
### Google-specific OAuth 2.0 authentication flags
| Flag | Description | Env. Variable |
|--------------------------|---------------------------------------------------------------------------------|-------------------------|
| `--google-client-id` | Google client ID value for OAuth 2.0 support | `$GOOGLE_CLIENT_ID` |
| `--google-client-secret` | Google client secret value for OAuth 2.0 support | `$GOOGLE_CLIENT_SECRET` |
| `--google-domains` | Restricts authorization to users from specified Google email domains. Optional. | `$GOOGLE_DOMAINS` |
### Auth0-specific OAuth 2.0 authentication flags
| Flag | Description | Env. Variable |
|-------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------|
| `--auth0-domain` | Subdomain of your Auth0 client. Available on the configuration page for your Auth0 client. | `$AUTH0_DOMAIN` |
| `--auth0-client-id` | Auth0 client ID value for OAuth 2.0 support | `$AUTH0_CLIENT_ID` |
| `--auth0-client-secret` | Auth0 client secret value for OAuth 2.0 support | `$AUTH0_CLIENT_SECRET` |
| `--auth0-organizations` | Auth0 organization membership required to access Chronograf. Organizations are set using an organization key in the user’s `app_metadata`. Lists are comma-separated and are only available when using environment variables. | `$AUTH0_ORGS` |
### Heroku-specific OAuth 2.0 authentication flags
| Flag | Description | Env. Variable |
|-------------------------|------------------------------------------------------------------------------------------|---------------------|
| `--heroku-client-id` | Heroku client ID value for OAuth 2.0 support | `$HEROKU_CLIENT_ID` |
| `--heroku-secret` | Heroku secret for OAuth 2.0 support | `$HEROKU_SECRET` |
| `--heroku-organization` | Heroku organization membership required to access Chronograf. Lists are comma-separated. | `$HEROKU_ORGS` |
### Generic OAuth 2.0 authentication flags
| Flag | Description | Env. Variable |
|---------------------------|--------------------------------------------------------------------------------|--------------------------|
| `--generic-name` | Generic OAuth 2.0 name presented on the login page | `$GENERIC_NAME` |
| `--generic-client-id` | Generic OAuth 2.0 client ID value. Can be used for a custom OAuth 2.0 service. | `$GENERIC_CLIENT_ID` |
| `--generic-client-secret` | Generic OAuth 2.0 client secret value | `$GENERIC_CLIENT_SECRET` |
| `--generic-scopes` | Scopes requested by provider of web client | `$GENERIC_SCOPES` |
| `--generic-domains` | Email domain required for user email addresses | `$GENERIC_DOMAINS` |
| `--generic-auth-url` | Authorization endpoint URL for the OAuth 2.0 provider | `$GENERIC_AUTH_URL` |
| `--generic-token-url` | Token endpoint URL for the OAuth 2.0 provider | `$GENERIC_TOKEN_URL` |
| `--generic-api-url` | URL that returns OpenID UserInfo-compatible information | `$GENERIC_API_URL` |

12
content/chronograf/v1.8/troubleshooting/_index.md Normal file
View File

@ -0,0 +1,12 @@
---
title: Troubleshooting Chronograf
menu:
chronograf_1_8:
name: Troubleshooting
weight: 50
---
Follow the link below to access Chronograf's FAQ.
## [Frequently Asked Questions](/chronograf/latest/troubleshooting/frequently-asked-questions/)

22
content/chronograf/v1.8/troubleshooting/frequently-asked-questions.md Normal file
View File

@ -0,0 +1,22 @@
---
title: Chronograf frequently asked questions (FAQ)
menu:
chronograf_1_8:
name: Frequently asked questions (FAQ)
weight: 10
parent: Troubleshooting
---
## How do I connect Chronograf to an InfluxEnterprise cluster?
The connection details form requires additional information when connecting Chronograf to an [InfluxEnterprise cluster](https://docs.influxdata.com/enterprise_influxdb/latest/).
When you enter the InfluxDB HTTP bind address in the `Connection String` input, Chronograf automatically checks if that InfluxDB instance is a data node.
If it is a data node, Chronograf automatically adds the `Meta Service Connection URL` input to the connection details form.
Enter the HTTP bind address of one of your cluster's meta nodes into that input and Chronograf takes care of the rest.
![Cluster connection details](/img/chronograf/v1.8/faq-cluster-connection.png)
Note that the example above assumes that you do not have authentication enabled.
If you have authentication enabled, the form requires username and password information.
For more details about monitoring an InfluxEnterprise cluster, see the [Monitor an InfluxEnterprise Cluster](/chronograf/latest/guides/monitoring-influxenterprise-clusters/) guide.