Welcome! We're excited that you're interested in contributing. Below are some basic guidelines.
Grafana Explore Profiles follows a standard GitHub pull request workflow. If you're unfamiliar with this workflow, read the very helpful Understanding the GitHub flow guide from GitHub.
You are welcome to create draft PRs at any stage of readiness - this
can be helpful to ask for assistance or to develop an idea.
Before a piece of work is finished, it should:
- Be organised into one or more commits, each of which has a commit message that describes all changes made in that commit ('why' more than 'what' - we can read the diffs to see the code that changed).
- Each commit should build towards the whole - don't leave in back-tracks and mistakes that you later corrected.
- Have unit for new functionality or tests that would have caught the bug being fixed.
- Clone the repository
git clone [email protected]:grafana/pyroscope-app-plugin.git - Install the dependencies:
yarn install - Build the plugin in dev mode:
yarn dev - Start the Grafana server (with static data):
yarn server:static - Optionally, to enable the GitHub integration feature, read the "Enable GitHub integration" section below.
Then visit http://localhost:3000/a/grafana-pyroscope-app
Alternatively:
- To use live remote data, read the "Enable with live remote profile data" section below.
- To use a local version of Pyroscope, read the "Enable with a local version of Pyroscope" section below.
- To use a local version of Grafana, read this section.
- If not already done, copy the content of the
.env.localfile to a new.envfile in the root directory. - Fill in the missing
REMOTE_values in the.envfile. - Start the Grafana server:
yarn server:remote
- Start the local version of Pyroscope (see Pyroscope's contributing guide)
- Execute
yarn server:local
When clicking on a node of the flame graph, the plugin can offer to display information about the function being profiled in the form of a "Function details" contextual menu item.
To enable this feature:
- If not already done, copy the content of the
.env.localfile to a new.envfile in the root directory. - Fill in the missing
GITHUB_values in the.envfile. - Start the Grafana server.
For more information, refer to the Pyroscope GitHub integration documentation.
The plugin can help understand flame graphs by using a large-language model (LLM) to assist with profiling data interpretation.
To enable this feature:
- If not already done, copy the content of the
.env.localfile to a new.envfile in the root directory. - Fill in the missing
OPENAI_values in the.envfile. - Start the Grafana server.
For more information, refer to the Flame graph AI documentation.
For developing in this repo, requirements are generally managed by lint rules and pre-commit hooks. However, for other things, like code organization, please follow the pattern established by the rest of the repo.
In case of doubt, have a look at "Explore Profiles frontend architecture"
We use ESLint and Prettier to lint and format our code. These will be run in a pre-commit hook, but you can also setup your IDE to run them on save.
We use conventional commits to format our commit messages. This allows us to automatically generate changelogs and version bumps.
When opening a Pull Request (PR), please make sure that the title is properly prefixed with one of the following type: feat, fix, docs, test, ci, refactor, perf, chore or revert.
We encourage you to write tests, whether they are unit tests or end-to-end tests. They will give us the confidence that the plugin behaves as intended and help us capture any regression early.
For end-to-end testing (E2E), please have a look at our E2E testing documentation.
...