The API endpoint to aggregate spans into buckets and compute metrics and timeseries.
This endpoint is rate limited to 300 requests per hour.
This endpoint requires the apm_read permission.
OAuth apps require the apm_read authorization scope to access this endpoint.
The list of metrics or timeseries to compute for the retrieved buckets.
aggregation [required]
enum
An aggregation function.
Allowed enum values: count,cardinality,pc75,pc90,pc95,pc98,pc99,sum,min,maxShow 2 more,avg,median
interval
string
The time buckets' size (only used for type=timeseries)
Defaults to a resolution of 150 points.
metric
string
The metric to use.
type
enum
The type of compute.
Allowed enum values: timeseries,total
default: total
filter
object
The search and filter query settings.
from
string
The minimum time for the requested spans, supports date-time ISO8601, date math, and regular timestamps (milliseconds).
default: now-15m
query
string
The search query - following the span search syntax.
default: *
to
string
The maximum time for the requested spans, supports date-time ISO8601, date math, and regular timestamps (milliseconds).
default: now
group_by
[object]
The rules for the group by.
facet [required]
string
The name of the facet to use (required).
histogram
object
Used to perform a histogram computation (only for measure facets).
Note: At most 100 buckets are allowed, the number of buckets is (max - min)/interval.
interval [required]
double
The bin size of the histogram buckets.
max [required]
double
The maximum value for the measure used in the histogram
(values greater than this one are filtered out).
min [required]
double
The minimum value for the measure used in the histogram
(values smaller than this one are filtered out).
limit
int64
The maximum buckets to return for this group by.
default: 10
missing
<oneOf>
The value to use for spans that don't have the facet used to group by.
Object 1
string
The missing value to use if there is string valued facet.
Object 2
double
The missing value to use if there is a number valued facet.
sort
object
A sort rule.
aggregation
enum
An aggregation function.
Allowed enum values: count,cardinality,pc75,pc90,pc95,pc98,pc99,sum,min,maxShow 2 more,avg,median
metric
string
The metric to sort by (only used for type=measure).
order
enum
The order to use, ascending or descending.
Allowed enum values: asc,desc
type
enum
The type of sorting algorithm.
Allowed enum values: alphabetical,measure
default: alphabetical
total
<oneOf>
A resulting object to put the given computes in over all the matching records.
Object 1
boolean
If set to true, creates an additional bucket labeled "$facet_total".
Object 2
string
A string to use as the key value for the total bucket.
Object 3
double
A number to use as the key value for the total bucket.
options
object
Global query options that are used during the query.
Note: You should only supply timezone or time offset but not both otherwise the query will fail.
timeOffset
int64
The time offset (in seconds) to apply to the query.
timezone
string
The timezone can be specified as GMT, UTC, an offset from UTC (like UTC+1), or as a Timezone Database identifier (like America/New_York).
default: UTC
type
enum
The type of resource. The value should always be aggregate_request.
Allowed enum values: aggregate_request
The response object for the spans aggregate API endpoint.
Expand All
항목
유형
설명
data
[object]
The list of matching buckets, one item per bucket.
attributes
object
A bucket values.
by
object
The key, value pairs for each group by.
<any-key>
The values for each group by.
compute
object
The compute data.
computes
object
A map of the metric name -> value for regular compute or list of values for a timeseries.
<any-key>
<oneOf>
A bucket value, can be either a timeseries or a single value.
Object 1
string
A single string value.
Object 2
double
A single number value.
Object 3
[object]
A timeseries array.
time
string
The time value for this point.
value
double
The value for this point.
id
string
ID of the spans aggregate.
type
enum
The spans aggregate bucket type.
Allowed enum values: bucket
meta
object
The metadata associated with a request.
elapsed
int64
The time elapsed in milliseconds.
request_id
string
The identifier of the request.
status
enum
The status of the response.
Allowed enum values: done,timeout
warnings
[object]
A list of warnings (non fatal errors) encountered, partial results might be returned if
warnings are present in the response.
code
string
A unique code for this type of warning.
detail
string
A detailed explanation of this specific warning.
title
string
A short human-readable summary of the warning.
{"data":[{"attributes":{"by":{"<any-key>":"undefined"},"compute":{},"computes":{"<any-key>":{"description":"undefined","type":"undefined"}}},"id":"string","type":"bucket"}],"meta":{"elapsed":132,"request_id":"MWlFUjVaWGZTTTZPYzM0VXp1OXU2d3xLSVpEMjZKQ0VKUTI0dEYtM3RSOFVR","status":"done","warnings":[{"code":"unknown_index","detail":"indexes: foo, bar","title":"One or several indexes are missing or invalid, results hold data from the other indexes"}]}}
DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comuk1.datadoghq.comddog-gov.comus2.ddog-gov.com"DD_API_KEY="<DD_API_KEY>"DD_APP_KEY="<DD_APP_KEY>"cargo run
/**
* Aggregate spans returns "OK" response
*/import{client,v2}from"@datadog/datadog-api-client";constconfiguration=client.createConfiguration();constapiInstance=newv2.SpansApi(configuration);constparams: v2.SpansApiAggregateSpansRequest={body:{data:{attributes:{compute:[{aggregation:"count",interval:"5m",type:"timeseries",},],filter:{from:"now-15m",query:"*",to:"now",},},type:"aggregate_request",},},};apiInstance.aggregateSpans(params).then((data: v2.SpansAggregateResponse)=>{console.log("API called successfully. Returned data: "+JSON.stringify(data));}).catch((error: any)=>console.error(error));
