External metrics sink

Namespace can send instance resource metrics to an external Prometheus remote write endpoint. This is an advanced configuration path for teams that want to keep a copy of Namespace instance metrics in their own observability system.

The sink is configured per instance. Namespace sends guest CPU, memory, disk, and filesystem metrics to the configured remote write endpoint.

Requirements

You need a Prometheus remote write endpoint and credentials that can write to it. If the endpoint requires authentication, store the credential in the Namespace vault and reference the secret ID from the instance configuration.

For Grafana Cloud Metrics, use the remote write endpoint shown in the Grafana Cloud portal. It usually has this form:

https://prometheus-prod-<region>.grafana.net/api/prom/push

Grafana Cloud remote write uses basic auth. The username is the metrics instance ID. The password is a Grafana Cloud token with metrics write permissions.

Store the remote write secret

Create a Namespace vault secret from a local file that contains the remote write password or token:

$
nsc vault add --from_file prometheus-remote-write-token.txt --description "Prometheus remote write token"

The command returns an object ID such as:

{
  "object_id": "sec_abc123",
  "description": "Prometheus remote write token",
  "version": "secv_def456"
}

Use the object_id value in the sink configuration. The secret is resolved by the host and is not exposed inside the guest.

Create an instance with a metrics sink

Create an experimental configuration file:

{
  "prometheusMetricsSink": {
    "url": "https://prometheus-prod-<region>.grafana.net/api/prom/push",
    "basicAuthUsername": "<metrics-instance-id>",
    "basicAuthPasswordSecretRef": "sec_abc123"
  }
}

Create the instance with that configuration:

$
nsc create --bare --experimental_from prometheus-metrics-sink.json

You can combine --experimental_from with the other flags you normally pass to nsc create, such as shape, image, duration, labels, or purpose.

For the full configuration schema, see the PrometheusMetricsSink API reference.

Bearer token endpoints

If your remote write endpoint accepts bearer token authentication, use bearerTokenSecretRef instead of basic auth:

{
  "prometheusMetricsSink": {
    "url": "https://prometheus.example.com/api/v1/write",
    "bearerTokenSecretRef": "sec_abc123"
  }
}

Do not configure bearer token and basic auth on the same sink.

Metrics and labels

The external sink exports guest metrics with these default metric name prefixes:

• guest_cpu_
• guest_memory_
• guest_disk_
• guest_filesystem_

Namespace always adds these identity labels:

• nsc_instance_id
• nsc_tenant_id

Metric-specific labels are preserved. For example, CPU metrics include cpu and mode, disk metrics include device, and filesystem metrics include device, filesystem, and mountpoint when the source metric provides them.

Namespace-internal routing labels are removed before export. The sink does not send labels such as nsc_vm_id, nsc_cluster_id, nsc_region, nsc_worker, or nsc_layer.

Verify ingestion

After the instance starts, query the external Prometheus-compatible backend for the instance ID:

To list the resource metric families that arrived:

For Grafana Cloud, you can query the Prometheus API directly with basic auth:

$
curl -u "<metrics-instance-id>:<remote-write-token>" --get --data-urlencode 'query=count({nsc_instance_id="<instance-id>"})' https://prometheus-prod-<region>.grafana.net/api/prom/api/v1/query

If the count is zero, confirm that the instance was created with the expected configuration and that the remote write token has metrics write permissions.