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

# Use Prometheus Agent to send metrics

> Configure Prometheus to send metrics to Cortex XCOR for analysis.

<Note>
  This feature isn't available to all Palo Alto Networks Cortex XCOR users and
  might not be visible in your app. For information about enabling this feature in your
  environment, contact [Cortex XCOR Support](/support).
</Note>

You can configure Prometheus to send metrics to Palo Alto Networks Cortex XCOR
using the
[Remote-Write Protocol 2.0 API](/ingest/metrics-traces/prometheus-remote-write)
over HTTPS.

<Note>
  Cortex XCOR supports only Prometheus Remote-Write Protocol versions 2.0.0
  or later and Prometheus server 3.0.0 or later. All requests must be encrypted using
  TLS, compressed payloads should be smaller than 16 MB, and metric payloads
  must contain fewer than 10,000 items.
</Note>

## Prerequisites

To forward metrics from Prometheus, you must first create a
[restricted service account](/administer/accounts-teams/service-accounts#create-a-restricted-service-account)
in Cortex XCOR, which generates an API token for Prometheus to authenticate
with Cortex XCOR. The API token only needs write access for Prometheus to
send metrics to Cortex XCOR.

<Warning>
  Store your API token in a secure location, such as a separate file or as a Kubernetes
  Secret, and reference it using an environment variable, such as `$API_TOKEN`.
  You can also bind a Kubernetes
  [Secret](https://kubernetes.io/docs/concepts/configuration/secret/) to an environment
  variable on the Pod.

  If you lose your token, you must create a new service account.
</Warning>

## Configure Prometheus

To implement remote write, you must configure your application and Prometheus to
use it. You must also install Prometheus Agent, which is beyond the scope of these
instructions and can vary depending on your usage.

For more information, see the Prometheus Operator documentation for
[installing the Prometheus Agent in Kubernetes](https://prometheus-operator.dev/docs/platform/prometheus-agent/)
or the
[Prometheus installation documentation](https://prometheus.io/docs/prometheus/latest/installation/)
for other scenarios.

1. Instrument your app with
   [Prometheus client libraries](https://prometheus.io/docs/instrumenting/clientlibs/)
   for scraping or
   [push metrics](https://prometheus.io/docs/instrumenting/pushing/) to the PushGateway.
2. Configure [third-party exporters](https://prometheus.io/docs/instrumenting/exporters/)
   to scrape or push metrics from third-party tools and services.
3. Add a
   [`remote_write`](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#remote_write)
   section to your `prometheus.yml` to forward metrics to Cortex XCOR.

   ```yaml theme={null}
   remote_write:
     - url: https://<COMPANY>.chronosphere.io/data/api/v1/prom/remote/write
       remote_timeout: 30s
       protobuf_message: io.prometheus.write.v2.Request
       headers:
         API-Token: $API_TOKEN
         Chronosphere-Metrics-Validation-Response: SHORT

       queue_config:
         batch_send_deadline: 1s
         max_samples_per_send: 2000
   ```

   * `url`: Replace `<COMPANY>` with the name of your company as it appears in the
     subdomain of the Cortex XCOR URL.
   * `remote_timeout`: Defines the timeout for Remote Write requests before failing
     and retrying. Default: `30s`.
   * `protobuf_message`: Specifies the Remote-Write v2 Protobuf format, which provides
     additional metric types and more efficient egress traffic than the v1 format.
     For more information, see the
     [Prometheus Remote-Write 2.0 Specification](https://prometheus.io/docs/specs/prw/remote_write_spec_2_0/).
   * `headers`: HTTP headers required in each request.
     * `API-Token`: Provides a Cortex XCOR API token for a restricted
       service account with write permissions. See [Prerequisites](#prerequisites) for
       more information.
     * `Chronosphere-Metrics-Validation-Response`: Controls the verbosity of details
       in the response body for partial writes that describe why invalid series were
       rejected. The Prometheus server logs partial-write responses for visibility.
       Higher verbosity levels require more processing and are best enabled temporarily
       to investigate issues. Valid values are `SHORT`, `SUMMARY`, and `DETAILED`.
       Default: `SHORT`.
   * `queue_config`: Prometheus maintains a sharded queue to batch series together
     for better performance and compression efficiency. These parameters control
     batching for processing and ingress efficiency by optimizing payload size and
     request frequency.
     * `batch_send_deadline`: Defines the period between requests to send items
       in the queue. Cortex XCOR recommends a value of `1s`.
     * `max_samples_per_send`: Limits the number of samples that Prometheus sends
       in each request. Requests can be sent with fewer samples than this limit.
       Set to `2000` to force splitting requests that would include more than 2,000
       items.

### Configure multiple remote write endpoints

You can configure multiple remote write endpoints to help in a cutover from one
target to another, or when migrating from v1 to v2. The following example demonstrates
a configuration for a Prometheus Agent writing metrics to a remote write v1 endpoint
and a remote write v2 endpoint.

```yaml theme={null}
remote_write:
  - url: https://...
    protobuf_message: prometheus.WriteRequest
    # ...

  - url: https://<COMPANY>.chronosphere.io/data/api/v1/prom/remote/write
    protobuf_message: io.prometheus.write.v2.Request
    # ...
```

## Next steps

Verify that Cortex XCOR is
[receiving metrics](/ingest/metrics-traces/collector/monitor/verify-metrics).

If you encounter issues, review the Prometheus Agent logs and
[Troubleshooting](/ingest/metrics-traces/troubleshooting).


## Related topics

- [Agent types](/ingest/pipeline/v2/fleets/agent.md)
- [Install Core Agent on Linux (Debian-based)](/ingest/pipeline/v2/fleets/agent/debian-install.md)
- [Install Core Agent on Linux (RHEL-based)](/ingest/pipeline/v2/fleets/agent/rhel-install.md)
- [Datadog](/ingest/xcor/integrations/collector/datadog.md)
- [Configure your OpenTelemetry Collector](/ingest/metrics-traces/otel/otel-ingest.md)


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