The New Relic Metric API allows you to send custom dimensional metrics directly into New Relic, bypassing the need for agents in certain scenarios.
Let’s see this in action. Imagine you have a batch job that processes a large number of transactions, and for each transaction, you want to record its duration and a custom tag indicating the type of processing.
curl -X POST \
'https://metric-api.newrelic.com/metric/v1' \
-H 'Content-Type: application/json' \
-H 'Api-Key: YOUR_API_KEY' \
-d '[
{
"metrics": [
{
"name": "Custom/BatchJob/TransactionDuration",
"type": "gauge",
"value": 123.45,
"timestamp": 1678886400000,
"interval.ms": 60000,
"attributes": {
"processingType": "user_update",
"batchId": "batch_abc123"
}
}
]
}
]'
This curl command sends a single metric named Custom/BatchJob/TransactionDuration with a value of 123.45 milliseconds. It’s a gauge metric, meaning its value can go up or down. The timestamp indicates when the measurement was taken, and interval.ms specifies the duration over which this metric was collected (in this case, 60 seconds). Crucially, the attributes object allows us to attach custom dimensions like processingType and batchId. These dimensions are what make your metrics dimensional – you can later query and filter by processingType or batchId to analyze performance for specific subsets of your batch jobs.
The core problem the Metric API solves is enabling granular, custom observability without the overhead or complexity of deploying and configuring full agents for every single data source. Think about ephemeral workloads, third-party services you don’t control, or simple scripts that generate critical performance data. Instead of weaving agent instrumentation into every nook and cranny, you can have these components push metrics directly to New Relic. This is particularly useful for:
- Batch Processing: As shown, tracking the duration, success rate, or throughput of discrete batch jobs.
- Serverless Functions: Capturing execution times and custom events from Lambda, Azure Functions, or Cloud Functions.
- Third-Party Integrations: Ingesting metrics from external SaaS tools or services that expose their own metrics.
- Custom Hardware/IoT: Monitoring embedded systems or specialized hardware where traditional agents are impractical.
- Legacy Systems: Adding observability to older applications that are difficult or impossible to instrument with agents.
Internally, New Relic’s Metric API acts as a high-throughput ingestion endpoint. When you send data, it’s parsed, validated, and then routed into the New Relic time-series database. The name of the metric becomes the primary identifier, while the attributes are indexed as dimensions. This indexing is what allows for powerful querying. You’re not just getting a raw stream of numbers; you’re getting structured data that can be sliced, diced, and visualized based on any of the dimensions you provide.
The type field is important: gauge is for values that represent a current state (like CPU usage or temperature), count is for cumulative counts (like the number of requests served), and rate is for how fast a count metric is increasing over time. When sending count metrics, you’ll typically send the value as the increment since the last report and specify the interval.ms.
When you define a gauge metric, the value you send is the absolute measurement at that point in time. For count metrics, the value represents the delta or the change since the last time you reported that specific metric with the same dimensions. New Relic will then calculate the cumulative sum. If you send a count metric with value: 5 and interval.ms: 60000, and then shortly after send another count metric with value: 3 and interval.ms: 60000, New Relic understands that over 120 seconds (60 + 60), 8 events occurred.
The timestamp field is crucial for ensuring data is correctly ordered and attributed. If you omit it, New Relic will use the server’s ingestion time, which can lead to data skew if your data source experiences clock drift or network latency. Always aim to send an accurate client-side timestamp. The interval.ms is also vital, especially for count and rate metrics, as it provides context for the rate of change.
A common pitfall is sending count metrics as absolute values instead of deltas. If you want to track the total number of errors, and your job generates 10 errors, then 5 more errors, you should send value: 10 for the first report and value: 5 for the second report, not value: 10 and then value: 15. New Relic aggregates these deltas into a cumulative total.
Once your custom metrics are flowing, you can explore them in New Relic using NRQL. For example, to see the average transaction duration for user updates in your batch job:
SELECT average(Custom/BatchJob/TransactionDuration) FROM Metric WHERE processingType = 'user_update' SINCE 1 hour ago
You can also create dashboards and alerts based on these custom metrics, just as you would with any other New Relic data. The real power comes from combining these custom metrics with your existing agent data to get a holistic view of your application’s performance.
The next step after successfully ingesting custom dimensional metrics is often to alert on them.