Thanks for your interest in working on Performance Co-Pilot (PCP) in this years Google Season of Docs program. PCP is a system-level performance analysis toolkit for complex, distributed computer systems.
The tools in PCP are fairly well documented, but there is plenty of room for improvement! Below are a list of project ideas and areas we'd like to see the existing documentation improved, and new documentation added.
If you find below projects of interest, please contact the group of mentors at pcp-mentors@groups.io and CC individual mentors listed with your area(s) of interest.
Please provide at that time:
We'll then chat with you directly about the idea(s) and work with you on a project proposal. A strong proposal will likely include more than one idea from the list that follows, and a strong candidate would be one with an interest in learning about performance analysis, monitoring tools, and improving documentation!
To learn about PCP basics, philosophy and tools, we recommend you:
grafana-pcp is a plugin for Grafana, which allows the visualization of Performance Co-Pilot metrics in the Grafana metric visualization application. There are three data sources available at the moment:
All three data sources access PCP metric data via pmproxy REST APIs, which in turn requests the metric values from the scalable Redis database, pmapi or the bpftrace PMDA. Grafana dashboards can be exported in JSON format and shipped with grafana-pcp or imported using the Grafana provisioning mechanisms.
This is a significant opportunity for a technical writer to work with PCP developers to document the existing functionality, write guides, document REST APIs and the administrative procedures required to setup local and cloud-based time series analysis at scale.
Expected results: Initial documentation is available at grafana-pcp.readthedocs.io, which will serve as a starting point. This documentation should be extended by describing the functionality of grafana-pcp in much greater detail, adding screenshots, infographics and various guides to setup core functionality. Additionally, the documentation should contain a section about the technical details - specifically the interaction of all involved components (pmcd, pmproxy, pmseries, redis, Grafana) with one or more diagrams.
Mentors: Andreas Gerstmayr <agerstmayr@redhat.com> , Nathan Scott <nathans@redhat.com>
One area of need in the PCP documentation identified at last years conference was for us to provide short, hands-on introductory texts and videos that guide people toward the in-depth documentation they need. The deep documentation exists and is needed, but its buried in alot of the detail-oriented, jargon-heavy books.
Expected results: A series of short, introductory pieces will be created that provide simple introductions to complex topics. These topics include writing new instrumentation agents, application instrumentation in Java, Go, Rust, python and C languages, writing analysis tools, and some PCP administration tasks. These will each link to the detailed documentation elsewhere - such as in the 'Users and Administors Guide', or the 'Programmers Guide'.
Mentors: Christian Horn <chorn@redhat.com> , Apurva Bhide <abhide@redhat.com>
This project involves documenting recent advances in the performance analysis capabilities provided by PCP within the pbench benchmarking and analysis framework. This involves documenting the new pbench direction of using the PCP pmlogger tool's remote collection and efficient archive storage capabilities. Users should also be guided through the processes for adding new PCP metrics into the set collected during a pbench benchmarkng run. This could be in the form of tutorials, extensions to the existing online pbench documentation, other novel formats, or all of the above.
Expected results: This project provides a good opportunity to the technical writer to work hand-in-hand with PCP and pbench developers. The new content will need to link in, and form part of the existing pbench documentation, such that it guides the (expert level) users how to use the tools in an intuitive and informative way.
Mentors: Ashwin Nayak <ashwinnayak111@gmail.com> , Nathan Scott <nathans@redhat.com>
The Performance Co-Pilot documentation currently exists in several forms. These are the primary PCP website and the PCP books (docbook format). This project will focus on transfering and updating this docbook content to RST such that it can be hosted on the modern, community readthedocs.io site. This will allow community contributors to more easily change and extend this content.
Expected results: You will work with the mentors to setup the Performance Co-Pilot readthedocs.io hosting, and by the end of the project we will be able to edit and contribute to the books directly through github.
Mentors: Apurva Bhide <abhide@redhat.com> , Nathan Scott <nathans@redhat.com>
The Performance Co-Pilot REST API is currently documented in man page format primarily. This is not ideal for web developers, so we'd like to transition to separate formatted web pages describing individual requests, allowed inputs, sample outputs, etc. Likely, this would also be in RST form such that it can be hosted on the modern, community readthedocs.io site. This will allow community contributors to more easily change and extend this content.
Expected results: You will work with the mentors to create modern REST API documentation for the Performance Co-Pilot, readily consumable by web developers.
Mentors: Andreas Gerstmayr <agerstmayr@redhat.com> , Nathan Scott <nathans@redhat.com>
The pbench benchmarking suite makes use of Performance Co-Pilot services for recording arbitrary performance metrics during benchmark runs. It is currently documented in a traditional fashion similar to PCP itself, with much content in large individual files and typically in MarkDown format. This project will focus on transfering and updating the pbench guides to RST such that it can be hosted on the modern, community readthedocs.io site. This will allow community contributors to more easily change and extend this content.
Expected results: You will work with the mentors to setup the pbench readthedocs.io hosting, and by the end of the project we will be able to edit and contribute to the content directly through github.
Mentors: Ashwin Nayak <ashwinnayak111@gmail.com> , Nathan Scott <nathans@redhat.com>