diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 973f42d7ab4..52d8590a641 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -52,7 +52,7 @@ Unsure where to begin contributing to Grafana? Start by browsing issues labeled - [Beginner-friendly](https://github.com/grafana/grafana/issues?q=is%3Aopen+is%3Aissue+label%3A%22beginner+friendly%22) issues are generally straightforward to complete. - [Help wanted](https://github.com/grafana/grafana/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22) issues are problems we would like the community to help us with regardless of complexity. -If you're looking to make a code change, see how to set up your environment for [local development](contribute/development.md). +If you're looking to make a code change, see how to set up your environment for [local development](contribute/developer-guide.md). When you're ready to contribute, it's time to [Create a pull request](/contribute/pull-request.md). @@ -69,6 +69,6 @@ Before we can accept your pull request, you need to [sign our CLA](https://grafa ## Where do I go from here? -- Set up your [development environment](contribute/development.md). +- Set up your [development environment](contribute/developer-guide.md). - Learn how to [contribute documentation](contribute/documentation.md). - Get started [developing plugins](https://grafana.com/docs/plugins/developing/development/) for Grafana. diff --git a/README.md b/README.md index cd188d70f81..6f94735e0ff 100644 --- a/README.md +++ b/README.md @@ -1,222 +1,45 @@ -# [Grafana](https://grafana.com) [![Circle CI](https://circleci.com/gh/grafana/grafana.svg?style=svg)](https://circleci.com/gh/grafana/grafana) [![Go Report Card](https://goreportcard.com/badge/github.com/grafana/grafana)](https://goreportcard.com/report/github.com/grafana/grafana) +![Grafana](docs/logo-horizontal.png) -[Website](https://grafana.com) | -[Twitter](https://twitter.com/grafana) | -[Community & Forum](https://community.grafana.com) +The open-source platform for monitoring and observability. -Grafana is an open source, feature rich metrics dashboard and graph editor for -Graphite, Elasticsearch, OpenTSDB, Prometheus and InfluxDB. +[![License](https://img.shields.io/github/license/grafana/grafana)](LICENSE) +[![Circle CI](https://img.shields.io/circleci/build/gh/grafana/grafana)](https://circleci.com/gh/grafana/grafana) +[![Go Report Card](https://goreportcard.com/badge/github.com/grafana/grafana)](https://goreportcard.com/report/github.com/grafana/grafana) - +Grafana allows you to query, visualize, alert on and understand your metrics no matter where they are stored. Create, explore, and share dashboards with your team and foster a data driven culture: -## Installation +- **Visualize:** Fast and flexible client side graphs with a multitude of options. Panel plugins for many different way to visualize metrics and logs. +- **Dynamic Dashboards:** Create dynamic & reusable dashboards with template variables that appear as dropdowns at the top of the dashboard. +- **Explore Metrics:** Explore your data through ad-hoc queries and dynamic drilldown. Split view and compare different time ranges, queries and data sources side by side. +- **Explore Logs:** Experience the magic of switching from metrics to logs with preserved label filters. Quickly search through all your logs or streaming them live. +- **Alerting:** Visually define alert rules for your most important metrics. Grafana will continuously evaluate and send notifications to systems like Slack, PagerDuty, VictorOps, OpsGenie. +- **Mixed Data Sources:** Mix different data sources in the same graph! You can specify a data source on a per-query basis. This works for even custom datasources. -Head to [docs.grafana.org](http://docs.grafana.org/installation/) for documentation or [grafana.com/get](https://grafana.com/get) to download the latest release. +## Get started -## Documentation & Support +- [Get Grafana](https://grafana.com/get) +- [Installation guides](http://docs.grafana.org/installation/) -Be sure to read the [Getting Started](http://docs.grafana.org/guides/gettingstarted/) guide and the other feature guides. +Unsure if Grafana is for you? Watch Grafana in action on [play.grafana.org](https://play.grafana.org/)! -## Run from master +## Documentation -If you want to build a package yourself, or contribute - here is a guide for how to do that. You can always find -the latest master builds [here](https://grafana.com/grafana/download). +The Grafana documentation is available at [grafana.com/docs](https://grafana.com/docs/). -### Dependencies +## Contributing -- Go (Latest Stable) -- Node.js LTS - - yarn [`npm install -g yarn`] +If you're interested in contributing to the Grafana project: -### Get the project +- Start by reading the [Contributing guide](/CONTRIBUTING.md). +- Learn how to set up your local environment, in our [Developer guide](/contribute/developer-guide.md). +- Explore our [beginner-friendly issues](https://github.com/grafana/grafana/issues?q=is%3Aopen+is%3Aissue+label%3A%22beginner+friendly%22). -**The project located in the go-path will be your working directory.** +## Get involved -```bash -go get github.com/grafana/grafana -cd $GOPATH/src/github.com/grafana/grafana -``` - -### Run and rebuild on source change - -#### Backend - -To run the backend and rebuild on source change: - -```bash -make run -``` - -#### Frontend -Install front-end dependencies first: - -```bash -yarn install --pure-lockfile -``` - -Rebuild on file change, and serve them by Grafana's webserver (http://localhost:3000): - -```bash -yarn start -``` - -Build the assets, rebuild on file change with Hot Module Replacement (HMR), and serve them by webpack-dev-server (http://localhost:3333): - -```bash -yarn start:hot -# OR set a theme -env GRAFANA_THEME=light yarn start:hot -``` - -_Note: HMR for Angular is not supported. If you edit files in the Angular part of the app, the whole page will reload._ - -Run tests and rebuild on source change: - -```bash -yarn jest -``` - -**Open grafana in your browser (default: e.g. `http://localhost:3000`) and login with admin user (default: `user/pass = admin/admin`).** - -### Building - -#### The backend - -```bash -go run build.go setup -go run build.go build -``` - -#### Frontend assets - -_For this you need Node.js (LTS version)._ - -```bash -yarn install --pure-lockfile -``` - -### Building a Docker image - -There are two different ways to build a Grafana docker image. If your machine is setup for Grafana development and you run linux/amd64 you can build just the image. Otherwise, there is the option to build Grafana completely within Docker. - -Run the image you have built using: `docker run --rm -p 3000:3000 grafana/grafana:dev` - -#### Building on linux/amd64 (fast) - -1. Build the frontend `go run build.go build-frontend`. -2. Build the docker image `make build-docker-dev`. - -The resulting image will be tagged as `grafana/grafana:dev`. - -#### Building anywhere (slower) - -Choose this option to build on platforms other than linux/amd64 and/or not have to setup the Grafana development environment. - -1. `make build-docker-full` or `docker build -t grafana/grafana:dev`. - -The resulting image will be tagged as `grafana/grafana:dev`. - -Notice: If you are using Docker for MacOS, be sure to set the memory limit to be larger than 2 GiB (at docker -> Preferences -> Advanced), otherwise `grunt build` may fail. - -## Development - -### Dev config - -Create a custom.ini in the conf directory to override default configuration options. -You only need to add the options you want to override. Config files are applied in the order of: - -1. grafana.ini -1. custom.ini - -In your custom.ini uncomment (remove the leading `;`) sign. And set `app_mode = development`. - -### Running tests - -#### Frontend - -Execute all frontend tests: - -```bash -yarn test -``` - -Write and watch frontend tests: - -- Start watcher: `yarn jest`. -- Jest runs all test files that end with the name ".test.ts". - -#### Backend - -```bash -# Run Golang tests using sqlite3 as database (default) -go test ./pkg/... -``` - -##### Running the MySQL or Postgres backend tests: - -Run these by setting `GRAFANA_TEST_DB` in your environment. - -- `GRAFANA_TEST_DB=mysql` to test MySQL -- `GRAFANA_TEST_DB=postgres` to test Postgres - -Follow the instructions in `./devenv` to spin up test containers running the appropriate databases with `docker-compose` -- Use `docker/blocks/mysql_tests` or `docker/blocks/postgres_tests` as appropriate. - -```bash -# MySQL -# Tests can only be ran in one Go package at a time due to clashing db queries. To run MySQL tests for the "pkg/services/sqlstore" package, run: -GRAFANA_TEST_DB=mysql go test ./pkg/services/sqlstore/... - -# Or run all the packages using the circle CI scripts. This method will be slower as the scripts will run all the tests, including the integration tests. -./scripts/circle-test-mysql.sh -``` - -```bash -# Postgres -# Tests can only be ran in one Go package at a time due to clashing db queries. To run Postgres tests for the "pkg/services/sqlstore" package, run: -GRAFANA_TEST_DB=postgres go test ./pkg/services/sqlstore/... - -# Or run all the packages using the circle CI scripts. This method will be slower as the scripts will run all the tests, including the integration tests. -./scripts/circle-test-postgres.sh -``` - -#### End-to-end - -Execute all end-to-end tests: - -```bash -yarn e2e-tests -``` - -Execute all end-to-end tests using using a specific url: - -```bash -ENV BASE_URL=http://localhost:3333 yarn e2e-tests -``` - -Debugging all end-to-end tests (BROWSER=1 starts the browser and SLOWMO=1 delays each puppeteer operation by 100ms): - -```bash -ENV BROWSER=1 SLOWMO=1 yarn e2e-tests -``` - -### Data source and dashboard provisioning - -[Here](https://github.com/grafana/grafana/tree/master/devenv) you can find helpful scripts and docker-compose setup -that will populate your dev environment for quicker testing and experimenting. - -## Contribute - -If you have any ideas for improvement or have found a bug, do not hesitate to open an issue. -And if you have time, clone this repo and submit a pull request to help me make Grafana the kickass metrics and devops dashboard we all dream about! - -Read the [contributing](https://github.com/grafana/grafana/blob/master/CONTRIBUTING.md) guide then check the [`beginner friendly`](https://github.com/grafana/grafana/issues?q=is%3Aopen+is%3Aissue+label%3A%22beginner+friendly%22) label to find issues that are easy and that we would like help with. - -## Plugin development - -Checkout the [Plugin Development Guide](http://docs.grafana.org/plugins/developing/development/) and checkout the [PLUGIN_DEV.md](https://github.com/grafana/grafana/blob/master/PLUGIN_DEV.md) file for changes in Grafana that relate to plugin development. +- Follow [@grafana on Twitter](https://twitter.com/grafana/) +- Read and subscribe to the [Grafana blog](https://grafana.com/blog/) +- If you have a specific question, check out our [discussion forums](https://community.grafana.com/). +- For general discussions, join us on the [official Slack](http://slack.raintank.io/) team. ## License diff --git a/contribute/development.md b/contribute/developer-guide.md similarity index 100% rename from contribute/development.md rename to contribute/developer-guide.md diff --git a/docs/logo-horizontal.png b/docs/logo-horizontal.png new file mode 100644 index 00000000000..b8a9e51ff36 Binary files /dev/null and b/docs/logo-horizontal.png differ diff --git a/docs/logo-swirl.svg b/docs/logo-swirl.svg new file mode 100644 index 00000000000..95ff28c6807 --- /dev/null +++ b/docs/logo-swirl.svg @@ -0,0 +1,64 @@ + + + + + + + + + +