The Neon Metrics API doesn’t just count your queries; it tracks the fundamental building blocks of your database’s activity, giving you a granular view of resource consumption.
Let’s see it in action. Imagine you’ve got a Neon project and you want to track how many times your users table is being written to. You’d use the Metrics API to fetch this data.
Here’s a simplified example of what a request might look like to get write operations for a specific table:
curl -X GET \
"https://api.neon.tech/v2/metrics/project/<YOUR_PROJECT_ID>/database/<YOUR_DATABASE_NAME>/table/users/operations?metric_name=write_operations&start_time=2023-10-27T00:00:00Z&end_time=2023-10-27T23:59:59Z&granularity=1h" \
-H "Authorization: Bearer <YOUR_API_KEY>"
This request asks for write_operations on the users table within your specified project and database, for the entire day of October 27th, 2023, broken down by hour. The response would be a time-series dataset showing the count of write operations at each hourly interval.
The core problem Neon’s Metrics API solves is making the invisible costs of database usage visible. Traditional monitoring often focuses on high-level metrics like CPU or memory usage. While important, these don’t tell you what is consuming those resources. The Metrics API allows you to drill down to specific tables, operations (reads, writes, deletes), and even individual queries (though this is more advanced). This enables you to understand which parts of your application are driving costs and performance bottlenecks.
Internally, Neon collects these metrics by instrumenting its various components. When a query executes, or a table is accessed, the relevant service emits a metric event. These events are aggregated and stored, then made accessible through the API. You have control over the scope of your monitoring: you can look at project-wide usage, database-specific activity, or even focus on individual tables. The granularity parameter is your lever for deciding the resolution of the data – from minutes to days.
The most surprising true thing about the Metrics API is how it enables proactive cost management at a granular level. Many users assume cost optimization is about reducing overall database load. However, the Metrics API reveals that a single, inefficient query hitting a frequently used table can disproportionately inflate costs. By tracking row_count changes or cpu_time_per_query for specific operations, you can identify and optimize these "rogue" queries before they become significant expenses. This shifts cost optimization from a reactive cleanup to a proactive engineering discipline.
The next concept you’ll want to explore is using these metrics to trigger automated actions, such as scaling policies or alerting.