> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-1d264819.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Monitorización de métricas de PostgreSQL con ClickStack

> Monitorización de métricas de PostgreSQL con ClickStack

export const TrackedLink = ({href, eventName, children, ...rest}) => {
  const handleClick = () => {
    try {
      if (typeof window !== "undefined" && window.galaxy && eventName) {
        window.galaxy.track(eventName, {
          interaction: "click"
        });
      }
    } catch (e) {}
  };
  return <a href={href} onClick={handleClick} {...rest}>
      {children}
    </a>;
};

export const Image = ({img, alt, size}) => {
  return <Frame>
      <img src={img} alt={alt} />
    </Frame>;
};

<Info>
  **Resumen**

  Supervisa las métricas de rendimiento de PostgreSQL en ClickStack con el PostgreSQL receiver de OTel. Incluye un conjunto de datos de demostración y un dashboard preconfigurado.
</Info>

<div id="existing-postgres">
  ## Integración con PostgreSQL existente
</div>

En esta sección se explica cómo configurar su instalación existente de PostgreSQL para enviar métricas a ClickStack mediante la configuración del ClickStack OTel collector con el PostgreSQL receiver.

Si desea probar la integración de métricas de PostgreSQL antes de configurar su propia instalación, puede hacerlo con nuestro demo dataset preconfigurado en la [siguiente sección](#demo-dataset).

<div id="prerequisites">
  ##### Requisitos previos
</div>

* Instancia de ClickStack en ejecución
* Instalación existente de PostgreSQL (versión 9.6 o posterior)
* Acceso de red desde ClickStack a PostgreSQL (puerto predeterminado: 5432)
* Usuario de monitorización de PostgreSQL con los permisos adecuados

<Steps>
  <Step>
    #### Asegúrese de que el usuario de monitorización tenga los permisos necesarios

    El PostgreSQL receiver requiere un usuario con acceso de lectura a las vistas de estadísticas. Otorgue el rol `pg_monitor` a su usuario de monitorización:

    ```sql theme={null}
    GRANT pg_monitor TO your_monitoring_user;
    ```
  </Step>

  <Step>
    #### Cree una configuración personalizada del OpenTelemetry Collector

    ClickStack le permite ampliar la configuración base del OpenTelemetry Collector montando un archivo de configuración personalizado y estableciendo una variable de entorno.

    Cree `postgres-metrics.yaml`:

    ```yaml theme={null}
    receivers:
      postgresql:
        endpoint: postgres-host:5432
        transport: tcp
        username: otel_monitor
        password: ${env:POSTGRES_PASSWORD}
        databases:
          - postgres
          - your_application_db # Reemplace por los nombres reales de sus bases de datos
        collection_interval: 30s
        tls:
          insecure: true

    processors:
      resourcedetection:
        detectors: [env, system, docker]
        timeout: 5s
      batch:
        timeout: 10s
        send_batch_size: 10000

    exporters:
      clickhouse:
        endpoint: tcp://localhost:9000
        database: default
        ttl: 96h

    service:
      pipelines:
        metrics/postgres:
          receivers: [postgresql]
          processors: [resourcedetection, batch]
          exporters: [clickhouse]
    ```

    <Note>
      La configuración `tls: insecure: true` desactiva la verificación de SSL para entornos de desarrollo o pruebas. En PostgreSQL de producción con SSL habilitado, elimine esta línea o configure los certificados adecuados.
    </Note>
  </Step>

  <Step>
    #### Despliegue ClickStack con una configuración personalizada

    Monte su configuración personalizada:

    ```bash theme={null}
    docker run -d \
      --name clickstack-postgres \
      -p 8123:8123 -p 9000:9000 -p 4317:4317 -p 4318:4318 \
      -e HYPERDX_API_KEY=your-api-key \
      -e CLICKHOUSE_PASSWORD=your-clickhouse-password \
      -e POSTGRES_PASSWORD=secure_password_here \
      -e CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml \
      -v "$(pwd)/postgres-metrics.yaml:/etc/otelcol-contrib/custom.config.yaml:ro" \
      clickhouse/clickstack:latest
    ```
  </Step>

  <Step>
    #### Verifique la recopilación de métricas

    Una vez configurado, inicie sesión en HyperDX y verifique que las métricas se estén recibiendo:

    1. Vaya a Metrics Explorer
    2. Busque métricas que empiecen por postgresql (por ejemplo, postgresql.backends, postgresql.commits)
    3. Debería ver puntos de datos de métricas en el intervalo de recopilación configurado

    Una vez que las métricas se estén recibiendo, continúe con la sección [Dashboards y visualización](#dashboards) para importar el dashboard preconfigurado.
  </Step>
</Steps>

<div id="demo-dataset">
  ## Conjunto de datos de demostración
</div>

Para los usuarios que quieran probar la integración de métricas de PostgreSQL antes de configurar sus sistemas en producción, proporcionamos un conjunto de datos pregenerado con patrones realistas de métricas de PostgreSQL.

<Info>
  **Solo métricas a nivel de base de datos**

  Este conjunto de datos de demostración incluye únicamente métricas a nivel de base de datos para mantener la muestra de datos ligera. Las métricas de tablas e índices se recopilan automáticamente al supervisar una base de datos PostgreSQL real.
</Info>

<Steps>
  <Step>
    #### Descargar el conjunto de datos de muestra de métricas

    Descargue los archivos de métricas pregenerados (24 horas de métricas de PostgreSQL con patrones realistas):

    ```bash theme={null}
    # Descargar métricas gauge (conexiones, tamaño de la base de datos)
    curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/postgres/postgres-metrics-gauge.csv

    # Descargar métricas sum (commits, rollbacks, operaciones)
    curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/postgres/postgres-metrics-sum.csv
    ```

    El conjunto de datos incluye patrones realistas:

    * **Pico matutino de conexiones (08:00)** - Hora punta de inicios de sesión
    * **Problema de rendimiento de la caché (11:00)** - Pico de Blocks\_read
    * **Error de la aplicación (14:00-14:30)** - La tasa de rollback alcanza picos del 15 %
    * **Incidentes de deadlock (14:15, 16:30)** - Deadlocks poco frecuentes
  </Step>

  <Step>
    #### Iniciar ClickStack

    Inicie una instancia de ClickStack:

    ```bash theme={null}
    docker run -d --name clickstack-postgres-demo \
      -p 8080:8080 -p 4317:4317 -p 4318:4318 \
      clickhouse/clickstack-all-in-one:latest
    ```

    Espere aproximadamente 30 segundos hasta que ClickStack se inicie por completo.
  </Step>

  <Step>
    #### Cargar métricas en ClickStack

    Cargue las métricas directamente en ClickHouse:

    ```bash theme={null}
    # Cargar métricas gauge
    cat postgres-metrics-gauge.csv | docker exec -i clickstack-postgres-demo \
      clickhouse-client --query "INSERT INTO otel_metrics_gauge FORMAT CSVWithNames"

    # Cargar métricas sum
    cat postgres-metrics-sum.csv | docker exec -i clickstack-postgres-demo \
      clickhouse-client --query "INSERT INTO otel_metrics_sum FORMAT CSVWithNames"
    ```
  </Step>

  <Step>
    #### Verificar métricas en HyperDX

    Una vez cargadas, la forma más rápida de ver sus métricas es mediante el dashboard preconfigurado.

    Continúe en la sección [Dashboards y visualización](#dashboards) para importar el dashboard y ver varias métricas de PostgreSQL a la vez.

    <Info>
      **Visualización de la zona horaria**

      HyperDX muestra los timestamps en la zona horaria local de su navegador. Los datos de demostración abarcan **2025-11-10 00:00:00 - 2025-11-11 00:00:00 (UTC)**. Establezca el intervalo de tiempo en **2025-11-09 00:00:00 - 2025-11-12 00:00:00** para asegurarse de ver las métricas de demostración independientemente de su ubicación. Una vez que vea las métricas, puede reducir el intervalo a un período de 24 horas para obtener visualizaciones más claras.
    </Info>
  </Step>
</Steps>

<div id="dashboards">
  ## Dashboards y visualización
</div>

Para ayudarte a empezar a monitorear PostgreSQL con ClickStack, proporcionamos visualizaciones esenciales de las métricas de PostgreSQL.

<Steps>
  <Step>
    #### <TrackedLink href={'/es/examples/postgres-metrics-dashboard.json'} download="postgres-metrics-dashboard.json" eventName="docs.postgres_metrics_monitoring.dashboard_download">Descargar</TrackedLink> la configuración del dashboard
  </Step>

  <Step>
    #### Importa el dashboard preconfigurado

    1. Abre HyperDX y ve a la sección Dashboards
    2. Haz clic en **Import Dashboard** en la esquina superior derecha, en el menú de los tres puntos

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-1d264819/KBMpfHRObzlPpAN0/images/clickstack/import-dashboard.png?fit=max&auto=format&n=KBMpfHRObzlPpAN0&q=85&s=6e43e9f6e79839ce7706f4ab0f592964" alt="Botón para importar dashboard" width="3024" height="556" data-path="images/clickstack/import-dashboard.png" />

    3. Sube el archivo `postgres-metrics-dashboard.json` y haz clic en **Finish Import**

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-1d264819/KBMpfHRObzlPpAN0/images/clickstack/postgres/import-dashboard.png?fit=max&auto=format&n=KBMpfHRObzlPpAN0&q=85&s=8c0c762ee264c554f89e71a22b3a26fb" alt="Cuadro de diálogo para finalizar la importación" width="3808" height="1910" data-path="images/clickstack/postgres/import-dashboard.png" />
  </Step>

  <Step>
    #### Ver el dashboard

    El dashboard se creará con todas las visualizaciones preconfiguradas:

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-1d264819/KBMpfHRObzlPpAN0/images/clickstack/postgres/postgres-metrics-dashboard.png?fit=max&auto=format&n=KBMpfHRObzlPpAN0&q=85&s=159d0daebca34ee1ed89b242c6d2e961" alt="Dashboard de métricas de PostgreSQL" width="3808" height="1910" data-path="images/clickstack/postgres/postgres-metrics-dashboard.png" />

    <Note>
      Para el demo dataset, establece el intervalo de tiempo en **2025-11-10 00:00:00 - 2025-11-11 00:00:00 (UTC)** (ajústalo según tu zona horaria local). El dashboard importado no tendrá ningún intervalo de tiempo especificado de forma predeterminada.
    </Note>
  </Step>
</Steps>

<div id="troubleshooting">
  ## Solución de problemas
</div>

<div id="troubleshooting-not-loading">
  ### La configuración personalizada no se carga
</div>

Verifique que la variable de entorno esté configurada:

```bash theme={null}
docker exec <container-name> printenv CUSTOM_OTELCOL_CONFIG_FILE
```

Comprueba que el archivo de configuración personalizado esté montado:

```bash theme={null}
docker exec <container-name> cat /etc/otelcol-contrib/custom.config.yaml
```

<div id="no-metrics">
  ### No se muestran métricas en HyperDX
</div>

Verifica que PostgreSQL sea accesible:

```bash theme={null}
docker exec <clickstack-container> psql -h postgres-host -U otel_monitor -d postgres -c "SELECT 1"
```

Revise los logs del OTel collector:

```bash theme={null}
docker exec <container> cat /etc/otel/supervisor-data/agent.log | grep -i postgres
```

<div id="auth-errors">
  ### Errores de autenticación
</div>

Verifique que la contraseña esté configurada correctamente:

```bash theme={null}
docker exec <clickstack-container> printenv POSTGRES_PASSWORD
```

Probar las credenciales directamente:

```bash theme={null}
psql -h postgres-host -U otel_monitor -d postgres -c "SELECT version();"
```

<div id="next-steps">
  ## Siguientes pasos
</div>

* Configura [alertas](/es/clickstack/features/alerts) para umbrales críticos (límites de conexión, tasas elevadas de rollback y tasas bajas de aciertos de caché)
* Habilita la monitorización a nivel de consulta con la extensión `pg_stat_statements`
* Supervisa varias instancias de PostgreSQL duplicando la configuración del receiver con distintos endpoints y nombres de servicio

<div id="going-to-production">
  ## Paso a producción
</div>

Esta guía amplía el OpenTelemetry Collector integrado de ClickStack para ofrecer una configuración rápida. Para implementaciones en producción, recomendamos ejecutar su propio OTel Collector y enviar los datos al endpoint de OTLP de ClickStack. Consulte [Envío de datos de OpenTelemetry](/es/clickstack/ingesting-data/opentelemetry) para la configuración de producción.