BYOC Monitoring Integrations

For BYOC deployments, a Prometheus server is deployed by default on the byoc-agent host and listens on port 9090. You can use this server directly to query collected metrics, scrape selected metrics into your own Prometheus, or forward metrics to your own storage system.

These options connect directly to the BYOC Prometheus server and do not require Metrics API Private Preview access or a VeloDB Cloud API key.

Before you start

Make sure your Grafana server or collector can reach the byoc-agent host on port 9090 through your private network. In the examples below, replace <byoc-agent-host> with the host's reachable private IP address or hostname. The HTTP examples use the server's default listener. Restrict access to trusted monitoring clients on your private network.

Choose a monitoring option

Goal	Option
Query metrics and visualize them in your own Grafana	Connect Grafana directly to the BYOC Prometheus server.
Pull selected metrics into your own Prometheus	Scrape the BYOC Prometheus `/federate` endpoint.
Forward metrics to your own storage system	Configure `remote_write` on the BYOC Prometheus server.

Connect your own Grafana

Add a Prometheus data source in your Grafana instance and set its URL to http://<byoc-agent-host>:9090. Grafana queries the collected metrics through the server's standard Prometheus HTTP API:

/api/v1/query: evaluate an instant PromQL query.
/api/v1/query_range: evaluate a PromQL query over a time range.

You can also call these endpoints directly. For query parameters and response formats, see the Prometheus HTTP API documentation.

Pull metrics through federation

To collect selected metrics in your own Prometheus instance, add a scrape job that targets the BYOC server's /federate endpoint. Use match[] selectors to choose the time series to collect and honor_labels: true to preserve their source labels.

Add the following job to your collector's existing scrape_configs list:

scrape_configs:
  - job_name: velodb-byoc-federation
    scheme: http
    metrics_path: /federate
    honor_labels: true
    params:
      'match[]':
        - '{__name__=~"doris_.+|node_.+"}'
    static_configs:
      - targets:
          - '<byoc-agent-host>:9090'

This example selects metrics whose names begin with doris_ or node_. Adjust the selectors to match the metrics you need. Federation returns the current values of selected time series, rather than their full history. See the Prometheus federation documentation for details.

Forward metrics with remote write

If your storage system supports the Prometheus remote write protocol, add a top-level remote_write section to /etc/prometheus/prometheus.yml on the byoc-agent host. Preserve the existing scrape jobs and other configuration. If remote_write is already configured, append the destination to its existing list.

remote_write:
  - url: https://<remote-write-host>/<remote-write-path>

Replace the URL with your storage system's remote write endpoint and configure any authentication or TLS settings it requires. Reload the Prometheus configuration after editing it. Prometheus supports reloading through SIGHUP, or through POST /-/reload when --web.enable-lifecycle is enabled.

Verify that your destination receives the metrics. For authentication, filtering with write_relabel_configs, and other settings, see the Prometheus remote write configuration reference.

Common errors

Symptom	What to check
Grafana or your collector cannot connect	Confirm that the `byoc-agent` host is reachable from the monitoring client and that network rules allow access to port `9090`.
Federation returns no metrics	Confirm that the `match[]` selectors match time series present in the BYOC Prometheus server.
Your remote storage receives no metrics	Confirm the remote write endpoint, required credentials, outbound network access, and that Prometheus successfully reloaded the configuration. Check the Prometheus logs for remote write errors.

Before you start​

Choose a monitoring option​

Connect your own Grafana​

Pull metrics through federation​

Forward metrics with remote write​

Common errors​

See also​