Documentation cleanup and addition of query-exporter metrics#158
Documentation cleanup and addition of query-exporter metrics#158richturner wants to merge 15 commits into
Conversation
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
|
@wborn maybe best to quickly review these changes, I have tried to ensure links are maintained. |
|
@codex review |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 7d63465a56
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| %% Connections | ||
| PromScrape --> Manager | ||
| PromScrape --> HAProxy | ||
| PromScape --> PostgreSQL |
There was a problem hiding this comment.
The Mermaid graph uses PromScape --> PostgreSQL, but the scrape config node is named PromScrape; this creates a second unintended node and misrepresents how PostgreSQL metrics are scraped. Readers following this diagram will see an incorrect architecture path, so the edge should reference the existing PromScrape node.
Useful? React with 👍 / 👎.
| direction TB | ||
| Manager["<b>Manager</b><br/>http://localhost:8404/metrics<br/>- Micrometer with Prometheus Registry<br/>- Runs on own embedded web server port 8404<br/>- OR_METRICS_ENABLED: true/false"]:::greenStyle | ||
| HAProxy["<b>HA Proxy</b><br/>http://localhost:8404/metrics<br/>- Uses prometheus-exporter<br/>- Runs on own embedded web server port 8404<br/>- Configured via haproxy.cfg"]:::greenStyle | ||
| Manager["<b>Manager</b><br/>http://localhost:8405/metrics<br/>- Micrometer with Prometheus Registry<br/>- Runs on own embedded web server port 8404<br/>- OR_METRICS_ENABLED: true/false"]:::greenStyle |
There was a problem hiding this comment.
This line documents the Manager metrics URL as http://localhost:8405/metrics but immediately says it runs on port 8404, which is contradictory and can lead to incorrect scrape/port-forward configuration. The endpoint and the descriptive port should match so operators don't configure the wrong target.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Pull request overview
This PR updates the documentation to (1) document new query-exporter / PostgreSQL metrics and (2) reorganize/consolidate parts of the Developer Guide (moving “ops/admin” content into a new System Administration page and adjusting navigation ordering).
Changes:
- Add PostgreSQL metrics documentation (via query-exporter) and update the metrics diagram endpoints.
- Introduce
System Administrationdoc and retarget existing docs to the new locations (e.g., DB backup/restore link from Quick Start). - Remove several older/duplicated Developer Guide pages and adjust
sidebar_positionordering across multiple docs.
Reviewed changes
Copilot reviewed 22 out of 22 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/user-guide/metrics.md | Updates metrics architecture diagram and adds a large new section documenting query-exporter PostgreSQL metrics. |
| docs/user-guide/deploying/release-management.md | Adds a note about CI/CD setting MANAGER_VERSION. |
| docs/user-guide/deploying/custom-deployment.md | Updates the agent/protocol documentation link and removes a “See Also” section. |
| docs/quick-start.md | Updates the DB backup/restore link to point to the new System Administration doc. |
| docs/developer-guide/working-on-ui-and-apps.md | Changes sidebar ordering. |
| docs/developer-guide/working-on-the-mobile-consoles.md | Changes sidebar ordering. |
| docs/developer-guide/working-on-maps.md | Changes sidebar ordering. |
| docs/developer-guide/useful-commands-and-queries.md | Removes this page (content appears consolidated elsewhere). |
| docs/developer-guide/system-administration.md | Adds new consolidated operations/admin guide (monitoring, JVM, DB, Docker, etc.). |
| docs/developer-guide/setting-up-an-ide.md | Streamlines IDE setup guidance; adds build/testing sections; adjusts structure and sidebar ordering. |
| docs/developer-guide/preparing-the-environment.md | Updates runtime tooling guidance and adjusts sidebar ordering. |
| docs/developer-guide/maintaining-an-installation.md | Removes this page (content appears consolidated into System Administration). |
| docs/developer-guide/licensing-guidelines-for-contributors.md | Updates copyright header example. |
| docs/developer-guide/installing-and-using-docker.md | Removes this page (Docker install guidance now points to upstream Docker docs). |
| docs/developer-guide/gateway-tunnelling-setup.md | Fixes a typo in a section header. |
| docs/developer-guide/docker-compose-profiles.md | Changes sidebar ordering. |
| docs/developer-guide/data-migration.md | Removes this page (content appears consolidated into System Administration). |
| docs/developer-guide/creating-a-custom-project.md | Changes sidebar ordering. |
| docs/developer-guide/connecting-protocol-adaptors-with-agents.md | Removes this page (replaced by the new SPI doc). |
| docs/developer-guide/building-and-testing.md | Removes this page (content moved into IDE setup doc). |
| docs/developer-guide/agent-protocol-spi.md | Adds a new, shorter Agent/Protocol SPI doc. |
| docs/developer-guide/adding-widgets-on-insights.md | Changes sidebar ordering. |
Comments suppressed due to low confidence (1)
docs/developer-guide/system-administration.md:139
- The page alternates between
openremote_postgresql_1andor-postgresql-1for the PostgreSQL container name. Please standardize on one naming scheme (or use a<PROJECT_NAME>_postgresql_1placeholder) to avoid copy/paste failures.
Use the following docker command to access the database on the docker host:
```shell
docker exec -it openremote_postgresql_1 psql -U postgres
</details>
---
💡 <a href="/openremote/documentation/new/main?filename=.github/instructions/*.instructions.md" class="Link--inTextBlock" target="_blank" rel="noopener noreferrer">Add Copilot custom instructions</a> for smarter, more guided reviews. <a href="https://docs.github.com/en/copilot/customizing-copilot/adding-repository-custom-instructions-for-github-copilot" class="Link--inTextBlock" target="_blank" rel="noopener noreferrer">Learn how to get started</a>.
| direction TB | ||
| Manager["<b>Manager</b><br/>http://localhost:8404/metrics<br/>- Micrometer with Prometheus Registry<br/>- Runs on own embedded web server port 8404<br/>- OR_METRICS_ENABLED: true/false"]:::greenStyle | ||
| HAProxy["<b>HA Proxy</b><br/>http://localhost:8404/metrics<br/>- Uses prometheus-exporter<br/>- Runs on own embedded web server port 8404<br/>- Configured via haproxy.cfg"]:::greenStyle | ||
| Manager["<b>Manager</b><br/>http://localhost:8405/metrics<br/>- Micrometer with Prometheus Registry<br/>- Runs on own embedded web server port 8404<br/>- OR_METRICS_ENABLED: true/false"]:::greenStyle |
| %% Connections | ||
| PromScrape --> Manager | ||
| PromScrape --> HAProxy | ||
| PromScape --> PostgreSQL |
| Force garbage collection with: | ||
|
|
||
| ```shell | ||
| docker exec -it openremote_manager_1 /usr/bin/jcmd 1 GC.run |
|
|
||
| ``` | ||
| Copyright 2021, OpenRemote Inc. | ||
| Copyright ${YEAR}, OpenRemote Inc. |
| ```shell | ||
| docker-machine version | ||
| docker -v | ||
| docker-compose -v |
Various documentation improvements relating to the developer guide and also added documentation for the new
query-exporterservice and the metrics it generates