> ## Documentation Index
> Fetch the complete documentation index at: https://namespace.so/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```text theme={null}
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:

```bash theme={null}
nsc vault add --from_file prometheus-remote-write-token.txt --description "Prometheus remote write token"
```

The command returns an object ID such as:

```json theme={null}
{
  "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:

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

Create the instance with that configuration:

```bash theme={null}
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](https://buf.build/namespace/cloud/docs/main%3Anamespace.cloud.compute.v1beta#namespace.cloud.compute.v1beta.CreateInstanceRequest.ExperimentalFeatures.PrometheusMetricsSink).

## Bearer token endpoints

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

```json prometheus-metrics-sink-bearer.json theme={null}
{
  "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:

```promql theme={null}
count({nsc_instance_id="<instance-id>"})
```

To list the resource metric families that arrived:

```promql theme={null}
count({nsc_instance_id="<instance-id>", __name__=~"guest_(cpu|memory|disk|filesystem).*"})
```

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

```bash theme={null}
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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.