diff --git a/.gitignore b/.gitignore index 6aabb82d6c3..0a59fd81900 100644 --- a/.gitignore +++ b/.gitignore @@ -1,7 +1,9 @@ node_modules coverage/ .aws-config.json -dist +awsconfig +/dist +/tmp # locally required config files web.config @@ -12,3 +14,10 @@ src/css/*.min.css *.sublime-workspace *.swp .idea/ +*.iml + +/data/* +/bin/* + +conf/custom.ini +fig.yml diff --git a/docs/Dockerfile b/docs/Dockerfile new file mode 100644 index 00000000000..69f47e82d08 --- /dev/null +++ b/docs/Dockerfile @@ -0,0 +1,23 @@ +FROM grafana/docs-base:latest + +# TODO: need the full repo source to get the git version info +COPY . /src + +# Reset the /docs dir so we can replace the theme meta with the new repo's git info +RUN git reset --hard + +# Then copy the desired docs into the /docs/sources/ dir +COPY ./sources/ /docs/sources + +COPY ./VERSION VERSION + +# adding the image spec will require Docker 1.5 and `docker build -f docs/Dockerfile .` +#COPY ./image/spec/v1.md /docs/sources/reference/image-spec-v1.md + +# TODO: don't do this - look at merging the yml file in build.sh +COPY ./mkdocs.yml /docs/mkdocs.yml + +COPY ./s3_website.json /docs/s3_website.json + +# Then build everything together, ready for mkdocs +RUN /docs/build.sh diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 00000000000..5a111e2eff4 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,47 @@ +.PHONY: all binary build cross default docs docs-build docs-shell shell test test-unit test-integration test-integration-cli test-docker-py validate + +# env vars passed through directly to Docker's build scripts +# to allow things like `make DOCKER_CLIENTONLY=1 binary` easily +# `docs/sources/contributing/devenvironment.md ` and `project/PACKAGERS.md` have some limited documentation of some of these +DOCKER_ENVS := \ + -e BUILDFLAGS \ + -e DOCKER_CLIENTONLY \ + -e DOCKER_EXECDRIVER \ + -e DOCKER_GRAPHDRIVER \ + -e TESTDIRS \ + -e TESTFLAGS \ + -e TIMEOUT +# note: we _cannot_ add "-e DOCKER_BUILDTAGS" here because even if it's unset in the shell, that would shadow the "ENV DOCKER_BUILDTAGS" set in our Dockerfile, which is very important for our official builds + +# to allow `make DOCSDIR=docs docs-shell` (to create a bind mount in docs) +DOCS_MOUNT := $(if $(DOCSDIR),-v $(CURDIR)/$(DOCSDIR):/$(DOCSDIR)) + +# to allow `make DOCSPORT=9000 docs` +DOCSPORT := 8180 + +GIT_BRANCH := $(shell git rev-parse --abbrev-ref HEAD 2>/dev/null) +DOCKER_DOCS_IMAGE := grafana-docs-base$(if $(GIT_BRANCH),:$(GIT_BRANCH)) + +DOCKER_RUN_DOCS := docker run --rm -it $(DOCS_MOUNT) -e AWS_S3_BUCKET -e NOCACHE + +# for some docs workarounds (see below in "docs-build" target) +GITCOMMIT := $(shell git rev-parse --short HEAD 2>/dev/null) + +default: docs + +docs: docs-build + $(DOCKER_RUN_DOCS) -p $(if $(DOCSPORT),$(DOCSPORT):)8000 "$(DOCKER_DOCS_IMAGE)" mkdocs serve + +docs-shell: docs-build + $(DOCKER_RUN_DOCS) -p $(if $(DOCSPORT),$(DOCSPORT):)8000 "$(DOCKER_DOCS_IMAGE)" bash + +docs-release: docs-build + $(DOCKER_RUN_DOCS) -e OPTIONS -e BUILD_ROOT -e DISTRIBUTION_ID \ + -v $(CURDIR)/awsconfig:/docs/awsconfig \ + "$(DOCKER_DOCS_IMAGE)" ./release.sh + +docs-test: docs-build + $(DOCKER_RUN_DOCS) "$(DOCKER_DOCS_IMAGE)" ./test.sh + +docs-build: + docker build -t "$(DOCKER_DOCS_IMAGE)" . diff --git a/docs/VERSION b/docs/VERSION new file mode 100644 index 00000000000..9ab8337f396 --- /dev/null +++ b/docs/VERSION @@ -0,0 +1 @@ +1.9.1 diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml new file mode 100644 index 00000000000..67944930fa5 --- /dev/null +++ b/docs/mkdocs.yml @@ -0,0 +1,54 @@ +site_name: Grafana Documentation +#site_url: http://docs.grafana.com/ +site_url: / +site_description: Documentation for Grafana, The Graphite and Influxdb dashboard and graph composer +site_favicon: img/fav32.png + +dev_addr: '0.0.0.0:8000' + +repo_url: https://github.com/grafana/grafana/ + +docs_dir: sources + +include_search: true + +use_absolute_urls: true + +# theme: docker +theme_dir: ./theme/mkdocs/ +theme_center_lead: false + +copyright: Copyright © 2014-2015, Coding Instinct AB. +google_analytics: ['UA-47280256-1', 'grafana.org'] + + +pages: + +# Introduction: +- ['index.md', 'About', 'Grafana'] +- ['installation/installation.md', 'Installation', 'Install & Configure'] +- ['installation/provisioning.md', 'Installation', 'Provisioning'] +- ['installation/performance.md', 'Installation', 'Performance tips'] +- ['installation/troubleshooting.md', 'Installation', 'Troubleshooting'] + +- ['features/intro.md', 'User Guides', 'Getting started'] +- ['features/graphs.md', 'User Guides', 'Graph options'] +- ['features/annotations.md', 'User Guides', 'Annotations'] +- ['features/time_range.md', 'User Guides', 'Time range controls'] +- ['features/search.md', 'User Guides', 'Search features'] +- ['features/templated_dashboards.md', 'User Guides', 'Templated dashboards'] +- ['features/scripted_dashboards.md', 'User Guides', 'Scripted dashboards'] +- ['features/playlist.md', 'User Guides', 'Playlist'] +- ['features/export_import.md', 'User Guides', 'Import & Export'] +- ['screencasts/index.md', 'User Guides', 'Screencasts'] + +- ['features/graphite.md', 'Metric Queries', 'Graphite guide'] +- ['features/influxdb.md', 'Metric Queries', 'InfluxDB guide'] +- ['features/opentsdb.md', 'Metric Queries', 'OpenTSDB guide'] + +- ['contributing/building_from_source.md', 'Contribute', 'Building from souce'] +- ['contributing/cla.md', 'Contribute', 'Contributor License Agreement'] + +- ['support/index.md', 'Support', 'Support'] + +- ['jsearch.md', '**HIDDEN**'] diff --git a/docs/s3_website.json b/docs/s3_website.json new file mode 100644 index 00000000000..b0747526d75 --- /dev/null +++ b/docs/s3_website.json @@ -0,0 +1,11 @@ +{ + "ErrorDocument": { + "Key": "jsearch/index.html" + }, + "IndexDocument": { + "Suffix": "index.html" + }, + "RoutingRules": [ + { "Condition": { "KeyPrefixEquals": "jsearch/index.html" }, "Redirect": { "HostName": "$BUCKET", "ReplaceKeyPrefixWith": "jsearch/" } } + ] +} diff --git a/docs/sources/contributing/building_from_source.md b/docs/sources/contributing/building_from_source.md new file mode 100644 index 00000000000..14521268a9d --- /dev/null +++ b/docs/sources/contributing/building_from_source.md @@ -0,0 +1,37 @@ +--- +page_title: Building from source +page_description: Building from source Grafana. +page_keywords: grafana, build, contribute, documentation +--- + +# Building from source + +If you have any idea for an improvement or found a bug do not hesitate to open an issue. +And if you have time clone [the grafana repository](https://github.com/grafana/grafana) and submit a pull request and help me make Grafana +the kickass metrics & devops dashboard we all dream about! + +Grafana uses nodejs and grunt as a build system for javascript, less compilation, and unit tests. + +## Get started + + - Install nodejs. + - npm install -g grunt-cli + - npm install (in grafana repository root) + +### run development server + + - grunt server + +### run less & jshint checks + - grunt + +### run unit tests + - grunt test + +### create optimized, minified build + - grunt build (or grunt release to get zip/tar files) + + +## Create a pull requests + +Before or after your create a pull requests, sign the [contributor license aggrement](/docs/contributing/cla.html). diff --git a/docs/sources/contributing/cla.md b/docs/sources/contributing/cla.md new file mode 100644 index 00000000000..d6462d135ee --- /dev/null +++ b/docs/sources/contributing/cla.md @@ -0,0 +1,84 @@ +--- +page_title: Grafana CLA +page_description: Grafana Contributor License Agreement +page_keywords: grafana, cla, contribute, documentation +--- + +# Grafana Contributor License Agreement + +## Why is this agreement necessary? +We very much appreciate your wanting to contribute to Grafana, +but we need to add you to the contributors list first. + + +Note that the following agreement is not a transfer of copyright ownership, +this simply is a license agreement for contributions. You also do not change +your rights to use your own contributions for any other purpose. + + +For some background on why contributor license agreements are necessary, +you can read FAQs from many other open source projects: + +- [Django's excellent CLA FAQ](https://www.djangoproject.com/foundation/cla/faq/) +- [A well-written chapter from Karl Fogel's Producing Open Source Software on CLAs](http://producingoss.com/en/copyright-assignment.html) +- [The Wikipedia article on CLAs](http://en.wikipedia.org/wiki/Contributor_license_agreement) + +This is part of the legal framework of the open-source ecosystem that adds some red tape, +but protects both the contributor and the company / foundation behind the project. +It also gives us the option to relicense the code with a more permissive license in the future. + + +If you have more questions, shoot us an email or drop by #grafana on IRC (freenode). + +Many thanks to [RethinkDB](http://rethinkdb.com) for permission to re-use their CLA! +h2 Terms of the Agreement + +--- + +This Contributor License Agreement (“Agreement”) is entered into between Coding Instinct AB, +a Swedish corporation (“Grafana,” “we” or “us” etc.) and you (as defined and further identified below). +Accordingly, you hereby agree to the following terms for your past, present and future contributions +submitted to Grafana: + + +**1. Definitions:** +(a) "You" (or "your") shall mean the contribution copyright owner (whether an individual or organization) or legal entity authorized by the copyright owner that is making this Agreement with Grafana. + + +(b) "Contribution(s)" shall mean the code, documentation or other original works of authorship, including any modifications or additions to an existing work, submitted by you to Grafana for inclusion in, or documentation of, any of the products or projects owned or managed by Grafana (the "work(s)"). For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to Grafana or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, Grafana for the purpose of discussing and/or improving the work, but excluding communication that is conspicuously marked or otherwise designated in writing by you as "Not a Contribution." + +**2. Grant of Copyright License.** +You hereby grant to Grafana and to recipients of software distributed by Grafana a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare derivative works of, publicly display, publicly perform, sublicense, and distribute your contributions and such derivative works. + + +**3. Grant of Patent License.** +With respect to any patents you own, or that you can license without payment to any third party, you hereby grant Grafana a perpetual, irrevocable, non-exclusive, worldwide, no-charge, royalty-free license to: (i) make, have made, use, sell, offer to sell, import, and otherwise distribute and exploit your contributions in whole or in part, alone or in combination with or included in any product, work or materials arising out of or relating to the Works to which your contributions were submitted; and (ii) sublicense these same rights to third parties through multiple levels of sublicensees or other licensing arrangements. + + +**4. Rights.** +Except as set out above, you keep all right, title, and interest in your contribution. The rights that you grant to us under this agreement are effective on the date you first submitted a contribution to us, even if your submission took place before the date you entered this agreement. + + +**5. You represent and warrant that:** +(i) the contributions are an original work and that you can legally grant the rights set out in this agreement; + + +(ii) the contributions and Grafana’s exercise of any license rights granted hereunder, does not and will not, infringe the rights of any third party; + + +(iii) you are not aware of any pending or threatened claims, suits, actions, or charges pertaining to the contributions, including without limitation any claims or allegations that any or all of the contributions infringes, violates, or misappropriate the intellectual property rights of any third party (you further agree that you will notify Grafana immediately if you become aware of any such actual or potential claims, suits, actions, allegations or charges). + + +**6. Employer Rights.** +If your employer(s) has rights to intellectual property that you create that includes your contributions, you represent and warrant that your employer has waived such rights for your contributions to Grafana, or that you have received permission to make contributions on behalf of that employer and that you are authorized to execute this agreement on behalf of your employer. + + +**7. Support.** +You are not expected to provide support for your contributions, except to the extent you desire to provide support. You may provide support for free, for a fee, or not at all. Except as set forth herein, and unless required by applicable law or agreed to in writing, you provide your contributions on an "as is" basis, without warranties or conditions of any kind. + + +**8. Enforcement.** +The failure of either party to enforce its rights under this agreement for any period shall not be construed as a waiver of such rights. No changes or modifications or waivers to this Agreement will be effective unless in writing and signed by both parties. In the event that any provision of this agreement shall be determined to be illegal or unenforceable, that provision will be limited or eliminated to the minimum extent necessary so that this agreement shall otherwise remain in full force and effect and enforceable. This agreement shall be governed by and construed in accordance with the laws of the State of California in the United States without regard to the conflicts of laws provisions thereof. In any action or proceeding to enforce rights under this agreement, the prevailing party will be entitled to recover costs and attorneys’ fees. + + + diff --git a/docs/sources/features/annotations.md b/docs/sources/features/annotations.md new file mode 100644 index 00000000000..37bf84cb891 --- /dev/null +++ b/docs/sources/features/annotations.md @@ -0,0 +1,47 @@ +---- +page_title: Annotations +page_description: Annotations user guide +page_keywords: grafana, annotations, guide, documentation +--- + +# Annotations +![](/img/v1/annotated_graph1.png) + +Annotations provide a way to mark points on the graph with rich events. When you hover over an annotation +you can get title, tags, and text information for the event. + +To enable annotations open dashboard settings and the controls tab. +Under feature toggles you will find the checkbox for annotations. + +When enabled they will appear in the sub menu controls area. +![](/img/v1/annotations_submenu1.png) + +Click the cog wheel to open the dialog where you can add & edit annotations. +![](/img/v1/annotations_dialog1.png) + +## Datasources +Grafana supports many data sources for annotation. + +- Graphite metrics +- Graphite events +- InfluxDB query +- Elasticsearch query + +## InfluxDB Annotations +![](/img/influxdb/influxdb_annotation.png) + +For InfluxDB you need to enter a query like in the above screenshot. You need to have the ```where $timeFilter``` part. +If you only select one column you will not need to enter anything in the column mapping fields. +If you have multiple columns you need to specify which column should be treated as title, tags and text column. + +## Elasticsearch Annotations +![](/img/v1/elasticsearch_annotations_edit.png) + +You can use the same data source as you specified in config.js for storing grafana dashboards or you can specify another one. +The annotation definition contains an index name that will override the index name specified in config.js. The index name can +be the name of an alias or an index wildcard pattern. You can leave the search query blank or specify a lucene query. + +If your elasticsearch document has a timestamp field other than ```@timestamp``` you will need to specify that. As well +as the name for the fields that should be used for the annotation title, tags and text. Tags and text are optional. + +**The annotation timestamp field in elasticsearch need to be in UTC format** diff --git a/docs/sources/features/export_import.md b/docs/sources/features/export_import.md new file mode 100644 index 00000000000..bfcdd7bd0d1 --- /dev/null +++ b/docs/sources/features/export_import.md @@ -0,0 +1,50 @@ +--- +page_title: Export & Import Guide +page_description: Export & Import Guide for Grafana +page_keywords: grafana, export, import, documentation +--- + +# Export and Import + +## Export (Json file) + +Load the dashboard you wish to export (e.g. via search) + +Click on the "Save" icon (floppy disk) + +![](/img/v1/export_import_save_menu.png) + +Click on "Export schema" + +![](/img/v1/export_schema_link.png) + +Save file on local disk + +![](/img/v1/export_save_file.png) + +## Import + +Click the "Search" icon (open folder) + +![](/img/v1/export_import_search_menu.png) + +Click "Import" button + +![](/img/v1/export_import_button.png) + +Click "Browse" button and browse to previously exported dashboard on local disk (which should be a valid Json file) + +![](/img/v1/export_import_browse_button.png) + +Select exported dashboard + +![](/img/v1/export_import_popup.png) + + +Click "Save" icon to show save menu + +![](/img/v1/export_import_save_menu.png) + +Click new save icon (floppy disk) to Save newly imported dashboard + +![](/img/v1/export_import_save_dashboard.png) diff --git a/docs/sources/features/graphite.md b/docs/sources/features/graphite.md new file mode 100644 index 00000000000..e8523ce2dbb --- /dev/null +++ b/docs/sources/features/graphite.md @@ -0,0 +1,33 @@ +---- +page_title: Graphite query guide +page_description: Graphite query guide +page_keywords: grafana, graphite, metrics, query, documentation +--- + +# Graphite + +Grafana has an advanced graphite query editor that lets you quickly navigate the metric space, add functions. +Change function paramaters and much more. The editor cannot handle all types of queries yet. +To switch to a regular text box click the pen icon to the right. + +## Navigate metric segments + +Click the ``Select metric`` link to start navigating the metric space. One you start you can continue using the mouse +or keyboard arrow keys. You can select a wildcard and still continue. + +![](/img/animated_gifs/graphite_query1.gif) + +## Functions + +Click the plus icon to the right to add a function. You can search for the function or select it from the menu. Once +a function is selected it will be added and your focus will be in the text box of the first parameter. To later change +a parameter just click on it and it will turn into a text box. To delete a function click the function name followed +by the x icon. + +![](/img/animated_gifs/graphite_query2.gif) + + +### Optional parameters +Some functions like aliasByNode support an optional second argument. To add this parameter specify for example 3,-2 as the first parameter and the function editor will adapt and move the -2 to a second parameter. To remove the second optional parameter just click on it and leave it blank and the editor will remove it. + +![](/img/animated_gifs/func_editor_optional_params.gif) diff --git a/docs/sources/features/graphs.md b/docs/sources/features/graphs.md new file mode 100644 index 00000000000..67f573cc4b9 --- /dev/null +++ b/docs/sources/features/graphs.md @@ -0,0 +1,32 @@ +--- +title: Docs - Graphing +--- + +# Graphing + +The main panel for in Grafana is simply named Graph. It provides a very rich set of graphing options. + + + +## Axes, Grid & Legend options +![](/img/v1/graph_axes_grid_options.png) + +### Legens values + +Check ``Include Values`` under legend styles. + +- Total - Sum of all values returned from metric query +- Current - Last value returned from the metric query + +This means that if your series represents a rate, for example requests / second then the Total in the legend will +not represent the total number of requests. It is just the sum of all data points. + + +## Display options +![](/img/v1/graph_display_styles.png) + +If you have stack enabled you can select what the mouse hover feature should show. + +- Cumulative - Sum of series below plus the series you hover over +- Individual - Just the value for the series you hover over + diff --git a/docs/sources/features/influxdb.md b/docs/sources/features/influxdb.md new file mode 100644 index 00000000000..22b28f8729a --- /dev/null +++ b/docs/sources/features/influxdb.md @@ -0,0 +1,34 @@ +---- +page_title: InfluxDB query guide +page_description: InfluxDB query guide +page_keywords: grafana, influxdb, metrics, query, documentation +--- + + +# InfluxDB + +## InfluxDB query editor + +![](/img/v1/influxdb_editor.png) + +When you add an InfluxDB query you can specify series name (can be regex), value column and a function. Group by time can be specified or if left blank will be automatically set depending on how long the current time span is. It will translate to a InfluxDB query that looks like this: + +```sql +select [[func]]([[column]]) from [[series]] where [[timeFilter]] group by time([[interval]]) order asc +``` + +To write the complete query yourself click the cog wheel icon to the right and select ``Raw query mode``. + +## InfluxDB Filters & Templated queries + +![](/img/animated_gifs/influxdb_templated_query.gif) + + +Use a distinct influxdb query in the filter query input box: + +```sql +select distinct(host) from app.status +``` + + + diff --git a/docs/sources/features/intro.md b/docs/sources/features/intro.md new file mode 100644 index 00000000000..df936138483 --- /dev/null +++ b/docs/sources/features/intro.md @@ -0,0 +1,50 @@ +--- +page_title: Getting started +page_description: Getting started +page_keywords: grafana, guide, documentation +--- + +# Getting started +This guide will help you get started and acquainted with the Grafana user interface. + +## Interface overview + + +## New dashboard +![](/img/animated_gifs/new_dashboard.gif) + +## Edit graphs +Click on a panel's title and then ``Edit`` to open a panel in edit mode. +![](/img/v1/edit_graph_ui_guide.png) + +## Editing Rows +To the right of each row you have two colored rectangles, hover over these to get access to quick row controls. +![](/img/animated_gifs/row_edit_menu.gif) + +## Drag drop panels +Click and drag the panel title to start a drag and drop action. +![](/img/animated_gifs/drag_drop.gif) + +## Tips and shortcuts + +* Click the graph title and in the dropdown menu quickly change span or duplicate the panel. +* Ctrl+S Saves the current dashboard +* Ctrl+F Opens the dashboard finder / search +* Ctrl+H Hides all controls (good for tv displays) +* Hit Escape to exit graph when in fullscreen or edit mode +* Click the colored icon in the legend to select series color +* Click series name in the legend to hide series +* Ctrl/Shift/Meta + Click legend name to hide other series +* Click the Save icon in the menu to save the dashboard with a new name +* Click the Save icon in the menu and then advanced to export the dashboard to json file, or set it as your default dashboard. + + + + + + + + + + + diff --git a/docs/sources/features/opentsdb.md b/docs/sources/features/opentsdb.md new file mode 100644 index 00000000000..5ccd60dd034 --- /dev/null +++ b/docs/sources/features/opentsdb.md @@ -0,0 +1,113 @@ +--- +page_title: OpenTSDB Guide +page_description: OpenTSDB guide for Grafana +page_keywords: grafana, opentsdb, documentation +--- + +# OpenTSDB Guide + +Here you will find some configuration tips for how to setup Grafana and OpenTSDB. + +## OpenTSDB configuration + +For OpenTSDB to work in Grafana you will either be needing to run the latest OpenTSDB +version built from the `next` branch that includes built in support for remote +api usage (CORS). This was merged into the next branch with [this issue](https://github.com/OpenTSDB/opentsdb/pull/333). + +If you upgrade you have to set the OpenTSDB setting `tsd.http.request.cors_domains` to your +grafana webserver domain name. + +If you do not want to upgrade OpenTSDB you need to setup an nginx proxy that will add the necessary CORS +HTTP headers. + +Example nginx config: + +Replace: + + - **OPENTSDB_HOST** (2 instances) - Hostname or IP address of the OpenTSDB server + - **OPENTSDB_PORT** (1 instance) - Port number of the OpenTSDB server + - **GRAFANA_DOMAIN** (1 instance) - Domain/Hostname of the Grafana server + +```nginx +upstream opentsdb { + server OPENTSDB_HOST:OPENTSDB_PORT fail_timeout=0; +} + +server { + listen *:4243; + + location / { + # Regex to whitelist systems + if ($http_origin ~* (https?://([a-z0-9._-]*\.)?GRAFANA_DOMAIN(:[0-9]+)?)) { + set $cors "true"; + } + + # OPTIONS indicates a CORS pre-flight request + if ($request_method = 'OPTIONS') { + set $cors "${cors}-options"; + } + + # If it's OPTIONS, then it's a CORS preflight request so respond immediately with no response body + if ($cors = "true-options") { + add_header 'Access-Control-Allow-Origin' "$http_origin"; + add_header 'Access-Control-Allow-Credentials' 'true'; + add_header 'Access-Control-Max-Age' 1728000; + add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS'; + add_header 'Access-Control-Allow-Headers' 'Authorization,Content-Type,Accept,Origin,User-Agent,DNT,Cache-Control,X-Mx-ReqToken,Keep-Alive,X-Requested-With,If-Modified-Since'; + add_header 'Content-Length' 0; + add_header 'Content-Type' 'text/plain charset=UTF-8'; + return 204; + } + + # Proxy the request + proxy_set_header X-Host OPENTSDB_HOST; + proxy_set_header X-Forwarded-For $Proxy_add_x_forwarded_for; + proxy_set_header Authorization ""; + proxy_pass http://opentsdb; + proxy_redirect default; + proxy_buffer_size 16k; + proxy_buffers 8 32k; + proxy_busy_buffers_size 64k; + proxy_temp_file_write_size 64k; + proxy_read_timeout 120; + # Strip any OpenTSDB-generated CORS headers that overlap with our own + proxy_hide_header 'Access-Control-Allow-Origin'; + proxy_hide_header 'Access-Control-Allow-Credentials'; + proxy_hide_header 'Access-Control-Allow-Headers'; + + # if it's a GET or POST, set the standard CORS responses header + if ($cors = "true") { + # Add our own CORS headers + add_header 'Access-Control-Allow-Origin' "$http_origin"; + add_header 'Access-Control-Allow-Credentials' 'true'; + add_header 'Access-Control-Allow-Headers' '*'; + } + } +} +``` + +## Grafana config +In config.js specify your opentsdb datasource: + +```javascript +datasources: { + 'OpenTSDB-TEST': { + default: true, + type: 'opentsdb', + url: "http://my_opentsdb_server:4242" + } + }, +``` + +## Create a graph +Open a graph in edit mode by click the title. + +![](/img/opentsdb/editor_v1.png) + +For details on opentsdb metric queries +checkout the offical [OpenTSDB documentation](http://opentsdb.net/docs/build/html/index.html) + + + + + diff --git a/docs/sources/features/playlist.md b/docs/sources/features/playlist.md new file mode 100644 index 00000000000..0f81bfe48fc --- /dev/null +++ b/docs/sources/features/playlist.md @@ -0,0 +1,33 @@ +--- +page_title: Playlist Guide +page_description: Playlist guide for Grafana +page_keywords: grafana, playlist, documentation +--- + +# Playlist Guide + +In Grafana v1.5 a playlist feature was added. You can use this feature by first marking a couple + of dashboards as favorites. This is accomplished in the Save menu. Click on the save icon and then _Mark As Favorite_. + + +## Step 1 - Mark as favorire +![](/img/v1/mark_as_favorite.png) + +Then open the playlist modal. You will find this button in the open dashboard / search popup (CTRL+F). + +## Step 2 - Open playlist view +![](/img/v1/playlist_button.png) + +This opens the playlist view. + +## Step 3 - Select dashbords and interval + +![](/img/v1/playlist_modal.png) + +In this view you can select the dashboards you want to include in the playlist, and even remove dashboards from you favorites list. Set the time span between dashboard change, for example 1m, 10m, 1h for 1 minute, 10 minute or 1 hour interval. + +To start the dashboard click the Start button. + +When a dashboard playlist is running, most menu buttons and dashboard controls are hidden. This is in order to present as clear a view of the dashboard as possible for big tv displays. Click the stop playlist link in the top menu to the right to stop the playlist. + +![](playlist_playing_hiden_menu.png) diff --git a/docs/sources/features/scripted_dashboards.md b/docs/sources/features/scripted_dashboards.md new file mode 100644 index 00000000000..6e8c25c0196 --- /dev/null +++ b/docs/sources/features/scripted_dashboards.md @@ -0,0 +1,61 @@ +---- +page_title: Scripted dashboards +page_description: Scripted dashboards +page_keywords: grafana, scripted, guide, documentation +--- + +# Scripted Dashboards + +If you have lots of metric names that change (new servers etc) in a defined pattern it is irritating to constantly have to create new dashboards. + +With scripted dashboards you can dynamically create your dashboards using javascript. In the folder grafana install folder _app/dashboards/_ there is a file named _scripted.js_. This file contains an example of a scripted dashboard. You can access it by using the url: +> http://grafana_url/#/dashboard/script/scripted.js?rows=3&name=myName + +If you open scripted.js you can see how it reads url paramters from ARGS variable and then adds rows and panels. + +## Example + +```javascript +var rows = 1; +var seriesName = 'argName'; + +if(!_.isUndefined(ARGS.rows)) { + rows = parseInt(ARGS.rows, 10); +} + +if(!_.isUndefined(ARGS.name)) { + seriesName = ARGS.name; +} + +for (var i = 0; i < rows; i++) { + + dashboard.rows.push({ + title: 'Scripted Graph ' + i, + height: '300px', + panels: [ + { + title: 'Events', + type: 'graph', + span: 12, + fill: 1, + linewidth: 2, + targets: [ + { + 'target': "randomWalk('" + seriesName + "')" + }, + { + 'target': "randomWalk('random walk2')" + } + ], + } + ] + }); + +} + +return dashboard; +``` + +## More examples + +You can find more examples in `app/dashboards/` directory of your grafana installation. diff --git a/docs/sources/features/search.md b/docs/sources/features/search.md new file mode 100644 index 00000000000..159fe4056e8 --- /dev/null +++ b/docs/sources/features/search.md @@ -0,0 +1,34 @@ +---- +page_title: Search guide +page_description: Search guide +page_keywords: grafana, time range, guide, documentation +--- + +# Search Guide + +To search and load dashboards click the open folder icon in the header or use the shortcut CTRL+F. + +## Tags +![](/img/v1/dashboards_tags2_search.png) + +Click on any dashboard or use the down arrow key to navigate the search result and hit enter to open the selected dashboard. + +If you have a lot of dashboards use tags to organize them. You can add tags in the dashboards settings modal. + +![](/img/v1/dashboards_tags1.png) + +After you have added tags you can now view all available tags in the search popup. Click the tags link to the right in the search box, or just hit tab and then enter. You should now see a list of all tags. You can filter the tag list by continue writing in the search box, for example: "tags!:mongodb". + +![](/img/v1/dashboards_tags3_search.png) + +Click on any tag in the tag list to show dashboards with that tag (or just down arrow key to select a tag then enter key). + +## Keyboard navigation + +While the search input has focus you can use your keyboard arrow keys to navigate the results, hit enter to open the selected dashboard. + + + + + + diff --git a/docs/sources/features/templated_dashboards.md b/docs/sources/features/templated_dashboards.md new file mode 100644 index 00000000000..f66a8838441 --- /dev/null +++ b/docs/sources/features/templated_dashboards.md @@ -0,0 +1,18 @@ +---- +page_title: Templated dashboards +page_description: Templated dashboards +page_keywords: grafana, templating, variables, guide, documentation +--- + +# Templated Dashboards + +Templating feature can be enabled under dashboard settings, in the Features tab. The templating feature allows +you to create variables that can be used in your metric queries, series names and panel titles. Use this feature to +create generic dashboards that can quickly be changed to show graphs for different servers or metrics. + +## Screencast - Templated Graphite Queries + + +
+## Screencast - Templated InfluxDB Queries +Coming soon diff --git a/docs/sources/features/time_range.md b/docs/sources/features/time_range.md new file mode 100644 index 00000000000..9c2fa634fae --- /dev/null +++ b/docs/sources/features/time_range.md @@ -0,0 +1,26 @@ +---- +page_title: Time Range options +page_description: Time range user guide +page_keywords: grafana, time range, guide, documentation +--- + +# Time range controls + +![](/img/v1/time_range_controls.png) + +In the menu you have the time range dropdown (between to Zoom out and refresh links). +In this dropdown you have relative time options, auto refresh options and custom time options. + + +## Custom time + +To customize the relative and auto refresh options open the dashboard settings and click the Timepicker tab. +In this tab you can specify the relative and auto refresh intervals. The Timepicker tab settings are saved +on per dashboard basis. + +![](/img/v1/timepicker_editor.png) + +## Time picker options + +In dashboard settings, `Time Picker` tab you can add or remove the relative time intervals and refresh intervals +that should be available in the time picker dropdown. diff --git a/docs/sources/index.md b/docs/sources/index.md new file mode 100644 index 00000000000..e0411164e3e --- /dev/null +++ b/docs/sources/index.md @@ -0,0 +1,17 @@ +page_title: About Grafana +page_description: Introduction to Grafana. +page_keywords: grafana, introduction, documentation, about + +# About + +Grafana is a general purpose dashboard and graph composer. Its focused on providing +rich ways to visualize time series metrics, mainly though graphs. It currently +has rich support for for [Graphite](http://graphite.readthedocs.org/en/latest/), [InfluxDB](http://influxdb.org) +and [OpenTSDB](http://opentsdb.net). But supports other data sources via plugins. + +## License + +Grafana is licensed under Apache 2.0. See [LICENSE](https://github.com/grafana/grafana/blob/master/LICENSE.mdhttps://github.com/grafana/grafana/blob/master/LICENSE.md) +for full license text. + + diff --git a/docs/sources/installation/installation.md b/docs/sources/installation/installation.md new file mode 100644 index 00000000000..8d2448665a3 --- /dev/null +++ b/docs/sources/installation/installation.md @@ -0,0 +1,194 @@ +--- +page_title: Grafana Installation +page_description: Install guide for Grafana. +page_keywords: grafana, installation, documentation +--- + +# Installation + +Grafana is a frontend for [Graphite](http://graphite.readthedocs.org/en/latest/), [InfluxDB](http://influxdb.org) +and [OpenTSDB](http://opentsdb.net) with powerfull visualization features for time series data. +You will need either a Graphite, InfluxDB or OpenTSDB server for Grafana to be of any use. + +## Download + +[Download](/download) the latest release. The release package contain a subfolder, for example **grafana-1.7.0**. The +contents of this folder should be hosted by a web server, for example nginx, apache, IIS. The standard release +packages does not contain a web server to host Grafana. + +### Dependencies +There are no dependencies, Grafana is a client side application that runs in your browser. It only needs a time series store +where it can fetch metrics. If you use InfluxDB Grafana can use it to store dashboards. +If you use Graphite or OpenTSDB you can use Elasticsearch to store dashboards or just use json files stored on disk. + +### Provisioning +If you prefer to install grafana via Puppet, Ansible, Docker or Chef. [This page](/docs/provisioning) has compiled a +list of repositories for different provisioning systems + +## Configuration +In your chosen Grafana install location, locate the file **config.sample.js** and copy or rename it to **config.js**. +This files contains global settings for your Grafana installation. + + +### Datasources +The datasources property defines your metric, annotation and dashboard storage backends. + +- You can specify multiple datasources. +- default: true marks it as the default metric source (if you have multiple) +- grafanaDB: true marks it for use as dashboard storage (applicable for InfluxDB & Elasticsearch) + +### InfluxDB example setup +```javascript +datasources: { + 'eu-metrics': { + type: 'influxdb', + url: 'http://my_influxdb_server:8086/db/', + username: 'test', + password: 'test', + }, + 'grafana': { + type: 'influxdb', + url: 'http://my_influxdb_server:8086/db/grafana', + username: 'test', + password: 'test', + grafanaDB: true + }, +}, +``` +In the above example you see two InfluxDB datasources, one for metrics and a seperate used for dashboard storage. You can use the same InfluxDB +database for both. But it is probably a good idea to keep them seperate. The InfluxDB databases need to exist, grafana does not create +them. + +### Graphite & Elasticsearch setup example + +```javascript +datasources: { + graphite: { + type: 'graphite', + url: "http://my.graphite.server.com:8080", + }, + elasticsearch: { + type: 'elasticsearch', + url: "http://my.elastic.server.com:9200", + index: 'grafana-dash', + grafanaDB: true, + } +}, +``` +If you use Graphite you need Elasticsearch if you want to store & search dashboards. You can also use json and scripted dashboards if +you really do not want to setup Elasticsearch. + +### OpenTSDB & Elasticsearch setup example + +```javascript +datasources: { + opentsdb: { + type: 'opentsdb', + url: "http://my.opentsdb.server.com:4242", + }, + elasticsearch: { + type: 'elasticsearch', + url: "http://my.elastic.server.com:9200", + index: 'grafana-dash', + grafanaDB: true, + } +}, +``` +Please view [this page](/docs/features/opentsdb) for details on how to configure OpenTSDB to work with Grafana. + +### Elasticsearch & CORS +As of Elasticsearch v1.4 CORS is disabled by default. This needs to be enabled in the Elasticsearch config file, otherwise grafana will not be able to access Elasticsearch. + +``` +http.cors.enabled: true +http.cors.allow-origin: * +``` + +Instead of the wildcard you can put your full grafana webserver address (including http:// and port) + +### Basic authentication +If your Graphite or Elasticsearch server require basic authentication you can specify the username and password in the url. +For example `"http://admin:secret@my.graphite.com"` + +## Global configuration options + +```javascript +// specify the limit for dashboard search results +search: { + max_results: 20 +}, + +// default start dashboard +default_route: '/dashboard/file/default.json', + +// set to false to disable unsaved changes warning +unsaved_changes_warning: true, + +// set the default timespan for the playlist feature +// Example: "1m", "1h" +playlist_timespan: "1m", + +// If you want to specify password before saving, please specify it bellow +// The purpose of this password is not security, but to stop some users from accidentally changing dashboards +admin: { + password: '' +}, + +// Add your own custom pannels +plugins: { + panels: [] +} +``` + +## Graphite server config +If you haven't used an alternative dashboard for graphite before you need to enable CORS (Cross Origin Resource Sharing). +This is only required if Grafana is hosted on a different web domain from your graphite-web. + +For Apache 2.x: + +```javascript +Header set Access-Control-Allow-Origin "*" +Header set Access-Control-Allow-Methods "GET, OPTIONS" +Header set Access-Control-Allow-Headers "origin, authorization, accept" +``` + +Note that using `"*"` leaves your graphite instance quite open so you might want to consider +using `"http://my.grafana.com"` in place of `"*"` + +If your Graphite web is proteced by basic authentication, you have to enable the HTTP verb OPTIONS. Take note that +when using basic auth **Access-Control-Allow-Origin** must not be set to a wildcard, also the header +**Access-Control-Allow-Credentials** must be specified. This looks like the following for Apache: + +```html +Header set Access-Control-Allow-Origin "http://mygrafana.com:5656" +Header set Access-Control-Allow-Methods "GET, OPTIONS" +Header set Access-Control-Allow-Headers "origin, authorization, accept" +Header set Access-Control-Allow-Credentials true + + + AuthName "graphs restricted" + AuthType Basic + AuthUserFile /etc/apache2/htpasswd + + require valid-user + + +``` + +For nginx: + +```javascript +auth_basic "Restricted"; +auth_basic_user_file /path/to/my/htpasswd/file; + +if ($http_origin ~* (https?://[^/]*\.somedomain\.com(:[0-9]+)?)) { #Test if request is from allowed domain, you can use multiple if + set $cors "true"; #statements to allow multiple domains, simply setting $cors to true in each one. +} + +if ($cors = 'true') { + add_header Access-Control-Allow-Origin $http_origin; #this mirrors back whatever domain the request came from as authorized, as + add_header "Access-Control-Allow-Credentials" "true"; #as long as it matches one of your if statements + add_header "Access-Control-Allow-Methods" "GET, OPTIONS"; + add_header "Access-Control-Allow-Headers" "Authorization, origin, accept"; +} +``` diff --git a/docs/sources/installation/performance.md b/docs/sources/installation/performance.md new file mode 100644 index 00000000000..535cf72a228 --- /dev/null +++ b/docs/sources/installation/performance.md @@ -0,0 +1,16 @@ +--- +page_title: Performance Tips +page_description: Grafana performance tips +page_keywords: grafana, performance, documentation +--- + +# Performance tips + +## Graphite + +Graphite 0.9.13 adds a much needed feature to the json rendering API that is very important for Grafana. If you are experiance slow +load & rendering times for large time ranges then it is most likely caused by running Graphite 0.9.12 or lower. The latest version +of Graphite adds a maxDataPoints parameter to the json render API, without this feature Graphite can return hundreds of thousands of data points per graph, which +can hang your browser. Be sue to upgrade to [0.9.13](http://graphite.readthedocs.org/en/latest/releases/0_9_13.html). + + diff --git a/docs/sources/installation/provisioning.md b/docs/sources/installation/provisioning.md new file mode 100644 index 00000000000..b7324721e58 --- /dev/null +++ b/docs/sources/installation/provisioning.md @@ -0,0 +1,32 @@ +--- +page_title: Provisioning +page_description: Grafana provisioning +page_keywords: grafana, provisioning, documentation +--- + +# Provisioning + +Here are links for how to install Grafana (and some include graphite or influxdb as well) via a provisioning +system. These are not maintained by any core Grafana team member and might be out of date. + +## Puppet + +* [forge.puppetlabs.com/bfraser/grafana](https://forge.puppetlabs.com/bfraser/grafana) + +## Ansible + +* [github.com/bobrik/ansible-grafana](https://github.com/bobrik/ansible-grafana) +* [github.com/bitmazk/ansible-digitalocean-influxdb-grafana](https://github.com/bitmazk/ansible-digitalocean-influxdb-grafana) + +## Docker + +* [github.com/kamon-io/docker-grafana-graphite](https://github.com/kamon-io/docker-grafana-graphite) +* [github.com/kamon-io/docker-grafana-influxdb](https://github.com/kamon-io/docker-grafana-influxdb) +* [github.com/tutumcloud/tutum-docker-grafana](https://github.com/tutumcloud/tutum-docker-grafana) +* [github.com/mingfang/docker-grafana](https://github.com/mingfang/docker-grafana) + +## Chef + +* [github.com/JonathanTron/chef-grafana](https://github.com/JonathanTron/chef-grafana) +* [github.com/dzautner/grafana-cookbook](https://github.com/dzautner/grafana-cookbook) + diff --git a/docs/sources/installation/troubleshooting.md b/docs/sources/installation/troubleshooting.md new file mode 100644 index 00000000000..9d0605f5eee --- /dev/null +++ b/docs/sources/installation/troubleshooting.md @@ -0,0 +1,48 @@ +page_title: Troubleshooting +page_description: Troubleshooting +page_keywords: grafana, support, documentation + +# Troubleshooting + +This page is dedicated to helping you solve any problem you have getting Grafana to work. Please review it before +opening a new github issue or asking a question in #grafana on freenode. + +## General connection issues +When setting up Grafana for the first time you might experiance issues with Grafana being unable to query Graphite, OpenTSDB or InfluxDB. +You might not be able to get metric name completion or the graph might show an error like this: + +![](/img/v1/graph_timestore_error.png) + +For some type of errors the ``View details`` link will show you error details. But for many types of HTTP connection errors there is +very little information. The best way to troubleshoot these issues is use +[Chrome developer tools](https://developer.chrome.com/devtools/index). By pressing F12 you can bring up the chrome dev tools. + +![](/img/v1/toubleshooting_chrome_dev_tools.png) + +There are two important tabs in the chrome dev tools, ``Network`` and ``Console``. Console will show you javascript errors and HTTP +request errors. In the Network tab you will be able to identifiy the request that failed and review request and response parameters. +This information will be of great help in finding the cause of the error. If you are unable to solve the issue, even after reading +the remainder of this troubleshooting guide, you may open a [github support issue](https://github.com/grafana/grafana/issues). +Before you do that please search the existing closed or open issues. Also if you need to create a support issue, +screenshots and or text information about the chrome console error, request and response information from the network tab in chrome +developer tools are of great help. + +### Inspecting Grafana metric requests +![](/img/v1/toubleshooting_chrome_dev_tools_network.png) + +After open chrome developer tools for the first time the Network tab is empty you need to refresh the page to get requests to show. +For some type of errors (CORS related) there might not be a response at all. + +## Graphite connection issues +If your Graphite web server is on another domain or IP than your Grafana web server you will need to [setup +CORS](../install/#graphite-server-config) (Cross Origin Resource Sharing). + +You know if you are having CORS related issues if you get an error like this in chrome developer tools: + +![](/img/v1/toubleshooting_graphite_cors_error.png) + +If the request failed on method ``OPTIONS`` then you need to review your graphite web server configuration. + +## Only blank white page +When you load Grafana and all you get is a blank white page then you probably have a javascript syntax error in ``config.js``. +In chrome developer tools console you will quickly identify the line of the syntax error. diff --git a/docs/sources/jsearch.md b/docs/sources/jsearch.md new file mode 100644 index 00000000000..56e9b7c48f5 --- /dev/null +++ b/docs/sources/jsearch.md @@ -0,0 +1,15 @@ +page_title: Search the Grafana documentation +page_keywords: Grafana, search documentation +no_toc: true +no_version_dropdown: true + +# Search + +
+ + +
+ +
+Sorry, page not found. +
diff --git a/docs/sources/screencasts/feature_tour/index.html.slim b/docs/sources/screencasts/feature_tour/index.html.slim new file mode 100644 index 00000000000..777c49c729f --- /dev/null +++ b/docs/sources/screencasts/feature_tour/index.html.slim @@ -0,0 +1,12 @@ + + +h1 Grafana video tour + +.row + .panel.callout + | This video will show you some of the basic features like building graphs and dashboards. It is a little outdated, the function + | editor has been much improved since this video was made. + +.row + iframe width="513" height="317" src="//www.youtube.com/embed/OUvJamHeMpw?vq=hd1080" frameborder="0" allowfullscreen="1" + diff --git a/docs/sources/screencasts/function_editor/index.html.slim b/docs/sources/screencasts/function_editor/index.html.slim new file mode 100644 index 00000000000..e51878e53ff --- /dev/null +++ b/docs/sources/screencasts/function_editor/index.html.slim @@ -0,0 +1,11 @@ + + +h1 Grafana 1.5 Function editor + +.row + .panel.callout + | This video demos the new Graphite function editor that was introduced in Grafana v1.5 + +.row + iframe width="513" height="317" src="//www.youtube.com/embed/I90WHRwE1ZM?vq=hd1080" frameborder="0" allowfullscreen="1" + diff --git a/docs/sources/screencasts/index.md b/docs/sources/screencasts/index.md new file mode 100644 index 00000000000..07f9801e9f8 --- /dev/null +++ b/docs/sources/screencasts/index.md @@ -0,0 +1,16 @@ +page_title: Screencasts +page_description: Grafana screencasts +page_keywords: grafana, screencasts, documentation, guides + +# Screencasts + +## Grafana Screencasts - Episode 2 - Templated Graphite Queries + + +
+## Grafana Screencasts - Episode 1 - Building Graphite Queries + + +
+ + diff --git a/docs/sources/search.md b/docs/sources/search.md new file mode 100644 index 00000000000..0e2e13fb08c --- /dev/null +++ b/docs/sources/search.md @@ -0,0 +1,10 @@ +# Search + +*Please activate JavaScript to enable the search functionality.* + +## How To Search + +From here you can search these documents. Enter your search words into +the box below and click "search". Note that the search function will +automatically search for all of the words. Pages containing fewer words +won't appear in the result list. diff --git a/docs/sources/support/index.md b/docs/sources/support/index.md new file mode 100644 index 00000000000..cf68fb5f19a --- /dev/null +++ b/docs/sources/support/index.md @@ -0,0 +1,20 @@ +page_title: Support +page_description: Support options for Grafana. +page_keywords: grafana, support, documentation + +# Support + +If you have any trouble with Grafana, either the install or some feature you do not understand or you suspect isn't working +correctly there are a number of sources where you can get help. + +- [Troubleshooting guide](../troubleshooting) +- \#grafana IRC channel on freenode +- Search closed and open [issues on github](https://github.com/grafana/grafana/issues). +- [Mailing list](https://groups.io/org/groupsio/grafana) + +Do not hesitate to open a new issue with a question, bug report or an idea for improvement. + +User feedback and involvement is paramount to making a product better so please take the time and create an issue. + +## Paid support +If you wish to get paid support please [contact us](mailto:contact@grafana.org). diff --git a/docs/sources/test.md b/docs/sources/test.md new file mode 100644 index 00000000000..8202105a8eb --- /dev/null +++ b/docs/sources/test.md @@ -0,0 +1,4 @@ + +# Test + +## Google diff --git a/docs/sources/versions.html_fragment b/docs/sources/versions.html_fragment new file mode 100644 index 00000000000..00ee000a0f0 --- /dev/null +++ b/docs/sources/versions.html_fragment @@ -0,0 +1,2 @@ +
  • Version v2.0
    • +
  • Version v1.9