{"id":13583820,"url":"https://github.com/grofers/legend","last_synced_at":"2025-09-03T23:31:57.955Z","repository":{"id":38824885,"uuid":"299820726","full_name":"grofers/legend","owner":"grofers","description":"Legend builds and publishes Grafana dashboards for your services with prefilled metrics and alerts for your services.","archived":false,"fork":false,"pushed_at":"2022-12-29T05:49:44.000Z","size":497,"stargazers_count":184,"open_issues_count":14,"forks_count":17,"subscribers_count":11,"default_branch":"master","last_synced_at":"2024-12-22T10:34:53.289Z","etag":null,"topics":["grafana","grafana-dashboard","monitoring","monitoring-tool","observability"],"latest_commit_sha":null,"homepage":"","language":"Jinja","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/grofers.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"docs/contributing-to-kubernetes-library.md","funding":null,"license":"COPYING","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-09-30T05:47:48.000Z","updated_at":"2024-09-27T09:23:37.000Z","dependencies_parsed_at":"2022-08-26T20:02:40.655Z","dependency_job_id":null,"html_url":"https://github.com/grofers/legend","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grofers%2Flegend","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grofers%2Flegend/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grofers%2Flegend/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grofers%2Flegend/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/grofers","download_url":"https://codeload.github.com/grofers/legend/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":231926367,"owners_count":18447052,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["grafana","grafana-dashboard","monitoring","monitoring-tool","observability"],"created_at":"2024-08-01T15:03:49.857Z","updated_at":"2024-12-30T23:56:03.389Z","avatar_url":"https://github.com/grofers.png","language":"Jinja","funding_links":[],"categories":["Jinja"],"sub_categories":[],"readme":"# Legend\n\n\u003e The legendary tool which builds and manages grafana dashboards for your applications\n\n[![License](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0) [![Release](https://img.shields.io/github/v/tag/grofers/legend)](https://github.com/grofers/legend/releases/tag/v0.1) [![Artifact HUB](https://img.shields.io/endpoint?url=https://artifacthub.io/badge/repository/legend)](https://artifacthub.io/packages/search?repo=legend)\n\n[![Grofers Engineering](https://img.shields.io/badge/Grofers-Engineering-orange)](https://lambda.grofers.com/)\n\n## What is Legend\n\nLegend builds and publishes Grafana dashboards for your services with prefilled metrics and alerts for your services.\n\nSay you got an EC2 to monitor, an S3 to monitor, a Kubernetes cronjob to monitor (or one of many other things); legend has got your back. It will do all the menial work of setting up grafana dashboards for you without you needing to setup grafana dashboards manually or write cloudwatch/prometheus/influxdb queries by hand.\n\n### Methodology\n\nLegend uses the [USE](http://www.brendangregg.com/usemethod.html) and [RED](https://thenewstack.io/monitoring-microservices-red-method/) methodology of monitoring service and infrastructure level metrics.\n\n## Table of contents\n\n* [Features](#features)\n* [Getting started](#getting-started)\n  * [Pre-requisites](#pre-requisites)\n  * [Using Legend](#using-legend)\n* [Contribution](#contribution)\n* [Legend internals](#legend-internals)\n\n## Features\n\n* Build dashboards for your services with prefilled metrics\n* Customizable alerts and panels\n* Automatic setup of basic alerts with priority and service mapping\n* Beautiful outlay of the dashboard to enable uniformity.\n* Currently, here are the following types of components which legend can plot for you:\n  * Airflow\n  * Amazon ALB\n  * Celery\n  * Consul\n  * CouchDB\n  * Django\n  * Flask\n  * Amazon ELB\n  * Go\n  * HAProxy\n  * JMX\n  * Loki\n  * MySQL - RDS\n  * MySQL - EC2\n  * NGINX (Log-based metrics)\n  * NodeJS\n  * PostgreSQL - RDS\n  * PgBouncer\n  * Phoenix\n  * EC2 Platform level metrics\n  * [Kubernetes CronJob](docs/cronjob-prometheus-rule.md)\n  * Kubernetes Deployment\n  * Kubernetes Horizontal Pod Autoscaler\n  * Kubernetes Ingress\n  * Playframework\n  * Promtail\n  * RabbitMQ\n  * Redis\n  * Redis - Elasticache\n  * S3\n  * Sprintboot\n  * SQS\n  * Starlette\n  * Hashicorp Vault\n* Legend currently has the capability to further have support for any other component, provided that component's log generation is backed by one of the following metric/log stores:\n  * Cloudwatch\n  * InfluxDB\n  * Loki\n  * Prometheus\n\n## Getting started\n\nThis section describes on how to get started with using Legend.\n\n### Pre-requisites\n\n* For each component of your service, there has to be a respective metric files in\n`legend/metrics_library/metrics/` which containes the metrics to be plotted for that component. If you are adding a new component(and a new metric library file) please refer to [contributing-to-metric-library](docs/contributing-to-metric-library.md)\n\n* Based on the component an additional step of enabling metrics for the component has to happen. The monitoring queries written are based on specific exporters userd to expose the metrics, mentioned in [enabling metrics](docs/contributing-to-metric-library.md). If other exporters are used, the queries might have to be changed.\n\n* For cronjobs an additional custom prometheus rule is required. You can find more details [here](docs/cronjob-prometheus-rule.md)\n### Using Legend\n\nYou can use `legend` in one of the two ways:\n\n* [Use legend in kubernetes](#use-legend-in-kubernetes)\n* [Legend CLI](#legend-cli)\n\n**The recommended way to use Legend is to deploy it in Kubernetes**\n\nYou need to create an input file describing the components of your service [writing-input-file](docs/writing-input-file.md)\n\n#### Use legend in kubernetes\n\nLegend installs as a CRD in Kubernetes\n\n**Required kubernetes \u003e= 1.16**\n\n*Installation*\nQuick instructions\nLegend is installed via [helm](https://helm.sh/):\n\n* Add the helm repo: `helm repo add legend https://grofers.github.io/legend`\n* Configure Legend, make a local copy of [values.yaml](charts/legend/values.yaml) and edit the values as necessary\n* Deploy the chart: `helm install legend legend/legend -f values.yaml`\n\nLegend Helm Chart is hosted [here](https://artifacthub.io/packages/helm/legend/legend)\n\n*Usage*\n\nTo use legend via its CRD (Current version: v1beta1), create a spec file in the following format:\n\n```yaml\napiVersion: grofers.io/v1beta1\nkind: GrafanaDashboard\nmetadata:\n  name: # Name of the object internally\n  labels:\n    app: # Add name for reference\nspec:\n  apiVersion: grofers.io/v1beta1\n  kind: GrafanaDashboard\n  grafana_dashboard_spec: # The core spec/configuration on the basis of which legend will build the dashboards\n    #Dashboard Spec\n```\n\nFormat for [spec.grafana_dashboard_spec](./sample_input.yaml)\n\nTo create/update/delete the dashboard, run:\n\n```shell\nkubectl apply -f \u003cinput-file.yaml\u003e\nkubectl delete -f \u003cinput-file.yaml\u003e\n```\n\n#### Use Legend CLI\n\nLegend can also be installed as a CLI and used to create dashboards.\n\u003e At the current stage, Legend can only create dashboards but not delete them becuase it does not\n\u003e record the state of dashboards it created anywhere\n\n*Installation*\n\nLegend requires python3. It is recommended to install legend in a virtual env\n\n```shell\nbrew install jsonnet\nmkvirtualenv -p `which python3` legend\npip install git+https://github.com/grofers/legend\nlegend configure\n```\n\n*Configuration*\n\n`LEGEND_HOME` represents the home directory of Legend, by default it is the home directory of the user.\nYou can override by setting the `LEGEND_HOME` env variable while running legend\n\nLegend needs a configuration file to talk to Grafana, by default it searches for it in `LEGEND_HOME/.legend/legend.cfg`, you can over-ride this with passing `-c` option while runing the commands.\n\nThe format for legend.cfg:\n\u003e This is pre-requisite to run legend as a CLI.\n\n```shell\n[grafana]\napi_key = # Grafana key with write permission if you are using Legend to create a dashboard, if not read permissions to get the alerting id\nprotocol = [https|http] # ex: https\nhost = # Grafana host url\n```\n\nTo configure legend\n\n```shell\nlegend configure\n```\n\n*Running legend*\n\n```shell\nUsage: legend [OPTIONS] COMMAND [ARGS]...\n\nOptions:\n  --help  Show this message and exit.\n\nCommands:\n  apply\n  build\n  configure\n  publish\n```\n\n## Contribution\n\nYou can contribute to legend in two ways:\n\n*Developing/improving legend's functionality*\n\n* You can pick up the existing issues in the github repo of legend and work on the fixes.\n* Or, you can raise an issue (bug-report or feature-request).\n* Fork this repo and setup up a branch on your forked repo to work on the contribution.\n* Follow the guide [developing on legend](docs/developing-on-legend.md) for getting a detailed idea about the rightful way of developing and testing over legend.\n* Raise the PR containing the reference to the issue it intends to solve.\n\n*Improve the metrics legend creates for a service*\n* This is one of the biggest offerings of Legend - pre configured metrics for a wide variety of\ncomponents.\n* If you are contibuting to the existing metrics or writing new ones please follow the giude [contributing-to-metric-library](docs/contributing-to-metric-library.md)\n* To Run e2e tests locally follow the guide [testing on legend](docs/developing-on-legend.md#testing).\n\n* Raise a PR\n\n## Legend internals\n\n[Legend internals](docs/legend-internals.md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgrofers%2Flegend","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgrofers%2Flegend","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgrofers%2Flegend/lists"}