OpenTelemetry

Available for Scale plan users, the Neon OpenTelemetry integration lets you export metrics and Postgres logs to any OpenTelemetry Protocol (OTLP) compatible observability platform. This gives you the flexibility to send your Neon data to your preferred monitoring solution, whether that's New Relic, Grafana Cloud, Honeycomb, or any other OTEL-compatible service.

How it works

The integration uses the OpenTelemetry Protocol (OTLP) to securely transmit Neon metrics and Postgres logs to your chosen destination. By configuring the integration with your OTEL endpoint and authentication credentials, Neon automatically sends data from all computes in your project.

Neon metrics

The integration exports a comprehensive set of metrics including:

• Connection counts — Tracks active and idle database connections.
• Database size — Monitors total size of all databases in bytes.
• Replication delay — Measures replication lag in bytes and seconds.
• Compute metrics — Includes CPU and memory usage statistics for your compute.

Postgres logs

The Neon OpenTelemetry integration can forward Postgres logs to your destination platform. These logs provide visibility into database activity, errors, and performance.

Prerequisites

Before getting started, ensure the following:

• You have a Neon account and project. If not, see Sign up for a Neon account.
• You have an OpenTelemetry-compatible observability platform account and know your OTLP endpoint URL and authentication credentials (API key, bearer token, or basic auth).

1. Set up your observability platform

   Choose your preferred observability platform and follow the setup instructions:

   Grafana OSS with Docker OTEL LGTM

   For a cost-effective, open-source monitoring stack, you can set up the complete LGTM stack (Loki for logs, Grafana for visualization, Tempo for traces, and Mimir for metrics) with OpenTelemetry integration.

   Quick setup with Docker:

   1. Clone and start the stack:

      git clone https://github.com/grafana/docker-otel-lgtm.git
      cd docker-otel-lgtm
      docker compose up -d

   This provides:

   • Grafana at http://localhost:3000 (admin/admin)
   • OpenTelemetry Collector at http://localhost:4318 (HTTP) and localhost:4317 (gRPC)
   • Prometheus/Mimir, Loki, and Tempo for complete observability

   For detailed configuration, see the docker-otel-lgtm documentation.

   Grafana Cloud

   For a fully managed solution, see the dedicated Grafana Cloud integration guide.

   New Relic

   If you use New Relic, you'll need to sign up for an account and get your license key.

   1. Sign up for a free account at newrelic.com if you haven't already.

   2. Once signed in, you'll need your New Relic license key for authentication.

      If you're onboarding for the first time, copy the license key when it's offered to you (this is your Original account key).

      tip

      If you get stuck in New Relic's onboarding screens and don't see a way to proceed, try opening the Logs or Data Explorer pages in a new browser tab. This can sometimes let you access the main New Relic UI and continue with your setup.

      If you missed copying your license key during onboarding, you can create a new one: choose Ingest - License as the type.

      Create New Relic license key

      1. Click on your user menu in the bottom left corner.
      2. Select API Keys from the menu.

      3. Click Create a key → choose Ingest - License. Copy the key immediately (you can't view it again later).

      

      Your license key will look something like eu01xxaa1234567890abcdef1234567890NRAL (the format varies by region).

2. Open the OpenTelemetry integration

   1. In the Neon Console, navigate to the Integrations page in your Neon project.

   2. Locate the OpenTelemetry card and click Add.

      

      The sidebar form opens for you to enter your platform's details.

      

3. Select data to export

   Choose what data you want to export (at the top of the form):

   • Metrics: System metrics and database statistics (CPU, memory, connections, etc.)
   • Postgres logs: Error messages, warnings, connection events, and system notifications

   You can enable either or both options based on your monitoring needs.

4. Configure the connection

   1. Select your connection protocol: For most platforms, choose HTTP (recommended), which uses HTTP/2 for efficient data transmission. Some environments may require gRPC instead.

   2. Enter your Endpoint URL based on your platform:

      For Grafana OSS (docker-otel-lgtm):

      • http://localhost:4318 (if running locally)
      • http://your-server-ip:4318 (if running on a remote server)

      For Grafana Cloud:

      • Use your Grafana Cloud OTLP endpoint (typically https://otlp-gateway-{region}.grafana.net/otlp)
      • See the Grafana Cloud guide for details

      For New Relic:

      • US: https://otlp.nr-data.net
      • Europe: https://otlp.eu01.nr-data.net
      • See New Relic's endpoint documentation for other regions

   3. Configure authentication:

      For Grafana OSS:

      • No authentication required for local docker setup

      For Grafana Cloud:

      • Use Basic authentication with Base64 encoded <opentelemetry-instance-id>:<grafana-cloud-token>
      • Get your instance ID and API token from the Grafana Cloud Portal by clicking on the OpenTelemetry card

      For New Relic:

      • Use Bearer or API Key with your New Relic license key

      For other platforms: Choose the appropriate method:

      • Bearer: Enter your bearer token or API key
      • Basic: Provide your username and password credentials
      • API Key: Enter your API key

5. Configure resource attributes

   Neon automatically organizes your data into separate service entities: your configured service name will receive Postgres logs, while metrics are split into compute-host-metrics (infrastructure metrics) and sql-metrics (database metrics).

   1. In the Resource section, configure the service.name attribute to identify your Neon project in your observability platform. For example, you might use "neon-postgres-test" or your actual project name.

   2. Optionally, you can add additional resource attributes by providing a value in the second field to further categorize or filter your data in your observability platform.

6. Complete the setup

   Click Add to save your configuration and start the data export.

7. Verify your integration is working

   Your Neon data should start appearing in your observability platform within a few minutes.

   For Grafana (OSS and Cloud) users

   1. Access Grafana Explore: Visit http://localhost:3000 (admin/admin) or your Grafana Cloud Instance and navigate to Explore

   2. Check metrics: Select your Prometheus data source and use this query to check if data is flowing::

      neon_connection_counts

   3. Create dashboards: You can visualize using Grafana Drilldown apps or use the dashboard JSON from Grafana Cloud Documentation

   For New Relic users

   Use these queries to check if data is flowing:

   FROM Metric SELECT * SINCE 1 hour ago
   FROM Log SELECT * SINCE 1 hour ago

   Success looks similar to this:

   Metrics flowing into New Relic

   Postgres logs flowing into New Relic

   Find your data under APM & Services

   • Logs: Check your configured service name in APM & Services (e.g., neon-postgres-test)
   • Metrics: Look for the auto-created compute-host-metrics and sql-metrics services

Troubleshooting

If your data isn't appearing in your observability platform:

1. Verify your endpoint URL - Ensure the OTLP endpoint URL is correct for your platform.
2. Check authentication - Verify that your API key, bearer token, or credentials are valid and have the necessary permissions.
3. Confirm compute activity - Make sure your Neon compute is active and running queries.
4. Review platform-specific requirements - Some platforms may have specific configuration requirements for OTLP data ingestion.

Available metrics

For a complete list of all metrics and log fields exported by Neon, see the Metrics and logs reference.