Metrics

A Metric Is Really a Sequence of Data Points

A Datadog metric is a sequence of data points, each a pair of a value and a timestamp, and this sequence is stored as a time series. Sub-second timestamps are rounded to the nearest second, and if multiple values arrive for the same second, the later-arriving value overwrites the earlier one (as of August 2026; source: Metrics). Knowing this one point per second structure makes the behavior of aggregation and rollup described later much easier to internalize. The concept of a metric itself is also organized in the glossary entry on metrics. Its practical value is clear: the at-a-glance overview that lets you narrow down where things are deteriorating in a few dozen seconds even in an environment of hundreds of hosts. It is impossible for a human to grasp the overall picture by reading logs one line at a time, but the trend of a number can be told in a single graph.

Telling the Five Types Apart, from count to distribution

Metrics have types, and each means something different. At submission time there are 6 types including SET (COUNT, RATE, GAUGE, SET, HISTOGRAM, DISTRIBUTION), and within the Datadog application these are mapped to 5 types: COUNT, RATE, GAUGE, HISTOGRAM, and DISTRIBUTION (as of August 2026; source: Metric Types). This article organizes things around these 5 in-app types. COUNT is the total number of events that occurred within a fixed interval, used for request counts and database connection counts. RATE is the same events normalized to per second. GAUGE is a snapshot of the last value sent within the interval, suited to continuous quantities where measuring right now gives you this value, such as free disk space or memory usage. HISTOGRAM is a type that aggregates on the Agent side to produce derived metrics such as average, median, maximum, and 95th percentile, while DISTRIBUTION sends all raw values to the Datadog side and aggregates on the server, enabling percentile calculations across your entire infrastructure. Choosing the wrong type corrupts the numbers themselves. For example, sending a cumulative counter as a GAUGE produces a graph of the running total rather than increments, and threshold design for alerts falls apart at the root.

Integrations, Agent, DogStatsD, or API - Which to Send With

Standard metrics reflecting the health of the system are collected automatically just by enabling one of more than 1,000 integrations (as of August 2026; source: Metrics). When you want to send your own numbers, there are three main routes: a custom check in the Datadog Agent, DogStatsD sent over UDP from the application, and the HTTP API. In addition, there is a way to generate counts and statistics as metrics from logs, traces, and RUM events you have already ingested, which allows feats such as creating an error count metric without touching a single line of code. The choice of route is tied directly to maintenance cost. In-app instrumentation via DogStatsD is the standard practice, but considering first whether generating from existing logs will suffice prevents instrumentation code from scattering everywhere.

A Query Is Built from Two Stages of Aggregation

The line drawn on a graph is not the raw data itself. A query goes through the stages select a metric name → filter by tags → aggregate in time → aggregate in space, and time aggregation (rollup) is always applied. For example, when you display 4 hours, the data points are grouped into 2-minute buckets, and by default the average of each bucket is drawn (as of August 2026; source: Metrics). Besides avg, you can choose sum, min, max, or count as the aggregation method, and the rollup function lets you specify the granularity as well. Space aggregation is how you combine across hosts or tags; bundling hundreds of hosts into 4 lines by region is the typical example. The practical benefit of understanding this is that you become able to doubt the graph you are looking at. Because a momentary spike is smoothed away into the average over a wide display range, you can make the judgment yourself to switch to a max rollup when chasing peaks.

Retention Is 15 Months, but Granularity Gets Coarser

The retention period for metrics (tags and values) is 15 months (as of August 2026; source: Data Retention Periods). The significance of 15 months is that you can compare against the same period last year. For a service with seasonality, judging whether this load is abnormal or an annual regularity is not possible with 12 months; it is the 13th month onward that does the work. On the other hand, the longer the display period, the larger the time aggregation buckets become, and fine bumps are smoothed away. Because you cannot later perform a precise autopsy of that 30-second spike three months ago, the realistic division is to have monitors detect momentary anomalies on the spot, and use long-term metric retention for trend analysis and capacity planning. Note that log retention is a separate matter that depends on index settings; the glossary entry on retention sorts out the confusion.

The Multiplication of Cardinality Determines the Billable Count

The first thing to grasp in understanding custom metric billing is not the unit price but how they are counted. Datadog counts each unique combination of metric name and tag values (including the host tag) as one custom metric (as of August 2026; source: Custom Metrics). In the official documentation's example, a metric called request.Latency with 2 values for the endpoint tag and 2 values for the status tag is, by itself, 2 × 2 = 4 custom metrics.

Because of this multiplicative structure, adding a single tag whose values grow without bound, such as user_id or request_id, sends the number of time series soaring by orders of magnitude. This is the so-called cardinality accident. There is no fixed rate limit on the sending side, and the mechanism bills usage beyond the allotment, so the accident tends to be discovered on the invoice. As breakwaters, Datadog officially provides Metrics without Limits, which lets you control tag configuration after the fact, and the practice of regularly auditing the number of custom metrics. The overall picture of the pricing structure is covered in how to read the pricing.

Naming and Tag Conventions to Decide First

Naming has official constraints. A metric name must start with a letter, consist only of ASCII alphanumerics, underscores, and periods, and be at most 200 characters (under 100 recommended for readability in the UI). Other characters are converted to underscores, Unicode cannot be used, and names are case-sensitive (as of August 2026; source: Custom Metrics). How you name within those constraints is up to your team's convention, but aligning on a form that separates levels with periods, such as service.target.property, lets the metric list be read automatically as a tree structure. The convention on the tag side is even more important: unless key names are unified across all teams, such as env for environment and service for service, you will mass-produce screens that later cannot aggregate production only across sources. Because naming and tags accumulate in the history from the moment you start sending, changing them after you are running loses continuity with past data. Spend just 30 minutes deciding the convention before sending the first metric; those 30 minutes make the following years easier.

Common Misconceptions - Average of Averages, count versus rate

The first misconception is the average of averages. Averaging the per-host average latencies again does not give the correct overall average, because it adds together on equal footing the averages of hosts whose request counts differ tenfold. Where you need overall percentiles or an accurate average, the officially provided answer is to use the DISTRIBUTION type, which aggregates raw data on the server side (as of August 2026; source: Metric Types). The second misconception is confusing COUNT and RATE: COUNT is the total within the interval, RATE is the number per second. When the aggregation interval changes, the COUNT value changes but the RATE does not, so when the value on the graph is a tenth of what you expected, suspect the type and the rollup first. The third misconception is that HISTOGRAM percentiles can be composed; averaging 95th percentiles that were already aggregated on the Agent side does not give the overall 95th percentile. All of these misconceptions come down to a single point: aggregation is an operation that discards information. Being aware of what is discarded at which stage is nearly the whole of the skill of reading metrics.