Affected: LaunchDarkly Relay Proxy
This article provides troubleshooting steps for resolving common metric export issues, using as an example to scrape metrics from LaunchDarkly Relay Proxy. The Relay Proxy-side troubleshooting steps apply to all supported metric exporters.
Symptoms
One or more of the following behaviors occurs:
- The Prometheus target state displays as DOWN.
- The following error appears in Prometheus:
Error scraping target: dial tcp <address>:8031: connect: connection refused
- Relay Proxy metrics do not appear when you query them in Prometheus.
- The /metrics endpoint does not return data when accessed directly.
Cause
One of the following conditions exists:
- The Relay Proxy is not running.
- Metrics are not enabled in the Relay Proxy configuration.
- The Relay Proxy is not listening on the expected port.
- The Relay Proxy binds only to 127.0.0.1 and is not reachable externally.
- Prometheus cannot reach the Relay Proxy due to networking configuration.
- The Relay Proxy logs contain configuration or startup errors.
These conditions prevent Prometheus from scraping metrics. The same Relay Proxy-side conditions affect all supported metric exporters.
Solution
Follow these steps to configure Prometheus and verify that Relay Proxy metrics are exported correctly.
Configure Prometheus export in the Relay Proxy
Configure the following properties in your Relay Proxy configuration file or by using environment variables found here: https://github.com/launchdarkly/ld-relay/blob/v8/docs/configuration.md#file-section-prometheus
To enable Prometheus export in a configuration file:
{
"prometheus": {
"enabled": true,
"port": 8031,
"prefix": "ldrelay"
}
}To enable Prometheus export using environment variables:
USE_PROMETHEUS=true PROMETHEUS_PORT=8031 PROMETHEUS_PREFIX=ldrelay
- Start the Relay Proxy using this configuration.
- After startup, the Relay Proxy exposes metrics at:
http://localhost:8031/metrics
Configure Prometheus to scrape the Relay Proxy
- Create or update your prometheus.yml file:
global:
scrape_interval: 15s
scrape_configs:
- job_name: 'ld-relay'
static_configs:
- targets: ['localhost:8031']- If Prometheus runs in Docker and the Relay runs on the host machine, use:
- targets: ['host.docker.internal:8031']
- Start Prometheus:
prometheus --config.file=prometheus.yml
- Open http://localhost:9090.
- Click Status, then click Targets. The ld-relay job appears.
If the configuration is correct, the target state displays as UP.
Verify the metrics endpoint directly
Run:
curl http://localhost:8031/metrics
If the endpoint works, it returns plain text metrics data.
If the request fails with connection refused, the Relay Proxy is not listening on the configured port or is not running.
Confirm the Relay Proxy is running
Run:
lsof -i :8031
- Confirm that a process listens on port 8031.
- If no process appears, restart the Relay Proxy.
Review Relay Proxy logs during startup
Look for:
- Metrics initialization errors.
- Invalid configuration errors.
- Port binding failures.
If the Relay Proxy cannot initialize metrics, Prometheus cannot scrape them.
Confirm network accessibility
Verify that Prometheus can reach the Relay Proxy.
- Confirm the Relay Proxy binds to the correct interface.
- Confirm port 8031 is exposed if using containers.
- Confirm no firewall blocks the port.
- Confirm the correct hostname is used in prometheus.yml.
Restart Prometheus after making configuration changes.
After completing these steps, Prometheus successfully scrapes Relay Proxy metrics. The target state displays as UP, and Relay Proxy metrics appear in query results.