{"id":18293071,"url":"https://github.com/kubesphere/monitoring-dashboard","last_synced_at":"2025-04-05T11:30:45.170Z","repository":{"id":46148697,"uuid":"250206020","full_name":"kubesphere/monitoring-dashboard","owner":"kubesphere","description":"Custom Metrics Monitoring Dashboard for Apps on KubeSphere","archived":false,"fork":false,"pushed_at":"2023-03-07T02:18:36.000Z","size":11976,"stargazers_count":16,"open_issues_count":4,"forks_count":8,"subscribers_count":5,"default_branch":"master","last_synced_at":"2024-04-13T21:43:11.143Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kubesphere.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2020-03-26T08:50:13.000Z","updated_at":"2022-04-29T08:05:09.000Z","dependencies_parsed_at":"2024-03-04T20:30:37.380Z","dependency_job_id":"12b3cbae-6e37-49a5-a825-4eaef345fe9a","html_url":"https://github.com/kubesphere/monitoring-dashboard","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kubesphere%2Fmonitoring-dashboard","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kubesphere%2Fmonitoring-dashboard/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kubesphere%2Fmonitoring-dashboard/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kubesphere%2Fmonitoring-dashboard/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kubesphere","download_url":"https://codeload.github.com/kubesphere/monitoring-dashboard/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247330401,"owners_count":20921623,"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":[],"created_at":"2024-11-05T14:21:47.255Z","updated_at":"2025-04-05T11:30:45.137Z","avatar_url":"https://github.com/kubesphere.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# KubeSphere Monitoring Dashboard\r\n\r\nThe project is inspired by [Grafana](http://grafana.com/) but with significant difference in data persistence, multitenancy supports and dashboard template sharing to fit KubeSphere's context. It is not a replacement to Grafana. It requires KubeSphere backend and frontend to work.\r\n\r\nThis repo is aimed at KubeSphere developers who want to understand dashboard data model, concepts and usage and how to contribute, as the custom monitoring feature is introduced as of v3.0.  \r\n\r\n## Table of contents\r\n\r\n- [KubeSphere Monitoring Dashboard](#kubesphere-monitoring-dashboard)\r\n  - [Table of contents](#table-of-contents)\r\n  - [Get Started](#get-started)\r\n  - [Prerequisites](#prerequisites)\r\n  - [Quick Start](#quick-start)\r\n  - [Concept and Design](#concept-and-design)\r\n    - [Data Model](#data-model)\r\n      - [Metadata](#metadata)\r\n      - [Panels](#panels)\r\n      - [Templatings](#templatings)\r\n    - [Data Source](#data-source)\r\n    - [Multi-tenancy](#multi-tenancy)\r\n    - [Dashboard Template](#dashboard-template)\r\n  - [Manual](#manual)\r\n    - [annotations](#annotations)\r\n    - [Query](#query)\r\n    - [Panels](#panels-1)\r\n      - [Chart](#chart)\r\n      - [Legend](#legend)\r\n    - [Time Range](#time-range)\r\n    - [Variables](#variables)\r\n  - [converter tool](#converter-tool)\r\n    - [Usage](#usage)\r\n    - [Integration with kubesphere backend](#integration-with-kubesphere-backend)\r\n  - [Development](#development)\r\n    - [APIs](#apis)\r\n    - [Backend](#backend)\r\n    - [Frontend](#frontend)\r\n  - [Contributing](#contributing)\r\n    - [Dashboard Gallery](#dashboard-gallery)\r\n\r\n## Get Started\r\n\r\n## Prerequisites\r\n\r\n- Kubernetes v17.0+\r\n- KubeSphere v3.0+\r\n\r\n## Quick Start\r\n\r\nTODO(@FeynmanZhou)\r\n\r\nThe stack making these possible includes KubeSphere backend, console and custom resources for dashboards. \r\n\r\n- [KubeSphere Backend](https://github.com/kubesphere/kubesphere): proxies metrics query, ensures data isolation over namespaces.\r\n- [KubeSphere Console](https://github.com/kubesphere/console): renders the dashboard with data and charts.\r\n- CustomResourceDefinition for Dashboard: defines dashboard data model.\r\n\r\n## Concept and Design\r\n\r\n### Data Model\r\n\r\nDashboards are backed by the custom resource definition (CRD) **`Dashboard`**. It is compromised of three components: metadata, panels and templatings. Below is an example: \r\n\r\n```yaml\r\napiVersion: monitoring.kubesphere.io/v1alpha1\r\nkind: Dashboard\r\nmetadata:\r\n  name: mysql-overview\r\n  namespace: default\r\nspec:\r\n  title: MySQL Overview\r\n  description: MySQL dashboard for the mysql exporter\r\n  time:\r\n    from: now-1h\r\n    to: now\r\n  datasource: prometheus\r\n  panels:\r\n  - type: singlestat\r\n    title\": Instance Up\r\n    targets:\r\n    - expr: mysql_up{release=\"$release\"}\r\n      instant: \"true\"\r\n  - type: graph\r\n    title: mysql  disk reads vs writes\r\n    targets:\r\n    - expr\": irate(mysql_global_status_innodb_data_reads{release=\"$release\"}[10m])\r\n      legendFormat\": reads\r\n    - expr\": irate(mysql_global_status_innodb_data_writes{release=\"$release\"}[10m])\r\n      legendFormat\": write\r\n  templatings:\r\n  - name: release\r\n    query: label_values(mysql_up,release)\r\n    type: query\r\n    sort: 0\r\n```\r\n\r\nOr you can use apiversion `monitoring.kubesphere.io/v1alpha2`, more fields are supported.\r\n\r\n```yaml\r\napiVersion: monitoring.kubesphere.io/v1alpha2\r\nkind: Dashboard\r\nmetadata:\r\n  name: mysql-overview-rev5\r\n  namespace: default\r\nspec:\r\n  annotations:\r\n  - datasource: -- Grafana --\r\n    enable: true\r\n    iconColor: '#e0752d'\r\n    name: PMM Annotations\r\n    tags:\r\n    - pmm_annotation\r\n    type: tags\r\n  auto_refresh: 1m\r\n  editable: true\r\n  panels:\r\n  - colors:\r\n    - rgba(245, 54, 54, 0.9)\r\n    - rgba(237, 129, 40, 0.89)\r\n    - rgba(50, 172, 45, 0.97)\r\n    datasource: ${DS_PROMETHEUS}\r\n    decimals: 1\r\n    description: |-\r\n      **MySQL Uptime**\r\n\r\n      The amount of time since the last restart of the MySQL server process.\r\n    format: s\r\n    gauge:\r\n      maxValue: 100\r\n      thresholdMarkers: true\r\n    height: 125px\r\n    id: 12\r\n    targets:\r\n    - expr: mysql_global_status_uptime\r\n      refId: 1\r\n      step: 1m\r\n    title: MySQL Uptime\r\n    type: singlestat\r\n    valueName: current\r\n  templatings:\r\n  - default: $__auto_interval_interval\r\n    label: Interval\r\n    name: interval\r\n    type: interval\r\n    values:\r\n    - $__auto_interval_interval\r\n    - 1s\r\n    - 5s\r\n    - 1m\r\n    - 5m\r\n    - 1h\r\n    - 6h\r\n    - 1d\r\n  - datasource: ${DS_PROMETHEUS}\r\n    label: Host\r\n    name: host\r\n    request: label_values(mysql_up, instance)\r\n    type: query\r\n  time:\r\n    from: now-12h\r\n    to: now\r\n  timezone: browser\r\n  title: MySQL Overview\r\n```\r\nThe two versions can be compatible with each other while applying the newly CustomResourceDefinition lacated at `config/crd/bases`.\r\n\r\n#### Metadata\r\n\r\n|Name|Desc|\r\n|---|---|\r\n|`spec.title`|dashboard title|\r\n|`spec.description`|dashboard description|\r\n|`spec.time`|time range for display. see [Time Range](#time-range) for more info|\r\n|`spec.datasource`|data source to query, defaults to Prometheus|\r\n|`spec.annotations`|annotations for the grafana templates|\r\n\r\n#### Panels\r\n\r\nThe `spec.panels` defines a collection of panels. Panels are build blocks of a dashboard. Currently supported panels are row, singlestat, graph and table. See [Query](#query) and [Panels](#panels) for more info.\r\n\r\n#### Templatings\r\n\r\nThe `spec.templatings` defines a collection of variables. It is convenient to use variables in query expressions. See [Variable](#variable) for more info.\r\n\r\n\u003e Note that the data model is heavily inspired by [Grafana JSON model](https://grafana.com/docs/grafana/latest/reference/dashboard/) to gain compatibility. However, to adapt it to KubeSphere's context, we may bring in new fields and break changes.\r\n\r\n### Data Source\r\n\r\nNote: we currently only support Prometheus as data source.\r\n\r\n### Multi-tenancy\r\n\r\nMetrics data should be isolated across namespaces, which means namespace members can only view metrics in the namespace they belong to. This is implemented in the phase of [querying](#query). Any user-written expression will be mutated to make sure no query outside the scope of the namespace. \r\n\r\nTake the datasource Prometheus for example, KubeSphere backend will add a namespace matcher, i.e. `\u003cmetric_name\u003e{namespace=\u003cnamespace_name\u003e}`, to each query.\r\n\r\n### Dashboard Template\r\n\r\nDashboard is represented by a custom resource object. Select templates from [contrib/gallery](contrib/gallery), and run the following command to import:\r\n\r\n```\r\nkubectl apply --namespace \u003cNAMESPACE\u003e -f contrib/gallery/\u003cTEMPLATE_YAML_FILE\u003e\r\n```\r\n\r\nYou can also open source your template and contribute to Dashboard Gallery. Templates in Dashboard Gallery will be shipped with KubeSphere.\r\n\r\n## Manual\r\n\r\n### annotations\r\n\r\nNow we support annotations in version v1alpha2. Refers to `api/v1alpha2/annotations`, the merged structure definition inspired by [the grafana sdk](https://pkg.go.dev/github.com/grafana-tools/sdk#Annotation) makes a simplified definition.\r\n\r\n### Query\r\n\r\nExcept for the panel `row` , and the `text` panel in version v1alpha2, each panel accepts at least one data source query. It allows you to input query expressions and fetch metrics data.\r\n\r\nYou can use placeholders in queries. See [Variables](#variables) for more information.\r\n\r\n### Panels\r\n\r\n#### Chart\r\n\r\nWe currently support three types of panels in version v1alpha1:\r\n\r\n- Row\r\n- Singlestat\r\n- Graph\r\n\r\nAnd, support other types as following in version v1alpha2:\r\n\r\n- bargauge\r\n- table\r\n- text\r\n\r\n#### Legend\r\n\r\n### Time Range\r\n\r\nTime range specifies current dashboard time for display. The following are examples in use.\r\n\r\n|Example|From|To|\r\n|--|--|--|\r\n|Last 5 minutes|now-5m|now|\r\n|Today|now-1d|now|\r\n|This week|now-1w|now|\r\n|Last month|now-2M|now-1M|\r\n\r\n### Variables\r\n\r\n|Query|Desc|\r\n|--|--|\r\n|label_values(metric, label)|Returns a list of label values for the label in the specified metric.|\r\n\r\n## converter tool\r\n\r\nwe support a converter tool located at `tools/converter/dashboard_converter.go` can be used for importing dashboards from Grafana dashboard templates.\r\n\r\n### Usage\r\n```\r\nUsage of converter:\r\n  -inputPath string\r\n        a input path for the converter to look for jobs (default \"./manifests/inputs\")\r\n  -isClusterCrd\r\n        a flag that defines whether build the cluster dashboard resource or not\r\n  -name string\r\n        name of the dashboard resource (default \"your file name\")\r\n  -namespace string\r\n        namespace of the dashboard resource (default \"default\")\r\n  -outputPath string\r\n        a output path for the converter to store manifests (default \"./manifests/outputs\")\r\n```\r\n\r\nif we want to convert a dashboard json template to a k8s manifest, you can use make cmdline like this below:\r\n```\r\n\tmake convert -isClusterCrd=$(IS_CLUSTER_CRD) -namespace=$(NAMESPACE) -inputPath=$(INPUT) -outputPath=$(OUTPUT)\r\n```\r\n\r\nor:\r\n```\r\n\tgo run ./cmd/converter -isClusterCrd=$(IS_CLUSTER_CRD) -namespace=$(NAMESPACE) -inputPath=$(INPUT) -outputPath=$(OUTPUT) -name=$(Name)\r\n```\r\n\r\n### Integration with kubesphere backend\r\n\r\nIn addition to the command line above, the method `ConvertToDashboard` located at `tools/converter/dashboard_converter.go` can read bytes from Grafana dashboard templates, and convert to a `Dashboard` model, therefore the frontend developers can make visual presentations as needed.\r\n\r\n## Development\r\n\r\n### APIs\r\n\r\nFor dashboard APIs, see [docs/crd.md](docs/crd.md)\r\n\r\nThe project is built with kubebuilder v2.3.0.\r\n\r\n### Backend\r\n\r\nIf you find some fields should be included in the CRD, edit [api package](https://github.com/kubesphere/monitoring-dashboard/tree/master/api/) and regenerate the project by `make`. Kubebuilder is the tool we are using.\r\n\r\nIf you find bugs or want to add new APIs, implement new datasources to KubeSphere, read KubeSphere [developer guides](https://github.com/kubesphere/community/tree/master/developer-guide/concepts-and-designs) for monitoring.\r\n\r\n### Frontend\r\n\r\n@TODO(justahole)\r\n\r\n## Contributing\r\n\r\n### Dashboard Gallery\r\n\r\nIf you want to share your dashboard templates, you can submit dashboard template yaml files to gallery folder with an elaborate readme. Outstanding templates will be selected to ship with KubeSphere future releases.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkubesphere%2Fmonitoring-dashboard","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkubesphere%2Fmonitoring-dashboard","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkubesphere%2Fmonitoring-dashboard/lists"}