Gateway troubleshooting

Use this order to isolate a problem without changing several components at once: metric source first, then OAuth 2.0, then the exporter, and finally the Eyenode view.

Quick checks

1. From the agent process, confirm that node_exporter:9100/metrics responds.
2. Confirm that all four OTEL_GATEWAY_* variables are available to the process without printing the secret.
3. Review scrape and export logs. With OpenTelemetry Collector, confirm the debug exporter metrics first.
4. Confirm the gateway HTTPS endpoint and verify the selected tenant and time range in Eyenode.

Common problems

Symptom	Check	Next action
401 or token retrieval fails	Token URL, client ID, secret encoded as base64(username:app_password), and the openid scope.	Correct the affected variable, restart the agent, and review authentication logs.
No local metrics	Connectivity, DNS, network permissions, and the source /metrics path.	Validate the source from the environment where the agent runs.
Metrics appear in debug, but not in Eyenode	OTEL_GATEWAY_ENDPOINT, HTTPS connectivity, and OTLP/HTTP exporter logs.	Review the URL, egress network path, and the exact exporter error.
Collector does not recognize oauth2client	Installed distribution.	Use OpenTelemetry Collector Contrib or a distribution containing that extension.
Alloy does not scrape	Target, interval, DNS, and Alloy network access to the Prometheus endpoint.	Correct the prometheus.scrape block and check the logs again.

Gather useful evidence

Share only error messages and timestamps; remove tokens, secrets, and authorization headers. State which guide you followed: OpenTelemetry Collector or Grafana Alloy.