> For the complete documentation index, see [llms.txt](https://docs.carto.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.carto.com/carto-self-hosted/operations/troubleshooting/monitoring.md).

# Monitoring & Observability

This page covers **proactive observability** for your CARTO Self-Hosted deployment: what signals matter, recommended alerting thresholds, and how to integrate with your monitoring stack.

{% hint style="info" %}
**CARTO Self-Hosted does not ship a bundled monitoring or observability stack.** CARTO services emit structured logs (JSON) to **stdout/stderr** and run as standard Kubernetes workloads, so they integrate with whatever logging, metrics, and alerting tooling you already operate. Collecting those logs and metrics and configuring dashboards and alerting at the infrastructure level is **your responsibility** — this page describes what to monitor and how to wire it into your stack.
{% endhint %}

For reactive debugging (checking pod status, enabling debug logs, or collecting a support bundle), see:

* [Debug mode and logs](/carto-self-hosted/operations/troubleshooting/debug-mode-and-logs.md)
* [Get debug information for support](/carto-self-hosted/operations/troubleshooting/get-debug-information-for-support.md)

***

## Key signals to monitor

CARTO Self-Hosted is a Kubernetes-based platform. The following signals are the most actionable for detecting and diagnosing issues before they affect users.

### Recommended alerts

| Signal             | Threshold              | Likely cause                              | Action                                        |
| ------------------ | ---------------------- | ----------------------------------------- | --------------------------------------------- |
| Pod restart count  | > 2 restarts in 10 min | OOM, crash loop, failed probe             | Check `kubectl logs` for the affected pod     |
| PostgreSQL CPU     | > 80% sustained        | Query load, missing indexes               | Tune connection pool or scale the DB instance |
| PostgreSQL storage | > 80% used             | Log growth, unvacuumed tables             | Scale storage or enable auto-grow             |
| Valkey memory      | > 85% of `maxmemory`   | Cache eviction pressure                   | Increase Valkey memory or review cache policy |
| API error rate     | > 1% of requests       | App error, bad config, downstream failure | Check `maps-api` and `workspace-api` logs     |
| Node disk usage    | > 80%                  | Image accumulation, log growth            | Clean unused images or expand disk            |

### Pod health quick check

```bash
# Overview of all CARTO pods
kubectl get pods -n <namespace>

# Watch for restarts
kubectl get pods -n <namespace> -w

# Events for a specific pod
kubectl describe pod <pod-name> -n <namespace>
```

A healthy deployment shows all pods in `Running` state with low restart counts.

***

## Integrating with your monitoring stack

Use your cloud provider's native monitoring or a third-party observability stack to collect and route the alerts above.

{% tabs %}
{% tab title="Google Cloud" %}
Use **Cloud Monitoring** with GKE system metrics enabled on your cluster. Key resources:

* [GKE observability overview](https://cloud.google.com/stackdriver/docs/solutions/gke)
* Enable **Managed Prometheus** for Kubernetes workload metrics

Recommended dashboards: GKE cluster health, PostgreSQL (Cloud SQL), Memorystore.
{% endtab %}

{% tab title="AWS" %}
Use **Amazon CloudWatch Container Insights** for EKS clusters. Key resources:

* [Container Insights for EKS](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Container-Insights-setup-EKS.html)
* Use **CloudWatch Logs** for pod log aggregation

Recommended dashboards: EKS cluster, RDS PostgreSQL, ElastiCache.
{% endtab %}

{% tab title="Azure" %}
Use **Azure Monitor** with **Container Insights** for AKS. Key resources:

* [Monitor AKS with Azure Monitor](https://learn.microsoft.com/en-us/azure/aks/monitor-aks)
* Use **Log Analytics** for log aggregation and alerts

Recommended dashboards: AKS cluster, Azure Database for PostgreSQL, Azure Cache for Redis.
{% endtab %}

{% tab title="Self-managed (Prometheus + Grafana)" %}
CARTO Self-Hosted pods expose standard Kubernetes metrics. Use the [kube-prometheus-stack](https://github.com/prometheus-community/helm-charts/tree/main/charts/kube-prometheus-stack) Helm chart for a full Prometheus + Grafana + Alertmanager setup.

Configure `ServiceMonitor` resources to scrape CARTO pods, and set up alerting rules for the thresholds in the table above.
{% endtab %}
{% endtabs %}

***

## Log aggregation

CARTO services write structured logs to stdout/stderr, which Kubernetes captures per pod. Aggregate them with:

* **GCP**: Cloud Logging (automatic with GKE)
* **AWS**: CloudWatch Logs via Container Insights or Fluent Bit
* **Azure**: Log Analytics via Container Insights
* **Self-managed**: Loki + Grafana, ELK stack, or Datadog

For collecting logs from a specific pod or generating a support bundle, see [Debug mode and logs](/carto-self-hosted/operations/troubleshooting/debug-mode-and-logs.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.carto.com/carto-self-hosted/operations/troubleshooting/monitoring.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.