{"id":20345200,"url":"https://github.com/rstgroup/zf-grafana-dashboards-module","last_synced_at":"2026-05-11T00:32:45.896Z","repository":{"id":77770439,"uuid":"101865646","full_name":"rstgroup/zf-grafana-dashboards-module","owner":"rstgroup","description":"This module contains integration with Grafana tool via it's HTTP APIs.","archived":false,"fork":false,"pushed_at":"2017-09-15T09:33:58.000Z","size":61,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-01-14T20:54:46.532Z","etag":null,"topics":["grafana","php","zend-framework"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rstgroup.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,"publiccode":null,"codemeta":null}},"created_at":"2017-08-30T09:53:31.000Z","updated_at":"2021-05-04T20:05:48.000Z","dependencies_parsed_at":null,"dependency_job_id":"9f34adc0-6973-4501-99d4-b183191cfca8","html_url":"https://github.com/rstgroup/zf-grafana-dashboards-module","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rstgroup%2Fzf-grafana-dashboards-module","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rstgroup%2Fzf-grafana-dashboards-module/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rstgroup%2Fzf-grafana-dashboards-module/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rstgroup%2Fzf-grafana-dashboards-module/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rstgroup","download_url":"https://codeload.github.com/rstgroup/zf-grafana-dashboards-module/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241876113,"owners_count":20035380,"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","php","zend-framework"],"created_at":"2024-11-14T22:07:15.694Z","updated_at":"2026-05-11T00:32:45.855Z","avatar_url":"https://github.com/rstgroup.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ZF Grafana Module\n\nThis module contains integration with Grafana tool via it's [HTTP APIs](http://docs.grafana.org/http_api/).\n\n## Installation\n\n```bash\ncomposer require rstgroup/zf-grafana-module\n```\n\n..and then add the module to your app using ZF system configuration (`config/application.config.php`):\n```php\nreturn [\n    'modules' =\u003e [\n        'RstGroup\\ZfGrafanaModule',\n    ],\n]\n```\n\nThe last step is providing database connection and HTTP client to allow the library to communicate with other services.\nUse aliasing functionality of Zend's Service Manager to define:\n* `\\RstGroup\\ZfGrafanaModule\\Repository\\DashboardApiRepositoryFactory::HTTP_CLIENT_SERVICE` \u003cbr /\u003e\n    HTTP client that implements `Http\\Client\\HttpClient` interface \n* `\\RstGroup\\ZfGrafanaModule\\Repository\\DashboardApiRepositoryFactory::REQUEST_FACTORY_SERVICE` \u003cbr /\u003e\n    request factory used to create HTTP requests\n* `\\RstGroup\\ZfGrafanaModule\\Repository\\DbalMetadataRepositoryFactory::SERVICE_CONNECTION` \u003cbr /\u003e\n    Doctrine DBAL Connection to database where the dashboard's metadata will be stored\n* `\\RstGroup\\ZfGrafanaModule\\Repository\\DbalIdMappingRepositoryFactory::SERVICE_CONNECTION` \u003cbr /\u003e\n    Doctrine DBAL Connection to database where the dashboard's ID mapping will be stored\n\n## Dashboards\n\nModule gives you functionality to automatically synchronize your dashboards with given Grafana instance.\n  \n### Usage\n\nModule provides CLI command:\n\n```bash\nphp public/index.php grafana migrate\n```\n  \nThere is currently no param required. All the information about dashboards is fetched from app's configuration.\n  \n### Defining dashboards to sync\n\nBy default, script scans through `build/dashboards` directory, looking for `.json` files with dashboard definition.\n\nThe directory to search can be easily changed in config file, here's the example:\n\n```php\nreturn [\n    'dashboard-migrations' =\u003e [\n        'repositories' =\u003e [\n            \\RstGroup\\ZfGrafanaModule\\Repository\\FilesystemDirectoryRepository::class =\u003e [\n                'path' =\u003e 'path/to/your/directory',\n            ],\n        ],\n    ],\n];\n```\n\n### Custom dashboard definition source\n\nIt's also possible to store dashboard definitions elsewhere. To do it, you need to do two things:\n \n* Implement your own `DashboardApiRepository`, define it in Zend's Service Manager and configure module to use it:\n \n    ```php\n    return [\n        'service_manager' =\u003e [\n            'factories' =\u003e [\n                MyOwnRepository::class =\u003e MyOwnRepositoryFactory::class,\n            ]\n        ],\n        'dashboard-migrations' =\u003e [\n            'source-repository' =\u003e [\n                'service' =\u003e MyOwnRepository::class,\n            ]\n        ]\n    ]\n    ```\n     \n* Implement your own `DashboardIdsProvider`, that will return the IDs to fetch from your custom repository.\nThen just alias your custom provider by the interface name:\n\n    ```php\n    return [\n        'service_manager' =\u003e [\n            'aliases' =\u003e [\n                \\RstGroup\\ZfGrafanaModule\\Controller\\Helper\\DashboardIdsProvider::class =\u003e \\Your\\Custom\\Provider::class,\n            ];\n        ]\n    ];\n    ```\n\n\n### Defining remote repository\nTo make synchronizing work, you need to pass Grafana API basic URL and API key. These values should be passed to app's\nconfiguration via config files (or, better, in Consul, if your app can fetch configuration from it!):\n\n```php\nreturn [\n    'dashboard-migrations' =\u003e [\n        'repositories' =\u003e [\n            \\RstGroup\\ZfGrafanaModule\\Repository\\DashboardApiRepository::class =\u003e [\n                'url'     =\u003e 'http://url.to.grafana.com/api',\n                'api-key' =\u003e 'grafana-api-key',\n            ],\n        ],\n    ],\n];\n```\n\nThe next thing you need is HTTP Client (which implements [PSR's client interface](http://docs.php-http.org/en/latest/clients.html)) \nand HTTP message factory implementation (see [http://docs.php-http.org/en/latest/message/message-factory.html]())\n\nYou should pass those in you app's configuration, aliasing predefined service names, like in the example below:\n\n```php\nreturn [\n    'service_manager' =\u003e [\n        'aliases' =\u003e [\n            \\RstGroup\\ZfGrafanaModule\\Repository\\DashboardApiRepositoryFactory::HTTP_CLIENT_SERVICE       =\u003e \\Http\\Adapter\\Guzzle6\\Client::class,\n            \\RstGroup\\ZfGrafanaModule\\Repository\\DashboardApiRepositoryFactory::REQUEST_FACTORY_SERVICE =\u003e \\Http\\Message\\MessageFactory\\GuzzleMessageFactory::class,\n        ]\n    ]\n];\n```\n\n### Metadata\n\n#### Why is there any metadata?\n\nThe module needs to store Dashboard's metadata. It's because of Grafana API, which generates additional identifiers\nand parameters for published dashboards.\n\nFirst of these is dashboard's \u003cstrong\u003eSLUG\u003c/strong\u003e. The slug is a textual, URL-safe representation of dashboard's Title. Slug is used in\nAPI as the required parameter in GET requests and thus can be trated as identifier.\n\nSecond one is  Dashboard's \u003cstrong\u003eID\u003c/strong\u003e, generated right after dashboard creation. The ID is a positive integer. It is used in update\nrequest (`POST`) and has to be provided as dashboard definition (inside of JSON), thus also can be treat as dashboard's \nidentifier - the second, less important one :))\n\nThe next metadata parameter is dashboard's \u003cstrong\u003eVERSION\u003c/strong\u003e - after each update, the version is incremented. If you try to update\nyour dashboard with the one with lower version number - API will refuse the change.\n \nThe last parameter is \u003cstrong\u003eSCHEMA VERSION\u003c/strong\u003e, which determines the version of definition schema itself, so\nGrafana instances are able to determine if it's up-to-date enough to parse given dashboard definition.\n\n#### Storage\n \nBy default - metadata is stored in MySQL database, thus the Doctrine DBAL Connection should be aliased for mapper to work:\n\n```php\nreturn [\n    'service_manager' =\u003e [\n        'aliases' =\u003e [\n            \\RstGroup\\ZfGrafanaModule\\Repository\\DbalIdMappingRepositoryFactory::SERVICE_CONNECTION =\u003e 'Your\\Doctrine\\Dbal\\Connection'\n        ]\n    ]\n]\n```\n\nThe table should follow the definition below:\n\n```mysql\nCREATE TABLE dashboard_metadata (\n  dashboard_id VARCHAR(255) NOT NULL PRIMARY KEY,\n  grafana_id INT NOT NULL,\n  dashboard_version INT NOT NULL,\n  dashboard_schema_version INT DEFAULT NULL\n) DEFAULT CHARACTER SET 'utf8';\n```\n\n#### ID mapping\n\nBecause the SLUG is created on the Grafana API's side, there is a need for keeping\nthe local -\u003e remote ID mapping.\n\nBy default, the local identifier of dashboard is its definition's filename. Mapping is stored\nin the database, thus the Doctrine DBAL Connection should be aliased for mapper to work:\n\n```php\nreturn [\n    'service_manager' =\u003e [\n        'aliases' =\u003e [\n            \\RstGroup\\ZfGrafanaModule\\Repository\\DbalIdMappingRepositoryFactory::SERVICE_CONNECTION =\u003e 'Your\\Doctrine\\Dbal\\Connection'\n        ]\n    ]\n]\n```\n\nThe mapping table should follow the definition:\n\n```mysql\nCREATE TABLE dashboard_id_mapping (\n  local_id VARCHAR(255) NOT NULL PRIMARY KEY,\n  remote_id VARCHAR(255) NOT NULL\n) DEFAULT CHARACTER SET 'utf8';\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frstgroup%2Fzf-grafana-dashboards-module","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frstgroup%2Fzf-grafana-dashboards-module","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frstgroup%2Fzf-grafana-dashboards-module/lists"}