Skip to content

docs: add Alloy UI troubleshooting section to monitoring docs #340

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
AgustinRamiroDiaz wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: add Alloy UI troubleshooting section to monitoring docs #340

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
37 changes: 32 additions & 5 deletions pages/validators/monitoring.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -376,17 +376,44 @@ Look for messages indicating successful batch sending (no error codes like 401,
`instance="${NODE_ID}"` or `validator_name="${VALIDATOR_NAME}"`
(example: `genlayer_node_uptime_seconds{instance="0xYourID"}`).

Troubleshooting
- No local metrics:
## Troubleshooting

### Using the Alloy UI

The Grafana Alloy service includes a built-in web UI for troubleshooting and monitoring the telemetry pipeline. Access it at:

```
http://localhost:12345
```

The Alloy UI provides:
- **Targets view** (`/targets`): Shows the status of all scrape targets. Check if your node's metrics endpoint shows as **UP**.
- **Graph view** (`/graph`): Explore and query collected metrics locally before they're forwarded.
- **Component health**: View the status of all Alloy pipeline components (scrapers, relabelers, writers).

<Callout type="info">
If metrics are not appearing in the central Grafana Cloud, first verify they show correctly in the local Alloy UI. This helps isolate whether the issue is with metrics collection or forwarding.
</Callout>

### Common Issues

- **No local metrics**:

```bash copy
curl http://localhost:9153/metrics
```

— it should return Prometheus-formatted data.
Authentication errors (401/403): Double-check CENTRAL_MONITORING_USERNAME, CENTRAL_MONITORING_PASSWORD, CENTRAL_LOKI_USERNAME, and CENTRAL_LOKI_PASSWORD in .env.
No data pushed: Ensure URLs in .env have no trailing slash.
Help: Share Alloy logs

Comment on lines +400 to +407
Copy link
Contributor

@coderabbitai coderabbitai bot Jan 28, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Indent the code block so it stays inside the list item.
Right now the fenced block and the explanatory line render outside the “No local metrics” bullet. Indent them to keep list formatting consistent.

💡 Proposed fix 
- **No local metrics**:
-
-```bash copy
-curl http://localhost:9153/metrics
-```
-
-— it should return Prometheus-formatted data.
+ **No local metrics**:
+  
+  ```bash copy
+  curl http://localhost:9153/metrics
+  ```
+  
+  — it should return Prometheus-formatted data.
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
- **No local metrics**:
```bash copy
curl http://localhost:9153/metrics
```
— it should return Prometheus-formatted data.
Authentication errors (401/403): Double-check CENTRAL_MONITORING_USERNAME, CENTRAL_MONITORING_PASSWORD, CENTRAL_LOKI_USERNAME, and CENTRAL_LOKI_PASSWORD in .env.
No data pushed: Ensure URLs in .env have no trailing slash.
Help: Share Alloy logs
- **No local metrics**:
🤖 Prompt for AI Agents 
In `@pages/validators/monitoring.mdx` around lines 400 - 407, Indent the fenced
code block and the explanatory line so they remain part of the "No local
metrics" list item: locate the "No local metrics" heading and the
triple-backtick block containing "curl http://localhost:9153/metrics" and indent
that block plus the following line "— it should return Prometheus-formatted
data." (e.g., add consistent leading spaces so the code fence and the
explanatory em-dash line are nested under the "No local metrics" bullet).

- **Authentication errors (401/403)**: Double-check `CENTRAL_MONITORING_USERNAME`, `CENTRAL_MONITORING_PASSWORD`, `CENTRAL_LOKI_USERNAME`, and `CENTRAL_LOKI_PASSWORD` in `.env`.

- **No data pushed**: Ensure URLs in `.env` have no trailing slash.

- **Target showing DOWN in Alloy UI**: Verify your node is running and the ops port (9153) is accessible. Check that `NODE_METRICS_ENDPOINT` in `.env` is correct.

### Getting Help

Share Alloy logs when asking for assistance:

```bash copy
docker logs genlayer-node-alloy
Expand Down